X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FRelationship.pm;h=b5d6932e9b02f23f4b05465f70fa52438f79b8c4;hb=60a8fb957a697c1ff60ab81fac452b691cd4e3b1;hp=770953fa1663cc1ded0b602c0f43f039d90e74ab;hpb=bc0c980086ba429cf33b1d471d1035601727231f;p=dbsrgits%2FDBIx-Class.git

diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm
index 770953f..b5d6932 100644
--- a/lib/DBIx/Class/Relationship.pm
+++ b/lib/DBIx/Class/Relationship.pm
@@ -13,12 +13,28 @@ __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',
+                                'actor');
+  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');
+
+  MyDB::Schema::Role->many_to_many('actors' => 'actorroles', 'actor');
+  MyDB::Schema::Actor->many_to_many('roles' => 'actorroles', 'role');
+
+  $schema->resultset('Actor')->roles();
+  $schema->resultset('Role')->search_related('actors', { Name => 'Fred' });
+  $schema->resultset('ActorRole')->add_to_roles({ Name => 'Sherlock Holmes'});
+
+See L<DBIx::Class::Manual::Cookbook> for more.
+
 =head1 DESCRIPTION
 
 This class provides methods to set up relationships between the tables
@@ -49,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.
@@ -67,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
@@ -75,7 +91,8 @@ will produce a query something like:
 all without needing multiple fetches.
 
 Only the helper methods for setting up standard relationship types
-are documented here. For the basic, lower-level methods, see
+are documented here. For the basic, lower-level methods, and a description
+of all the useful *_related methods that you get for free, see
 L<DBIx::Class::Relationship::Base>.
 
 =head1 METHODS
@@ -91,11 +108,11 @@ See L<DBIx::Class::Relationship::Base> for a list of valid attributes.
 =head2 belongs_to
 
   # in a Book class (where Author has many Books)
-  My::DBIC::Schema::Book->belongs_to(author => 'Author');
+  My::DBIC::Schema::Book->belongs_to(author => 'My::DBIC::Schema::Author');
   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
@@ -107,13 +124,15 @@ of C<has_a>.
 =head2 has_many
 
   # in an Author class (where Author has many Books)
-  My::DBIC::Schema::Author->has_many(books => 'Book', 'author');
+  My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author');
   my $booklist = $obj->books;
   my $booklist = $obj->books({
     name => { LIKE => '%macaroni%' },
     { prefetch => [qw/book/],
   });
   my @book_objs = $obj->books;
+  my $books_rs = $obj->books;
+  ( $books_rs ) = $obj->books_rs;
 
   $obj->add_to_books(\%col_data);
 
@@ -122,14 +141,24 @@ 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.
 
+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.
 
 =head2 might_have
 
-  My::DBIC::Schema::Author->might_have(psuedonym => 'Psuedonyms');
-  my $pname = $obj->psuedonym; # to get the Psuedonym object
+  My::DBIC::Schema::Author->might_have(pseudonym =>
+                                       'My::DBIC::Schema::Pseudonyms');
+  my $pname = $obj->pseudonym; # to get the Pseudonym object
 
 Creates an optional one-to-one relationship with a class, where the foreign
 class stores our primary key in one of its columns. Defaults to the primary
@@ -141,7 +170,7 @@ Any database-level update or delete constraints will override this behaviour.
 
 =head2 has_one
 
-  My::DBIC::Schema::Book->has_one(isbn => ISBN);
+  My::DBIC::Schema::Book->has_one(isbn => 'My::DBIC::Schema::ISBN');
   my $isbn_obj = $obj->isbn;
 
 Creates a one-to-one relationship with another class. This is just like
@@ -153,7 +182,16 @@ left join.
 
 =head2 many_to_many
 
-  My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles', 'Roles' );
+  My::DBIC::Schema::Actor->has_many( actor_roles =>
+                                     'My::DBIC::Schema::ActorRoles',
+                                     'actor' );
+  My::DBIC::Schema::ActorRoles->belongs_to( role =>
+                                            'My::DBIC::Schema::Role' );
+  My::DBIC::Schema::ActorRoles->belongs_to( actor =>
+                                            'My::DBIC::Schema::Actor' );
+
+  My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
+                                         'role' );
 
   ...
 
@@ -162,6 +200,9 @@ left join.
 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
+relation names are then used in the many_to_many call.
 
 =cut