X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FRelationship.pm;h=3ee93ff09c427d32720476bf5a3248fe86f219e7;hb=ddf66ced51e4cb9b888001bc926bc0b3c3af0f8b;hp=64e49f0627947b4a2218811681806ee8f8ae7c0d;hpb=2535b501efdb62977fbafa118b5db6f9c7f44270;p=dbsrgits%2FDBIx-Class-Historic.git diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm index 64e49f0..3ee93ff 100644 --- a/lib/DBIx/Class/Relationship.pm +++ b/lib/DBIx/Class/Relationship.pm @@ -104,29 +104,66 @@ 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 + +Creates a relationship where the calling class stores the foreign class's +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. + +=over + +=item accessor_name + +This argument is the name of the method you can call on a +L object to retrieve the instance of the foreign +class matching this relationship. + +Use this accessor_name (relation name) in L +or L to join to the foreign table +indicated by this relationship. + +=item related_class + +This is the class name of the table referenced by the foreign key in +this class. + +=item foreign_key_column + +The column name on this class that contains the foreign key. + +OR + +=item cond + +A hashref where the keys are C and +the values are C. This is useful for +relations that are across multiple columns. =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 - My::DBIC::Schema::Book->belongs_to(publisher => +The above belongs_to relationship could also have been specified as, -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. + My::DBIC::Schema::Book->belongs_to( author, + 'My::DBIC::Schema::Author', + { 'foreign.author' => 'self.author' } ); 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 +184,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 @@ -157,6 +195,45 @@ See L for documentation on relationship methods =back +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. 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. + +=over + +=item accessor_name + +This argument is the name of the method you can call on a +L object to retrieve a resultset of the related +class restricted to the ones related to the row object. In list +context it returns the row objects. + +Use this accessor_name (relation name) in L +or L to join to the foreign table +indicated by this relationship. + +=item related_class + +This is the class name of the table which contains a foreign key +column containing PK values of this class. + +=item foreign_key_column + +The column name on the related class that contains the foreign key. + +OR + +=item cond + +A hashref where the keys are C and +the values are C. This is useful for +relations that are across multiple columns. + +=back + # in an Author class (where Author has_many Books) My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author'); @@ -178,11 +255,6 @@ explicit join condition: 'foreign.author' => 'self.author', }); -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. - 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 almost exactly the same as the accessor method but "_rs" is added to the end of @@ -198,25 +270,70 @@ 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 + +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<$foreign_key_column> specifies the foreign key +column in C<$related_class> or C<$cond> specifies a reference to a join +condition hash. + +=over + +=item accessor_name + +This argument is the name of the method you can call on a +L object to retrieve the instance of the foreign +class matching this relationship. + +Use this accessor_name (relation name) in L +or L to join to the foreign table +indicated by this relationship. + +=item related_class + +This is the class name of the table which contains a foreign key +column containing PK values of this class. + +=item foreign_key_column + +The column name on the related class that contains the foreign key. + +OR + +=item cond + +A hashref where the keys are C and +the values are C. This is useful for +relations that are across multiple columns. =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 -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. +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' } ); 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 +341,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 +369,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 @@ -261,6 +380,37 @@ See L for documentation on relationship methods =back +C 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 and similar methods which operate on true relationships. + +=over + +=item accessor_name + +This argument is the name of the method you can call on a +L object to retrieve the rows matching this +relationship. + +On a many_to_many, unlike other relationships, this cannot be used in +L to join tables. Use the relations +bridged across instead. + +=item link_rel_name + +This is the accessor_name from the has_many relationship we are +bridging from. + +=item foreign_rel_name + +This is the accessor_name of the belongs_to relationship in the link +table that we are bridging across (which gives us the table we are +bridging to). + +=back + To create a many_to_many relationship from Actor to Role: My::DBIC::Schema::Actor->has_many( actor_roles => @@ -282,9 +432,10 @@ 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 }); 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 +452,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