X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FRelationship%2FBase.pm;h=96b7c189132b50ef0b270a68b277a281019bb00a;hb=2c037e6bd80a384bbf00b46ad91a7b36251f080b;hp=483ee98e5967734875f2e96f8b255a3afc32fa18;hpb=ff7bb7a13a5254d5af455d17eeaa8b629d936183;p=dbsrgits%2FDBIx-Class.git diff --git a/lib/DBIx/Class/Relationship/Base.pm b/lib/DBIx/Class/Relationship/Base.pm index 483ee98..96b7c18 100644 --- a/lib/DBIx/Class/Relationship/Base.pm +++ b/lib/DBIx/Class/Relationship/Base.pm @@ -5,9 +5,7 @@ use warnings; use base qw/DBIx::Class/; -__PACKAGE__->mk_classdata('_relationships', { } ); - -=head1 NAME +=head1 NAME DBIx::Class::Relationship::Base - Inter-table relationships @@ -15,26 +13,43 @@ DBIx::Class::Relationship::Base - Inter-table relationships =head1 DESCRIPTION -This class handles relationships between the tables in your database -model. It allows your to set up relationships, and to perform joins -on searches. +This class provides methods to describe the relationships between the +tables in your database model. These are the "bare bones" relationships +methods, for predefined ones, look in L. =head1 METHODS =head2 add_relationship +=over 4 + +=item Arguments: 'relname', 'Foreign::Class', $cond, $attrs + +=back + __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs); The condition needs to be an SQL::Abstract-style representation of the -join between the tables. For example, if you're creating a rel from Foo to Bar, +join between the tables. When resolving the condition for use in a JOIN, +keys using the pseudo-table I are resolved to mean "the Table on the +other side of the relationship", and values using the pseudo-table I +are resolved to mean "the Table this class is representing". Other +restrictions, such as by value, sub-select and other tables, may also be +used. Please check your database for JOIN parameter support. - { 'foreign.foo_id' => 'self.id' } +For example, if you're creating a rel from Author to Book, where the Book +table has a column author_id containing the ID of the Author row: + + { 'foreign.author_id' => 'self.id' } will result in the JOIN clause - foo me JOIN bar bar ON bar.foo_id = me.id + author me JOIN book book ON bar.author_id = me.id -You can specify as many foreign => self mappings as necessary. +You can specify as many foreign => self mappings as necessary. Each key/value +pair provided in a hashref will be used as ANDed conditions, to add an ORed +condition, use an arrayref of hashrefs. See the L documentation +for more details. Valid attributes are as follows: @@ -48,15 +63,19 @@ command immediately before C. =item proxy -An arrayref containing a list of accessors in the foreign class to proxy in +An arrayref containing a list of accessors in the foreign class to create in the main class. If, for example, you do the following: - __PACKAGE__->might_have(bar => 'Bar', undef, { proxy => [ qw/margle/ ] }); + MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes', + undef, { + proxy => [ qw/notes/ ], + }); -Then, assuming Bar has an accessor named margle, you can do: +Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do: - my $obj = Foo->find(1); - $obj->margle(10); # set margle; Bar object is created if it doesn't exist + my $cd = MyDB::Schema::CD->find(1); + $cd->notes('Notes go here'); # set notes -- LinerNotes object is + # created if it doesn't exist =item accessor @@ -69,17 +88,83 @@ created, which calls C for the relationship. =back -=head2 register_relationship($relname, $rel_info) +=head2 register_relationship + +=over 4 + +=item Arguments: $relname, $rel_info + +=back -Registers a relationship on the class +Registers a relationship on the class. This is called internally by +L to set up Accessors and Proxies. =cut sub register_relationship { } +=head2 related_resultset + +=over 4 + +=item Arguments: $relationship_name + +=item Return Value: $related_resultset + +=back + + $rs = $cd->related_resultset('artist'); + +Returns a L for the relationship named +$relationship_name. + +=cut + +sub related_resultset { + my $self = shift; + $self->throw_exception("Can't call *_related as class methods") + unless ref $self; + my $rel = shift; + my $rel_obj = $self->relationship_info($rel); + $self->throw_exception( "No such relationship ${rel}" ) + unless $rel_obj; + + return $self->{related_resultsets}{$rel} ||= do { + my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {}); + $attrs = { %{$rel_obj->{attrs} || {}}, %$attrs }; + + $self->throw_exception( "Invalid query: @_" ) + if (@_ > 1 && (@_ % 2 == 1)); + my $query = ((@_ > 1) ? {@_} : shift); + + my $cond = $self->result_source->resolve_condition( + $rel_obj->{cond}, $rel, $self + ); + if (ref $cond eq 'ARRAY') { + $cond = [ map { my $hash; + foreach my $key (keys %$_) { + my $newkey = $key =~ /\./ ? "me.$key" : $key; + $hash->{$newkey} = $_->{$key}; + }; $hash } @$cond ]; + } else { + foreach my $key (grep { ! /\./ } keys %$cond) { + $cond->{"me.$key"} = delete $cond->{$key}; + } + } + $query = ($query ? { '-and' => [ $cond, $query ] } : $cond); + $self->result_source->related_source($rel)->resultset->search( + $query, $attrs + ); + }; +} + =head2 search_related - My::Table->search_related('relname', $cond, $attrs); + $rs->search_related('relname', $cond, $attrs); + +Run a search on a related resultset. The search will be restricted to the +item or items represented by the L it was called +upon. This method can be called on a ResultSet, a Row or a ResultSource class. =cut @@ -91,6 +176,11 @@ sub search_related { $obj->count_related('relname', $cond, $attrs); +Returns the count of all the items in the related resultset, restricted by the +current item or where conditions. Can be called on a +L or a +L object. + =cut sub count_related { @@ -98,9 +188,30 @@ sub count_related { return $self->search_related(@_)->count; } +=head2 new_related + + my $new_obj = $obj->new_related('relname', \%col_data); + +Create a new item of the related foreign class. If called on a +L object, it will magically set any +primary key values into foreign key columns for you. The newly created item +will not be saved into your storage until you call L +on it. + +=cut + +sub new_related { + my ($self, $rel, $values, $attrs) = @_; + return $self->search_related($rel)->new($values, $attrs); +} + =head2 create_related - My::Table->create_related('relname', \%col_data); + my $new_obj = $obj->create_related('relname', \%col_data); + +Creates a new item, similarly to new_related, and also inserts the item's data +into your storage medium. See the distinction between C and C +in L for details. =cut @@ -112,20 +223,12 @@ sub create_related { return $obj; } -=head2 new_related - - My::Table->new_related('relname', \%col_data); - -=cut - -sub new_related { - my ($self, $rel, $values, $attrs) = @_; - return $self->search_related($rel)->new($values, $attrs); -} - =head2 find_related - My::Table->find_related('relname', @pri_vals | \%pri_vals); + my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals); + +Attempt to find a related object using its primary key or unique constraints. +See L for details. =cut @@ -137,7 +240,10 @@ sub find_related { =head2 find_or_create_related - My::Table->find_or_create_related('relname', \%col_data); + my $new_obj = $obj->find_or_create_related('relname', \%col_data); + +Find or create an item of a related class. See +L for details. =cut @@ -148,7 +254,15 @@ sub find_or_create_related { =head2 set_from_related - My::Table->set_from_related('relname', $rel_obj); + $book->set_from_related('author', $author_obj); + +Set column values on the current object, using related values from the given +related object. This is used to associate previously separate objects, for +example, to set the correct author for a book, find the Author object, then +call set_from_related on the book. + +The columns are only set in the local copy of the object, call L to +set them in the storage. =cut @@ -157,12 +271,16 @@ sub set_from_related { my $rel_obj = $self->relationship_info($rel); $self->throw_exception( "No such relationship ${rel}" ) unless $rel_obj; my $cond = $rel_obj->{cond}; - $self->throw_exception( "set_from_related can only handle a hash condition; the " - ."condition for $rel is of type ".(ref $cond ? ref $cond : 'plain scalar')) - unless ref $cond eq 'HASH'; - my $f_class = $self->result_source->schema->class($rel_obj->{class}); - $self->throw_exception( "Object $f_obj isn't a ".$f_class ) - unless $f_obj->isa($f_class); + $self->throw_exception( + "set_from_related can only handle a hash condition; the ". + "condition for $rel is of type ". + (ref $cond ? ref $cond : 'plain scalar') + ) unless ref $cond eq 'HASH'; + if (defined $f_obj) { + my $f_class = $self->result_source->schema->class($rel_obj->{class}); + $self->throw_exception( "Object $f_obj isn't a ".$f_class ) + unless $f_obj->isa($f_class); + } $self->set_columns( $self->result_source->resolve_condition( $rel_obj->{cond}, $f_obj, $rel)); @@ -171,7 +289,10 @@ sub set_from_related { =head2 update_from_related - My::Table->update_from_related('relname', $rel_obj); + $book->update_from_related('author', $author_obj); + +The same as L, but the changes are immediately updated +in storage. =cut @@ -183,7 +304,9 @@ sub update_from_related { =head2 delete_related - My::Table->delete_related('relname', $cond, $attrs); + $obj->delete_related('relname', $cond, $attrs); + +Delete any related item subject to the given conditions. =cut @@ -196,65 +319,6 @@ sub delete_related { 1; -=head2 related_resultset($name) - -Returns a L for the relationship named $name. - - $rs = My::Table->related_resultset('related_table'); - -=cut - -sub related_resultset { - my $self = shift; - $self->throw_exception("Can't call *_related as class methods") unless ref $self; - my $rel = shift; - $self->{related_resultsets} ||= {}; - #use Data::Dumper; warn "related_resultsets: ", Dumper $self->{related_resultsets}; - my $resultsets = $self->{related_resultsets}; - if( !exists $resultsets->{$rel} ) { - - #warn "creating related resultset for relation '$rel'", \$self; - my $source = $self->result_source; - # if relation exists but resultset doesn't, create the resultset - - my $attrs = { }; - if (@_ > 1 && ref $_[$#_] eq 'HASH') { - $attrs = { %{ pop(@_) } }; - } - - my $rel_obj = $self->relationship_info($rel); - $self->throw_exception( "No such relationship ${rel}" ) unless $rel_obj; - $attrs = { %{$rel_obj->{attrs} || {}}, %{$attrs || {}} }; - - $self->throw_exception( "Invalid query: @_" ) if (@_ > 1 && (@_ % 2 == 1)); - my $query = ((@_ > 1) ? {@_} : shift); - - my ($cond) = $self->result_source->resolve_condition($rel_obj->{cond}, $rel, $self); - if (ref $cond eq 'ARRAY') { - $cond = [ map { my %hash; - foreach my $key (keys %{$_}) { - unless ($key =~ m/\./) { - $hash{"me.$key"} = $_->{$key}; - } else { - $hash{$key} = $_->{$key}; - } - }; \%hash; } @$cond ]; - } else { - foreach my $key (keys %$cond) { - unless ($key =~ m/\./) { - $cond->{"me.$key"} = delete $cond->{$key}; - } - } - } - $query = ($query ? { '-and' => [ $cond, $query ] } : $cond); - #use Data::Dumper; warn Dumper($cond); - #warn $rel_obj->{class}." $meth $cond ".join(', ', @{$attrs->{bind}||[]}); - $resultsets->{$rel} = - $self->result_source->related_source($rel)->resultset->search($query, $attrs); - } - return $resultsets->{$rel}; -} - =head1 AUTHORS Matt S. Trout