X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FRelationship.pm;h=195514ce6af6ecb0f06ff99b092e4ce19f00c67e;hb=e5c6382908ee65577e53c0771629384d70959a3d;hp=ff26676fa0c60870eb71f42da6a106a5e35f27fd;hpb=13523f299f81871f7c33fb2e662fc2b5b009f9d2;p=dbsrgits%2FDBIx-Class.git diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm index ff26676..195514c 100644 --- a/lib/DBIx/Class/Relationship.pm +++ b/lib/DBIx/Class/Relationship.pm @@ -13,6 +13,10 @@ __PACKAGE__->load_own_components(qw/ Base /); +1; + +__END__ + =head1 NAME DBIx::Class::Relationship - Inter-table relationships @@ -20,15 +24,15 @@ DBIx::Class::Relationship - Inter-table relationships =head1 SYNOPSIS ## Creating relationships - MyDB::Schema::Actor->has_many('actorroles' => 'MyDB::Schema::ActorRole', + MyApp::Schema::Actor->has_many('actorroles' => 'MyApp::Schema::ActorRole', 'actor'); - MyDB::Schema::Role->has_many('actorroles' => 'MyDB::Schema::ActorRole', + MyApp::Schema::Role->has_many('actorroles' => 'MyApp::Schema::ActorRole', 'role'); - MyDB::Schema::ActorRole->belongs_to('role' => 'MyDB::Schema::Role'); - MyDB::Schema::ActorRole->belongs_to('actor' => 'MyDB::Schema::Actor'); + MyApp::Schema::ActorRole->belongs_to('role' => 'MyApp::Schema::Role'); + MyApp::Schema::ActorRole->belongs_to('actor' => 'MyApp::Schema::Actor'); - MyDB::Schema::Role->many_to_many('actors' => 'actorroles', 'actor'); - MyDB::Schema::Actor->many_to_many('roles' => 'actorroles', 'role'); + MyApp::Schema::Role->many_to_many('actors' => 'actorroles', 'actor'); + MyApp::Schema::Actor->many_to_many('roles' => 'actorroles', 'role'); ## Using relationships $schema->resultset('Actor')->find({ id => 1})->roles(); @@ -72,10 +76,10 @@ we can do this instead: my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books; Each relationship sets up an accessor method on the -L objects that represent the items -of your table. From L objects, +L objects that represent the items +of your table. From L objects, 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 list context, each returns a list of Result 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. Since the database is not actually queried until you attempt to retrieve @@ -105,13 +109,13 @@ L. All helper methods are called similar to the following template: - __PACKAGE__->$method_name('relname', 'Foreign::Class', - \%cond | \@cond | \&conf, \%attrs); + __PACKAGE__->$method_name('rel_name', 'Foreign::Class', \%cond|\@cond|\&cond?, \%attrs?); Both C and C are optional. Pass C for C if you want to use the default value for it, but still want to set C. -See L for full documentation on definition of the C argument. +See L for full documentation on +definition of the C argument. See L for documentation on the attributes that are allowed in the C argument. @@ -137,7 +141,7 @@ in this class or C specifies a reference to a join condition. =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 +L object to retrieve the instance of the foreign class matching this relationship. This is often called the C. @@ -159,14 +163,14 @@ OR =item cond A hashref, arrayref or coderef specifying a custom join expression. For -documentation see L. +more info see L. =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', 'author_id' ); @@ -174,11 +178,11 @@ documentation see L. My::DBIC::Schema::Book->belongs_to( author => 'My::DBIC::Schema::Author', - { 'foreign.author_id' => 'self.author_id' } + { 'foreign.author_id' => 'self.author_id' } ); # OR (similar result but uglier accessor name) - My::DBIC::Schema::Book->belongs_to( + My::DBIC::Schema::Book->belongs_to( author_id => 'My::DBIC::Schema::Author' ); @@ -191,25 +195,25 @@ documentation see L. # To retrieve the plain id if you used the ugly version: $book->get_column('author_id'); - -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 the example above C<< $obj->author >> would -return C. However in this case you would probably want to set -the L attribute so that -a C is done, which makes complex resultsets involving -C or C operations work correctly. The modified -declaration is shown below: +If some of the foreign key columns are +L you probably want to set +the L attribute to +C explicitly so that SQL expressing this relation is composed with +a C (as opposed to C which is default for +L relationships). This ensures that relationship traversal +works consistently in all situations. (i.e. resultsets involving +L or +L). +The modified declaration is shown below: # in a Book class (where Author has_many Books) __PACKAGE__->belongs_to( - author => + author => 'My::DBIC::Schema::Author', - 'author', + 'author', { join_type => 'left' } ); - Cascading deletes are off by default on a C relationship. To turn them on, pass C<< cascade_delete => 1 >> in the $attr hashref. @@ -231,13 +235,13 @@ which can be assigned to relationships as well. =over 4 -=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond\&cond?, \%attrs? +=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES> =back Creates a one-to-many relationship where the foreign class refers to this class's primary key. This relationship refers to zero or more -records in the foreign table (e.g. a C). This relationship +records in the foreign table (e.g. a C). This relationship defaults to using the end of this classes namespace as the foreign key in C<$related_class> to resolve the join, unless C<$their_fk_column> specifies the foreign key column in C<$related_class> or C @@ -248,9 +252,9 @@ specifies a reference to a join condition. =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. This is often called the +L object to retrieve a resultset of the related +class restricted to the ones related to the result object. In list +context it returns the result objects. This is often called the C. Use this accessor_name in L @@ -271,35 +275,35 @@ OR =item cond A hashref, arrayref or coderef specifying a custom join expression. For -documentation see L. +more info see L. =back # in an Author class (where Author has_many Books) # assuming related class is storing our PK in "author_id" My::DBIC::Schema::Author->has_many( - books => - 'My::DBIC::Schema::Book', + books => + 'My::DBIC::Schema::Book', 'author_id' ); # OR (same result) My::DBIC::Schema::Author->has_many( - books => - 'My::DBIC::Schema::Book', + books => + 'My::DBIC::Schema::Book', { 'foreign.author_id' => 'self.id' }, ); # OR (similar result, assuming related_class is storing our PK, in "author") # (the "author" is guessed at from "Author" in the class namespace) My::DBIC::Schema::Author->has_many( - books => - 'My::DBIC::Schema::Book', + books => + 'My::DBIC::Schema::Book', ); # Usage - # resultset of Books belonging to author + # resultset of Books belonging to author my $booklist = $author->books; # resultset of Books belonging to author, restricted by author name @@ -327,7 +331,7 @@ The second is almost exactly the same as the accessor method but "_rs" is added to the end of the method name, eg C<$accessor_name_rs()>. This method works just like the normal accessor, except that it always returns a resultset, even in list context. The third method, named C<< -add_to_$relname >>, will also be added to your Row items; this allows +add_to_$rel_name >>, will also be added to your Row items; this allows you to insert new related items, using the same mechanism as in L. @@ -355,7 +359,7 @@ relationships as well. =over 4 -=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs? +=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES> =back @@ -370,7 +374,7 @@ condition. =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 +L object to retrieve the instance of the foreign class matching this relationship. This is often called the C. @@ -392,7 +396,7 @@ OR =item cond A hashref, arrayref or coderef specifying a custom join expression. For -documentation see L. +more info see L. =back @@ -440,7 +444,7 @@ current table allows nulls (i.e., has the C attribute set to a true value), than C will warn about this because it's naughty and you shouldn't do that. The warning will look something like: - "might_have/has_one" must not be on columns with is_nullable set to true (MySchema::SomeClass/key) + "might_have/has_one" must not be on columns with is_nullable set to true (MySchema::SomeClass/key) If you must be naughty, you can suppress the warning by setting C environment variable to a true value. Otherwise, @@ -450,7 +454,7 @@ you probably just meant to use C. =over 4 -=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs? +=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES> =back @@ -465,7 +469,7 @@ condition. =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 +L object to retrieve the instance of the foreign class matching this relationship. This is often called the C. @@ -487,26 +491,26 @@ OR =item cond A hashref, arrayref or coderef specifying a custom join expression. For -documentation see L. +more info see L. =back # Every book has exactly one ISBN My::DBIC::Schema::Book->has_one( - isbn => + isbn => 'My::DBIC::Schema::ISBN', 'book_id', ); # OR (same result, assuming related_class stores our PK) My::DBIC::Schema::Book->has_one( - isbn => + isbn => 'My::DBIC::Schema::ISBN', ); # OR (same result) My::DBIC::Schema::Book->has_one( - isbn => + isbn => 'My::DBIC::Schema::ISBN', { 'foreign.book_id' => 'self.id' }, ); @@ -543,7 +547,7 @@ L. =over 4 -=item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, \%attrs? +=item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES> =back @@ -553,8 +557,8 @@ L. 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 +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 @@ -562,7 +566,7 @@ C and similar methods which operate on true relationships. =item accessor_name This argument is the name of the method you can call on a -L object to retrieve the rows matching this +L object to retrieve the rows matching this relationship. On a many_to_many, unlike other relationships, this cannot be used in @@ -629,17 +633,13 @@ L for a L which can be assigned to relationships as well. -=cut - -1; - -=head1 AUTHORS - -see L - -=head1 LICENSE +=head1 FURTHER QUESTIONS? -You may distribute this code under the same terms as Perl itself. +Check the list of L. -=cut +=head1 COPYRIGHT AND LICENSE +This module is free software L +by the L. You can +redistribute it and/or modify it under the same terms as the +L.