From: Justin Guenther Date: Wed, 23 Aug 2006 17:49:48 +0000 (+0000) Subject: More Relationship docs clarifications/fixes X-Git-Tag: v0.07002~25 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=9e64dfbf92b14c3dac77cf4ed8a8842114cdbfe5;p=dbsrgits%2FDBIx-Class.git More Relationship docs clarifications/fixes --- diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm index 64e49f0..6a5a046 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', + { 'self.author' => 'foreign.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 @@ -301,7 +327,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