# Copyright 2001-2005 Six Apart.# SCRiPTMAFiA 2005 - THE DiRTY HANDS ON YOUR SCRiPTS## $Id: Object.pm 10831 2005-03-30 23:27:06Z ezra $package MT::Object;use strict;use MT::ObjectDriver;use MT::ErrorHandler;@MT::Object::ISA = qw( MT::ErrorHandler );## Magic.sub install_properties {    my $class = shift;    no strict 'refs';    ${"${class}::__properties"} = shift;}sub properties {    my $this = shift;    my $class = ref($this) || $this;    no strict 'refs';    ${"${class}::__properties"};}## Drivers.use vars qw( $DRIVER );sub set_driver { $DRIVER = MT::ObjectDriver->new($_[1]) }sub driver { $DRIVER }sub set_callback_routine { shift; $DRIVER->set_callback_routine(@_) }## Callbackssub add_callback {    my $class = shift;    my($meth, $priority, $plugin, $code) = @_;    if (ref$code ne 'CODE') {	return $class->error("4th argument to add_callback must be "			     . "a perl CODE reference");    }    MT->add_callback($class . '::' . $meth, $priority, $plugin, $code);    1;}## Construction/initialization.sub new {    my $class = shift;    my $obj = bless {}, $class;    $obj->init(@_);}sub init {    my $obj = shift;    my %arg = @_;    $obj->{'column_values'} = {};    $obj;}sub clone {    my $obj = shift;    my $clone = ref($obj)->new();    $clone->set_values($obj->column_values);    $clone;}sub column_names {    my $obj = shift;    my $props = $obj->properties;    my @cols = @{ $props->{columns} };    push @cols, qw( created_on created_by modified_on modified_by )        if $props->{audit};    \@cols;}sub datasource { $_[0]->properties->{datasource} }sub column_values { $_[0]->{'column_values'} }sub column {    my $obj = shift;    my($col, $value) = @_;    return unless defined $col;    $obj->{'column_values'}->{$col} = $value if defined $value;    $obj->{'column_values'}->{$col};}sub created_on_obj {    my $obj = shift;    if (my $ts = $obj->created_on) {        my $blog;        if ($obj->isa('MT::Blog')) {            $blog = $obj;        } else {            if (my $blog_id = $obj->blog_id) {                require MT::Blog;                $blog = MT::Blog->load($blog_id);            }        }        my($y, $mo, $d, $h, $m, $s) = $ts =~ /(\d\d\d\d)[^\d]?(\d\d)[^\d]?(\d\d)[^\d]?(\d\d)[^\d]?(\d\d)[^\d]?(\d\d)/;        require MT::DateTime;        my $four_digit_offset;        if ($blog) {            $four_digit_offset = sprintf('%.02d%.02d', int($blog->server_offset),                                        60 * abs($blog->server_offset                                                 - int($blog->server_offset)));        }        return new MT::DateTime(year => $y, month => $mo, day => $d,                                hour => $h, minute => $m, second => $s,                                time_zone => $four_digit_offset);    }    undef;}sub set_values {    my $obj = shift;    my($values) = @_;    my @cols = @{ $obj->column_names };    for my $col (@cols) {        next unless exists $values->{$col};        $obj->column($col, $values->{$col});    }}sub _mk_passthru {    my($method) = @_;    sub {        my($this) = $_[0];        die "No ObjectDriver defined" unless defined $DRIVER;        my $class = ref($this) || $this;	if (wantarray) {	    my @result = eval {		my @rc = $DRIVER->$method(@_);		@rc or return $this->error( $DRIVER->errstr );		return @rc;	    }; if ($@) {		$@ =~ s/\s*at.*$//s;		require Carp;		Carp::croak($@);	    }	    return @result;	} else {	    my $result = eval {		my $rc = $DRIVER->$method(@_);		defined $rc or return $this->error( $DRIVER->errstr );		return $rc;	    }; if ($@) {		$@ =~ s/\s*at.*$//s;		require Carp;		Carp::croak($@);	    }	    return $result;	}    }}{    no strict 'refs';    *load = _mk_passthru('load');    *load_iter = _mk_passthru('load_iter');    *save = _mk_passthru('save');    *remove = _mk_passthru('remove');    *remove_all = _mk_passthru('remove_all');    *exists = _mk_passthru('exists');    *count = _mk_passthru('count');    *count_group_by = _mk_passthru('count_group_by');}sub set_by_key {    my $class = shift;    my ($key, $value) = @_;    my $obj = $class->load($key);    $obj ||= new $class;    $obj->set_values($key);    foreach my $col (keys %$value) {        $obj->column($col, $value->{$col});    }    $obj->save();    $obj;}sub DESTROY { }use vars qw( $AUTOLOAD );sub AUTOLOAD {    my $obj = $_[0];    (my $col = $AUTOLOAD) =~ s!.+::!!;    no strict 'refs';    my $class = ref($obj);    *$AUTOLOAD = sub {        shift()->column($col, @_);    };    goto &$AUTOLOAD;}1;__END__=head1 NAMEMT::Object - Movable Type base class for database-backed objects=head1 SYNOPSISCreating an I<MT::Object> subclass:    package MT::Foo;    use strict;    use MT::Object;    @MT::Foo::ISA = qw( MT::Object );    __PACKAGE__->install_properties({        columns => [            'id', 'foo',        ],        indexes => {            foo => 1,        },        datasource => 'foo',    });Using an I<MT::Object> subclass:    use MT;    use MT::Foo;    ## Create an MT object to load the system configuration and    ## initialize an object driver.    my $mt = MT->new;    ## Create an MT::Foo object, fill it with data, and save it;    ## the object is saved using the object driver initialized above.    my $foo = MT::Foo->new;    $foo->foo('bar');    $foo->save        or die $foo->errstr;=head1 DESCRIPTIONI<MT::Object> is the base class for all Movable Type objects that will beserialized/stored to some location for later retrieval; this location couldbe a DBM file, a relational database, etc.Movable Type objects know nothing about how they are stored--they know onlyof what types of data they consist, the names of those types of data (theircolumns), etc. The actual storage mechanism is in the I<MT::ObjectDriver>class and its driver subclasses; I<MT::Object> subclasses, on the other hand,are essentially just standard in-memory Perl objects, but with a little extraself-knowledge.This distinction between storage and in-memory representation allows objectsto be serialized to disk in many different ways--for example, an object couldbe stored in a MySQL database, in a DBM file, etc. Adding a new storage methodis as simple as writing an object driver--a non-trivial task, to be sure, butone that will not require touching any other Movable Type code.=head1 SUBCLASSINGCreating a subclass of I<MT::Object> is very simple; you simply need todefine the properties and metadata about the object you are creating. Startby declaring your class, and inheriting from I<MT::Object>:    package MT::Foo;    use strict;    use MT::Object;    @MT::Foo::ISA = qw( MT::Object );Then call the I<install_properties> method on your class name; an easy wayto get your class name is to use the special I<__PACKAGE__> variable:    __PACKAGE__->install_properties({        columns => [            'id', 'foo',        ],        indexes => {            foo => 1,        },        datasource => 'foo',    });I<install_properties> performs the necessary magic to install the metadataabout your new class in the MT system. The method takes one argument, a hashreference containing the metadata about your class. That hash reference canhave the following keys:=over 4=item * columnsThe definition of the columns (fields) in your object. Column names are alsoused for method names for your object, so your column name should notcontain any strange characters. (It could also be used as part of the name ofthe column in a relational database table, so that is another reason to keepcolumn names somewhat sane.)The value for the I<columns> key should be a reference to an array containingthe names of your columns.=item * indexesSpecifies the column indexes on your objects; this only has consequence forsome object drivers (DBM, for example), where indexes are not automaticallymaintained by the datastore (as they are in a relational database).The value for the I<indexes> key should be a reference to a hash containingcolumn names as keys, and the value C<1> for each key--each key representsa column that should be indexed.B<NOTE:> with the DBM driver, if you do not set up an index on a column youwill not be able to select objects with values matching that column using theI<load> and I<load_iter> interfaces (see below).=item * auditAutomatically adds bookkeeping capabilities to your class--each object willtake on four new columns: I<created_on>, I<created_by>, I<modified_on>, andI<modified_by>. These columns will be filled automatically with the propervalues.B<NOTE:> I<created_by> and I<modified_by> are not currently used.=item * datasourceThe name of the datasource for your class. The datasource is a name uniquelyidentifying your class--it is used by the object drivers to construct tablenames, file names, etc. So it should not be specific to any one driver.=back=head1 USAGE=head2 System InitializationBefore using (loading, saving, removing) an I<MT::Object> class and itsobjects, you must always initialize the Movable Type system. This is donewith the following lines of code:    use MT;    my $mt = MT->new;Constructing a new I<MT> objects loads the system configuration from theF<mt.cfg> configuration file, then initializes the object driver that willbe used to manage serialized objects.=head2 Creating a new objectTo create a new object of an I<MT::Object> class, use the I<new> method:    my $foo = MT::Foo->new;I<new> takes no arguments, and simply initializes a new in-memory object.In fact, you need not ever save this object to disk; it can be used as apurely in-memory object.=head2 Setting and retrieving column valuesTo set the column value of an object, use the name of the column as a methodname, and pass in the value for the column:    $foo->foo('bar');The return value of the above call will be C<bar>, the value to which you haveset the column.To retrieve the existing value of a column, call the same method, but withoutan argument:    $foo->fooThis returns the value of the I<foo> column from the I<$foo> object.=head2 Saving an objectTo save an object using the object driver, call the I<save> method:    $foo->save;On success, I<save> will return some true value; on failure, it will returnC<undef>, and you can retrieve the error message by calling the I<errstr>method on the object:    $foo->save        or die "Saving foo failed: ", $foo->errstr;If you are saving objects in a loop, take a look at the L<Note on ObjectLocking>.=head2 Loading an existing object or objectsYou can load an object from the datastore using the I<load> method. I<load>is by far the most complicated method, because there are many different waysto load an object: by ID, by column value, by using a join with another typeof object, etc.In addition, you can load objects either into an array (I<load>), or by usingan iterator to step through the objects (I<load_iter>).I<load> has the following general form:    my @objects = CLASS->load(\%terms, \%arguments);I<load_iter> has the following general form:    my $iter = CLASS->load_iter(\%terms, \%arguments);Both methods share the same parameters; the only difference is the manner inwhich they return the matching objects.If you call I<load> in scalar context, only the first row of the array