X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FRelationship.pm;h=3a2310852523a11e6269a9a818e7f8c88e985f7e;hb=7f613f3abf507feffb920890d245d325520d55c0;hp=c479e4c707021fae6dbc5b37011a6ea2e94fc4ed;hpb=d2113a6853f7ae702b922d936f5ac4d323c7da65;p=dbsrgits%2FDBIx-Class.git

diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm
index c479e4c..3a23108 100644
--- a/lib/DBIx/Class/Relationship.pm
+++ b/lib/DBIx/Class/Relationship.pm
@@ -13,15 +13,15 @@ __PACKAGE__->load_own_components(qw/
   Base
 /);
 
-=head1 NAME 
+=head1 NAME
 
 DBIx::Class::Relationship - Inter-table relationships
 
 =head1 SYNOPSIS
 
-  MyDB::Schema::Actor->has_many('actorroles' => 'MyDB::Schema::ActorRole', 
+  MyDB::Schema::Actor->has_many('actorroles' => 'MyDB::Schema::ActorRole',
                                 'actor');
-  MyDB::Schema::Role->has_many('actorroles' => 'MyDB::Schema::ActorRole', 
+  MyDB::Schema::Role->has_many('actorroles' => 'MyDB::Schema::ActorRole',
                                 'role');
   MyDB::Schema::ActorRole->belongs_to('role' => 'MyDB::Schema::Role');
   MyDB::Schema::ActorRole->belongs_to('actor' => 'MyDB::Schema::Actor');
@@ -31,7 +31,7 @@ DBIx::Class::Relationship - Inter-table relationships
 
   $schema->resultset('Actor')->roles();
   $schema->resultset('Role')->search_related('actors', { Name => 'Fred' });
-  $schema->resultset('ActorRole')->add_to_role({ Name => 'Sherlock Holmes'});
+  $schema->resultset('ActorRole')->add_to_roles({ Name => 'Sherlock Holmes'});
 
 See L<DBIx::Class::Manual::Cookbook> for more.
 
@@ -65,10 +65,10 @@ we can do this instead:
 
  my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books;
 
-Each relationship sets up an accessor method on the 
+Each relationship sets up an accessor method on the
 L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items
 of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects,
-the relationships can be searched using the "search_related" method. 
+the relationships can be searched using the "search_related" method.
 In list context, each returns a list of Row objects for the related class,
 in scalar context, a new ResultSet representing the joined tables is
 returned. Thus, the calls can be chained to produce complex queries.
@@ -83,7 +83,7 @@ the data for an actual item, no time is wasted producing them.
 
 will produce a query something like:
 
- SELECT * FROM Author me 
+ SELECT * FROM Author me
  LEFT JOIN Books books ON books.author = me.id
  LEFT JOIN Prices prices ON prices.book = books.id
  WHERE prices.Price <= 5.00
@@ -112,12 +112,28 @@ See L<DBIx::Class::Relationship::Base> for a list of valid attributes.
   my $author_obj = $obj->author;
   $obj->author($new_author_obj);
 
-Creates a relationship where the calling class stores the foreign class's 
+Creates a relationship where the calling class stores the foreign class's
 primary key in one (or more) of its columns. If $cond is a column name
 instead of a join condition hash, that is used as the name of the column
 holding the foreign key. If $cond is not given, the relname is used as
 the column name.
 
+If the relationship is optional - ie the column containing the foreign
+key can be NULL - then the belongs_to relationship does the right
+thing - so in the example above C<$obj->author> would return C<undef>.
+However in this case you would probably want to set the C<join_type>
+attribute so that a C<LEFT JOIN> is done, which makes complex
+resultsets involving C<join> or C<prefetch> operations work correctly.
+The modified declaration is shown below:-
+
+  # in a Book class (where Author has many Books)
+  __PACKAGE__->belongs_to(author => 'My::DBIC::Schema::Author',
+                          'author', {join_type => 'left'});
+
+
+Cascading deletes are off per default on a C<belongs_to> relationship, to turn
+them on, pass C<< cascade_delete => 1 >> in the $attr hashref.
+
 NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
 of C<has_a>.
 
@@ -131,6 +147,8 @@ of C<has_a>.
     { prefetch => [qw/book/],
   });
   my @book_objs = $obj->books;
+  my $books_rs = $obj->books;
+  ( $books_rs ) = $obj->books_rs;
 
   $obj->add_to_books(\%col_data);
 
@@ -139,17 +157,23 @@ foreign class store the calling class's primary key in one (or more) of its
 columns. You should pass the name of the column in the foreign class as the
 $cond argument, or specify a complete join condition.
 
-As well as the accessor method, a method named C<< add_to_<relname> >>
-will also be added to your Row items, this allows you to insert new
-related items, using the same mechanism as in L<DBIx::Class::Relationship::Base/"create_related">.
+Three methods are created when you create a has_many relationship.  The first
+method is the expected accessor method.  The second is almost exactly the same
+as the accessor method but "_rs" is added to the end of the method name.  This
+method works just like the normal accessor, except that it returns a resultset
+no matter what, even in list context. The third method, named
+C<< add_to_<relname> >>, will also be added to your Row items, this allows
+you to insert new related items, using the same mechanism as in
+L<DBIx::Class::Relationship::Base/"create_related">.
 
 If you delete an object in a class with a C<has_many> relationship, all
-related objects will be deleted as well. However, any database-level
-cascade or restrict will take precedence.
+the related objects will be deleted as well. However, any database-level
+cascade or restrict will take precedence. To turn this behavior off, pass
+C<< cascade_delete => 0 >> in the $attr hashref.
 
 =head2 might_have
 
-  My::DBIC::Schema::Author->might_have(pseudonym => 
+  My::DBIC::Schema::Author->might_have(pseudonym =>
                                        'My::DBIC::Schema::Pseudonyms');
   my $pname = $obj->pseudonym; # to get the Pseudonym object
 
@@ -160,6 +184,7 @@ key of the foreign class unless $cond specifies a column or join condition.
 If you update or delete an object in a class with a C<might_have>
 relationship, the related object will be updated or deleted as well.
 Any database-level update or delete constraints will override this behaviour.
+To turn off this behavior, add C<< cascade_delete => 0 >> to the $attr hashref.
 
 =head2 has_one
 
@@ -175,26 +200,29 @@ left join.
 
 =head2 many_to_many
 
-  My::DBIC::Schema::Actor->has_many( actor_roles => 
+=over 4
+
+=item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name
+
+=back
+
+  My::DBIC::Schema::Actor->has_many( actor_roles =>
                                      'My::DBIC::Schema::ActorRoles',
                                      'actor' );
-  My::DBIC::Schema::ActorRoles->belongs_to( role => 
+  My::DBIC::Schema::ActorRoles->belongs_to( role =>
                                             'My::DBIC::Schema::Role' );
-  My::DBIC::Schema::ActorRoles->belongs_to( actor => 
+  My::DBIC::Schema::ActorRoles->belongs_to( actor =>
                                             'My::DBIC::Schema::Actor' );
 
   My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
-                                         'My::DBIC::Schema::Roles' );
-
-  ...
+                                         'role' );
 
-  my @role_objs = $actor->roles;
+Creates a accessors bridging two relationships; not strictly a relationship in
+its own right, although the accessor will return a resultset or collection of
+objects just as a has_many would.
 
-Creates an accessor bridging two relationships; not strictly a relationship
-in its own right, although the accessor will return a resultset or collection
-of objects just as a has_many would.
 To use many_to_many, existing relationships from the original table to the link
-table, and from the link table to the end table must already exist, these 
+table, and from the link table to the end table must already exist, these
 relation names are then used in the many_to_many call.
 
 =cut