X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FRelationship.pm;h=b95867f01077542e150dcaf14d0526f15fe43850;hb=7d9fbacf13c288615dc718bbb76deb9fa28d8aa9;hp=64e49f0627947b4a2218811681806ee8f8ae7c0d;hpb=2535b501efdb62977fbafa118b5db6f9c7f44270;p=dbsrgits%2FDBIx-Class.git diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm index 64e49f0..b95867f 100644 --- a/lib/DBIx/Class/Relationship.pm +++ b/lib/DBIx/Class/Relationship.pm @@ -104,29 +104,34 @@ All helper methods take the following arguments: Both C<$cond> and C<$attrs> are optional. Pass C for C<$cond> if you want to use the default value for it, but still want to set C<$attrs>. -See L for a list of valid attributes. +See L for a list of valid attributes and valid +relationship attributes. =head2 belongs_to =over 4 -=item Arguments: $accessor_name, $related_class, $foreign_key_column?, $attr? +=item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr? =back # in a Book class (where Author has many Books) - My::DBIC::Schema::Book->belongs_to(author => 'My::DBIC::Schema::Author'); + My::DBIC::Schema::Book->belongs_to( author => 'My::DBIC::Schema::Author' ); my $author_obj = $obj->author; # get author object - $obj->author($new_author_obj); # set author object + $obj->author( $new_author_obj ); # set author object + +The above belongs_to relationship could also have been specified as, - My::DBIC::Schema::Book->belongs_to(publisher => + My::DBIC::Schema::Book->belongs_to( author, + 'My::DBIC::Schema::Author', + { 'foreign.author' => 'self.author' } ); Creates a relationship where the calling class stores the foreign class's -primary key in one (or more) of its columns. If C<$cond> is a column name -instead of a join condition hash, it is used as the name of the foreign key -column in the calling class. If C<$cond> is not given, C<$accessor_name> is -used as the column name. +primary key in one (or more) of its columns. This relationship defaults to +using C<$accessor_name> as the foreign key in C<$related_class> to resolve the +join, unless C<$foreign_key_column> specifies the foreign key column in +C<$related_class> or C<$cond> specifies a reference to a join condition hash. If the relationship is optional -- i.e. the column containing the foreign key can be NULL -- then the belongs_to relationship does the right thing. Thus, in @@ -147,7 +152,8 @@ in the $attr hashref. NOTE: If you are used to L relationships, this is the equivalent of C. -See L for documentation on relationship methods. +See L for documentation on relationship +methods and valid relationship attributes. =head2 has_many @@ -180,8 +186,10 @@ explicit join condition: Creates a one-to-many relationship, where the corresponding elements of the 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 -C<$cond> argument, or specify a complete join condition. +columns. This relationship defaults to using C<$accessor_name> as the foreign +key in C<$related_class> to resolve the join, unless C<$foreign_key_column> +specifies the foreign key column in C<$related_class> or C<$cond> specifies a +reference to a join condition hash. Three methods are created when you create a has_many relationship. The first method is the expected accessor method, C<$accessor_name()>. The second is @@ -198,25 +206,41 @@ pass C<< cascade_delete => 0 >> in the C<$attr> hashref. However, any database-level cascade or restrict will take precedence over a DBIx-Class-based cascading delete. -See L for documentation on relationship methods. +See L for documentation on relationship +methods and valid relationship attributes. =head2 might_have =over 4 -=item Arguments: $accessor_name, $related_class, $join_condition?, $attr? +=item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr? =back - My::DBIC::Schema::Author->might_have(pseudonym => - 'My::DBIC::Schema::Pseudonym'); + My::DBIC::Schema::Author->might_have( pseudonym => + 'My::DBIC::Schema::Pseudonym' ); my $pname = $obj->pseudonym; # to get the Pseudonym object +The above might_have relationship could have been specified as: + + My::DBIC::Schema::Author->might_have( pseudonym => + 'My::DBIC::Schema::Pseudonym', + 'author' ); + +Or even: + + My::DBIC::Schema::Author->might_have( pseudonym => + 'My::DBIC::Schema::Pseudonym', + { 'foreign.author' => 'self.author' } ); + +Assuming the Pseudonym table has + Creates an optional one-to-one relationship with a class. This relationship -defaults to using C<$accessor_name> as the foreign key in C<$related_class> -to resolve the join, unless C<$join_condition> specifies a column in -C<$related_class> or a join condition hash reference. +defaults to using C<$accessor_name> as the foreign key in C<$related_class> to +resolve the join, unless C<$foreign_key_column> specifies the foreign key +column in C<$related_class> or C<$cond> specifies a reference to a join +condition hash. If you update or delete an object in a class with a C relationship, the related object will be updated or deleted as well. To @@ -224,7 +248,8 @@ turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr> hashref. Any database-level update or delete constraints will override this behavior. -See L for more information. +See L for documentation on relationship +methods and valid relationship attributes. =head2 has_one @@ -251,7 +276,8 @@ table, use the L relationship. In the above example, each Book in the database is associated with exactly one ISBN object. -See L for documentation on relationship methods. +See L for documentation on relationship +methods and valid relationship attributes. =head2 many_to_many @@ -282,9 +308,16 @@ And, for the reverse relationship, from Role to Actor: My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' ); -Creates 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. +To add a role for your actor, and fill in the year of the role in the +actor_roles table: + + $actor->add_to_roles($role, { year => 1995 }); + +Many_to_many is not strictly a relationship in its own right. Instead, it is +a bridge between two resultsets which provide the same kind of convenience +accessors as true relationships provide. Although the accessor will return a +resultset or collection of objects just like has_many does, you cannot call +C<$related_resultset> and similar methods which operate on true relationships. In the above example, ActorRoles is the link table class, and Role is the foreign class. The C<$link_rel_name> parameter is the name of the accessor for @@ -301,7 +334,8 @@ set: C<$roles>, C<$add_to_roles>, C<$set_roles>, and similarly named accessors will be created for the Role class for the C many_to_many relationship. -See L for documentation on relationship methods. +See L for documentation on relationship +methods and valid relationship attributes. =cut