=head1 NAME

Fey::ORM::Manual::Intro - Introduction to Fey::ORM

=head1 DESCRIPTION

This documentation will walk you through the steps needed to start
using L<Fey::ORM>.

You should go ahead and make sure you have C<Fey::Loader> installed if
you want to follow along with this introduction.

=head1 SAMPLE SCHEMA

In these examples, we will use a very simple schema for a web forum
type of application. Here is that schema for SQLite:

  CREATE TABLE User (
      user_id   integer  not null  primary key autoincrement,
      username  text     not null,
      email     text     null,
      group_id  integer  not null,
      UNIQUE (username)
  );

  CREATE TABLE "Group" (
      group_id   integer  not null  primary key autoincrement,
      name       text     not null,
      UNIQUE (name)
  );

  CREATE TABLE Message (
      message_id    integer     not null  primary key autoincrement,
      message       text        not null  default 'Some message ''" text',
      message_date  date        not null  default current_date,
      parent_message_id  integer  null,
      user_id       integer     not null
  );

=head1 LOADING A SCHEMA

To do anything with L<Fey::ORM>, you need to define a schema using
C<Fey::Schema> and C<Fey::Table>. While you can do this by using the
C<Fey> API directly, it's much easier to load a schema from a DBMS
using C<Fey::Loader>:

  my $schema = Fey::Loader->new( dbh => $dbh )->make_schema();

The loader will create tables, columns, views, and foreign keys that
match the schema found in the DBMS.

=head1 YOUR SCHEMA CLASS

You need to define a schema class which contains the schema you've
loaded.

Your schema class will also contain your C<Fey::DBIManager> object,
which manages your database handle(s). L<Fey::ORM> is smart enough to
connect a table-based class to your schema class automatically, and
from that find an appropriate database handle when it needs to execute
queries.

To define your schema class you'll use the C<Fey::Schema::Class>:

  package Forum::Model::Schema;

  use Fey::ORM::Schema;

  has_schema $schema;

Of course, you need to create a C<Fey::Schema> object to pass to
C<has_schema()>. You might as well create a C<Fey::DBIManager::Source>
object along the way.

  package Forum::Model::User;

  use Fey::DBIManager;
  use Fey::DBIManager::Source;
  use Fey::Loader;
  use Fey::ORM::Schema;

  my $source = Fey::DBIManager::Source->new( dsn => 'dbi:SQLite:dbname=/tmp/forum.sqlite' );

  my $schema = Fey::Loader->new( dbh => $source->dbh() )->make_schema();

  has_schema $schema;

  __PACKAGE__->DBIManager()->add_source($source);

Now you can use C<Forum::Model::Schema> in other classes to get the
C<Fey::Table> objects from your schema.

=head1 YOUR TABLE CLASSES

With L<Fey::ORM>, each of your model classes has an associated
C<Fey::Table> object. For example, the User table would belong to the
C<Forum::Model::User> class.

  package Forum::Model::User;

  use Forum::Model::Schema;

  use Fey::ORM::Table;

  has_table( Forum::Model::Schema->Schema()->table('User') );

When you call C<has_table>, L<Fey::ORM> does a number of things behind
the scenes. It defines Moose attributes for each column in the
associated table and makes your class a subclass of
L<Fey::Object::Table>.

At this point, we can start using C<Forum::Model::User> for basic CRUD
operations. For example, to retrieve an existing user, you can simply
pass any unique key to the constructor:

  my $user = Forum::Model::User->new( user_id => 1 );
  my $user = Forum::Model::User->new( username => 'faye' );

L<Fey::Object::Table> knows that both of those columns represent
unique keys for the associated table, and so will be able to load the
associated user from the DBMS, if it exists.

You can also modify or delete existing users:

  $user->update( username => 'bubba' );

  $user->delete();

Finally, you can create new users:

  my $user = Fey::Model::User->insert( username => 'autarch',
                                       email    => 'autarch@urth.org',
                                     );

You'll notice that we didn't provide a C<user_id> value. When a column
is auto-incremented, as is the case with C<User.user_id>,
L<Fey::Object::Table> is smart enough to notice and simply retrieve
the value after the insert.

When your class calls C<has_table()>, it also gets a bunch of
attributes for free, one for each column in the associated table:

  print $user->username();

These attributes are only loaded from the DBMS once, and then are
cached. Calling C<< $user->update() >> will clear any attributes being
updated so they are reloaded from the DBMS when they are next
accessed.

Of course, L<Fey::ORM> actually loads all of the columns at once,
rather than once per column, since anytihng else would be grossly
inefficient.

=head1 INFLATE/DEFLATE

L<Fey::ORM> allows you to define an inflator and/or deflator for each
column. An inflator is used to convert the value received from the
database into some other value, usually an object. A deflator does the
opposite, turning the object into a value suitable for the DBMS when
doing updates or inserts. The inflator and deflator are both declared
with C<transform()>:

  package Forum::Model::User;

  use Forum::Model::Schema;

  use Email::Address;
  use Fey::ORM::Table;

  has_table( Forum::Model::Schema->Schema()->table('User') );

  transform 'email'
      => inflate { defined $_[1] ? Email::Address->new( $_[1] ) : undef }
      => deflate { defined $_[1] && blessed $_[1] ? $_[1]->address() : $_[1] };

The C<transform()> above inflates the email column's value to an
C<Email::Address> object, if it defined. Similarly, the deflator takes
an C<Email::Address> object and converts it back to a string.

The inflator and deflator are both called as methods on the object or
class, which is why they use C<$_[1]> to get at the email. The
inflator has to handle the case the email address is undefined, since
the column is nullable. The deflator handles the case where it is
passed a plain scalar, which allows you to pass a plain string or
undef to C<< $user->update() >> or C<< $user->insert() >>.

=head1 HAS-A RELATIONSHIPS

With L<Fey::ORM>, you can also declare has-a relationships with other
tables as C<has_one()> or C<has_many()>:

  package Forum::Model::Message;

  use Forum::Model::Schema;

  use Fey::ORM::Table;

  has_one( Forum::Model::Schema->Schema()->table('User') );

This creates a C<< $message->user() >> attribute which returns the
associated user object. If the source table's column is nullable, the
attribute may simply return false. In the case of this particular
relationship, that should never happen, since C<Message.user_id> is
not nullable.

By default, the name of the attribute created via C<has_one()> is
simple C<< lc $table->name() >>. Depending on your table naming
scheme, this may or may not work. If two tables have more than one
foreign key between them, you will also need to specify the foreign
key to use explicitly:

  has_one 'user' =>
      ( table => Forum::Model::Schema->Schema()->table('User'),
        fk    => ...,
      );

Also by default, C<has_one()> attributes cache the result of the
lookup, so that future calls to the same attribute method return the
object already created.

The C<has_many()> declaration works more or less exactly like
C<has_one()>:

  package Forum::Model::User;

  use Forum::Model::Schema;

  use Fey::ORM::Table;

  has_many( Forum::Model::Schema->Schema()->table('Message') );

The default name is still C<< lc $table->name() >>. In the case of the
naming scheme in this example, that doesn't really work, so we should
provide an explicit name:

  has_many 'messages' =>
      ( table => Forum::Model::Schema->Schema()->table('Message') );

Now we have a C<< $user->messages() >> method (not an
attribute!). This method returns a C<Fey::Object::Iterator> which
iterates over the user's messages.

  my $messages = $user->messages();

  while ( my $message = $messages->next() )
  {
      print $message->message_id();
  }

By default, C<has_many()> creates a I<non-caching> iterator. The
reason for this is that it cannot know how many foreign objects could
be created, and in the case where this is a very large number, caching
could be very problematic. However, you can turn caching on
explicitly:

  has_many 'messages' =>
      ( table => Forum::Model::Schema->Schema()->table('Message'),
        cache => 1,
      );

In this case, a C<< $user->messages() >> I<attribute> is created which
returns a C<Fey::Object::Iterator::Caching> object. Subsequent calls
to this attribute will return the same iterator, and that iterator in
turn caches any objects it has already created.

L<Fey::ORM> can also handle self-referential relationships:

  package Forum::Model::Message;

  use Forum::Model::Schema;

  use Fey::ORM::Table;

  has_one 'parent_message' =>
      ( table => Forum::Model::Schema->Schema()->table('Message') );

  has_many 'child_messages' =>
      ( table => Forum::Model::Schema->Schema()->table('Message') );

=head2 Arbitrary Relationships

L<Fey::ORM>, also allows you to declare arbitrary relationships
between any two tables by providing a SELECT statement to C<has_one()>
or C<has_many()>, rather than a C<Fey::FK> object. Here is a
straightforward example:

  package Forum::Model::Message;

  use Fey::Placeholder;
  use Forum::Model::Schema;

  use Fey::ORM::Table;

  my $schema = Forum::Model::Schema->Schema();
  my $message_table = $schema->table('Message');

  #   SELECT *
  #     FROM Message
  #    WHERE parent_message_id = ?
  # ORDER BY message_date DESC
  #    LIMIT 1
  my $select =
      $schema->SQLFactoryClass()->new_select()
             ->select( $message_table )
             ->from( $message_table )
             ->where( $message_table->column('user_id'),
                      '=', Fey::Placeholder->new() )
             ->order_by( $message_table->column('message_date'), 'DESC' )
             ->limit(1);

  has_one 'most_recent_child' =>
      ( table       => $schema->table('Message')
        select      => $select,
        bind_params => sub { $_[0]->message_id() },
      );

With this declaration, the C<Forum::Model::Message> class now has an a
C<< $message->most_recent_child() >> attribute. This attribute will
return the most recent child message of the C<$message> object, if
there is one to return. You can enable or disable caching of this data
just as with the other form of C<has_one()>.

You can use this arbitrary declaration to traverse your schema in
arbitrary ways. For example, we might want to find all the messages
for a group:

  package Forum::Model::Group;

  use Fey::Placeholder;
  use Forum::Model::Schema;

  use Fey::ORM::Table;

  my $schema = Forum::Model::Schema->Schema();
  my $message_table = $schema->table('Message');

  #   SELECT Message.*
  #     FROM Message
  #          JOIN User USING (user_id)
  #          JOIN Group USING (group_id)
  #    WHERE Group.group_id = ?
  # ORDER BY Message.message_date DESC

  my $select =
      $schema->SQLFactoryClass()->new_select()
             ->select( $message_table )
             ->from( $message_table, $user_table )
             ->from( $user_table, $group_table )
             ->where( $group_table->column('group_id'),
                      '=', Fey::Placeholder->new() )
             ->order_by( $message_table->column('message_date'), 'DESC' );

  has_many 'messages' =>
      ( table       => $message_table,
        select      => $select,
        bind_params => sub { $_[0]->group_id() },
      );

=head1 USING Fey

One of the advantages of using L<Fey::ORM> is that you can use the
power of the core Fey SQL generation tools with your classes:

  package Forum::Model::Message;

  use DateTime;
  use Fey::Object::Iterator;

  sub RecentMessages
  {
      my $class = shift;

      my $schema = $class->SchemaClass()->Schema();

      my $select = $class->SchemaClass()->SQLFactoryClass()->new_select();

      my ( $message_t, $user_t ) = $schema->tables( 'Message', 'User' )

      $select->select( $message_t, $user_t )
             ->from( $message_t, $user_t )
             ->where( $message_t->column('message_date'), '>=',
                      DateTime->today()->subtract( days => 7 )->strftime( '%Y-%m-%d' ) );

      my $dbh = $class->_dbh($select);

      my $sth = $dbh->prepare( $select->sql($dbh) );

      return
          Fey::Object::Iterator->new
              ( classes     => [ $class->meta()->ClassForTable( $message_t, $user_t ) ],
                handle      => $sth,
                bind_params => [ $select->bind_params() ],
              );
  }

This is all a bit verbose for now, but future versions of L<Fey::ORM>
will probably provide sugar to trim it down.

=head1 OBJECT CACHING

L<Fey::ORM> provides a built-in simple in-memory object caching
system. This system is very handy in a webapp environment where you
may end up trying to load the same objects more than once in the same
request.

L<Fey::ORM>'s caching makes no attempt to expire objects, so you need
to be careful to clear the object cache regularly to avoid stale
data. In practice, I've found that a good way to do this is to simply
clear the cache once per "request". In a web app environment, this is
simple to do. If you are writing a daemon or other long-running
application, you will need to find a similar place to clear the cache.

You can turn on caching for all of your table-based classes through
your schema class:

  Forum::Model::Schema->EnableObjectCaches();

Similarly, you can clear the cache for all the table-based classes
through your schema class:

  Forum::Model::Schema->ClearObjectCaches();

You can also enable or disable caching on a per-class basis, as well
as clear the cache for just one class at a time.

If you were writing a Catalyst application and wanted to ensure that
the cache was cleared at the beginning of each request, there are a
number of places to do this. If you have a base controller class, you
can do this in its C<begin()> method, as long as all your controllers
inherit from that class:

  package MyApp::Controller::Base;

  sub begin : Private
  {
      my $self = shift;
      my $c    = shift;

      MyApp::Model::Schema->ClearObjectCaches();

      ...
  }

You could also provide your own C<Catalyst::Request> subclass and do
the cache clearing in its constructor, or in a plugin of some sort.

=head1 AUTHOR

Dave Rolsky, <autarch@urth.org>

=head1 COPYRIGHT & LICENSE

Copyright 2006-2008 Dave Rolsky, All Rights Reserved.

This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself. The full text of the license
can be found in the LICENSE file included with this module.

=cut