X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FRelationship%2FBase.pm;h=e660d146e907ad25b8f35b9246ca00ce2cdd50b4;hb=0c11ad0ee5c8407f6b87d6e15c62a1b445076dc0;hp=c23ebdf9222d7554b2fa11edda2e2a3545f38e68;hpb=a126983e43f896c64e0ae7ba01c8a3d690d8125a;p=dbsrgits%2FDBIx-Class.git diff --git a/lib/DBIx/Class/Relationship/Base.pm b/lib/DBIx/Class/Relationship/Base.pm index c23ebdf..e660d14 100644 --- a/lib/DBIx/Class/Relationship/Base.pm +++ b/lib/DBIx/Class/Relationship/Base.pm @@ -15,6 +15,17 @@ DBIx::Class::Relationship::Base - Inter-table relationships =head1 SYNOPSIS + __PACKAGE__->add_relationship( + spiders => 'My::DB::Result::Creatures', + sub { + my $args = shift; + return { + "$args->{foreign_alias}.id" => { -ident => "$args->{self_alias}.id" }, + "$args->{foreign_alias}.type" => 'arachnid' + }; + }, + ); + =head1 DESCRIPTION This class provides methods to describe the relationships between the @@ -27,50 +38,193 @@ methods, for predefined ones, look in L. =over 4 -=item Arguments: 'relname', 'Foreign::Class', $cond, $attrs +=item Arguments: 'relname', 'Foreign::Class', $condition, $attrs =back - __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs); + __PACKAGE__->add_relationship('relname', + 'Foreign::Class', + $condition, $attrs); + +Create a custom relationship between one result source and another +source, indicated by its class name. =head3 condition -The condition needs to be an L-style representation of the -join between the tables. When resolving the condition for use in a C, -keys using the pseudo-table C are resolved to mean "the Table on the -other side of the relationship", and values using the pseudo-table C -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 C parameter support. +The condition argument describes the C clause of the C +expression used to connect the two sources when creating SQL queries. + +To create simple equality joins, supply a hashref containing the +remote table column name as the key(s), and the local table column +name as the value(s), for example given: + + My::Schema::Author->has_many( + books => 'My::Schema::Book', + { 'foreign.author_id' => 'self.id' } + ); + +A query like: + + $author_rs->search_related('books')->next + +will result in the following C clause: + + ... FROM author me LEFT JOIN book books ON books.author_id = me.id ... + +This describes a relationship between the C table and the +C table where the C table has a column C +containing the ID value of the C. + +C and C are pseudo aliases and must be entered +literally. They will be replaced with the actual correct table alias +when the SQL is produced. + +Similarly: + + My::Schema::Book->has_many( + editions => 'My::Schema::Edition', + { + 'foreign.publisher_id' => 'self.publisher_id', + 'foreign.type_id' => 'self.type_id', + } + ); + + ... + + $book_rs->search_related('editions')->next + +will result in the C clause: + + ... FROM book me + LEFT JOIN edition editions ON + editions.publisher_id = me.publisher_id + AND editions.type_id = me.type_id ... -For example, if you're creating a relationship from C to C, where -the C table has a column C containing the ID of the C -row: +This describes the relationship from C to C, where the +C table refers to a publisher and a type (e.g. "paperback"): - { 'foreign.author_id' => 'self.id' } +As is the default in L, the key-value pairs will be +Ced in the result. C can be achieved with an arrayref, for +example a condition like: -will result in the C clause + My::Schema::Item->has_many( + related_item_links => My::Schema::Item::Links, + [ + { 'foreign.left_itemid' => 'self.id' }, + { 'foreign.right_itemid' => 'self.id' }, + ], + ); - author me JOIN book book ON book.author_id = me.id +will translate to the following C clause: -For multi-column foreign keys, you will need to specify a C-to-C -mapping for each column in the key. For example, if you're creating a -relationship from C to C, where the C table refers to a -publisher and a type (e.g. "paperback"): + ... FROM item me JOIN item_relations related_item_links ON + related_item_links.left_itemid = me.id + OR related_item_links.right_itemid = me.id ... - { - 'foreign.publisher_id' => 'self.publisher_id', - 'foreign.type_id' => 'self.type_id', +This describes the relationship from C to C, where +C is a many-to-many linking table, linking items back to +themselves in a peer fashion (without a "parent-child" designation) + +To specify joins which describe more than a simple equality of column +values, the custom join condition coderef syntax can be used. For +example: + + My::Schema::Artist->has_many( + cds_80s => 'My::Schema::CD', + sub { + my $args = shift; + + return { + "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" }, + "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" }, + }; + } + ); + + ... + + $artist_rs->search_related('cds_80s')->next; + +will result in the C clause: + + ... FROM artist me LEFT JOIN cd cds_80s ON + cds_80s.artist = me.artistid + AND cds_80s.year < ? + AND cds_80s.year > ? + +with the bind values: + + '1990', '1979' + +C<< $args->{foreign_alias} >> and C<< $args->{self_alias} >> are supplied the +same values that would be otherwise substituted for C and C +in the simple hashref syntax case. + +The coderef is expected to return a valid L query-structure, just +like what one would supply as the first argument to +L. The return value will be passed directly to +L and the resulting SQL will be used verbatim as the C +clause of the C statement associated with this relationship. + +While every coderef-based condition must return a valid C clause, it may +elect to additionally return a simplified join-free condition hashref when +invoked as C<< $row_object->relationship >>, as opposed to +C<< $rs->related_resultset('relationship') >>. In this case C<$row_object> is +passed to the coderef as C<< $args->{self_rowobj} >>, so a user can do the +following: + + sub { + my $args = shift; + + return ( + { + "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" }, + "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" }, + }, + $args->{self_rowobj} && { + "$args->{foreign_alias}.artist" => $args->{self_rowobj}->artistid, + "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" }, + }, + ); } -This will result in the C clause: +Now this code: - book me JOIN edition edition ON edition.publisher_id = me.publisher_id - AND edition.type_id = me.type_id + my $artist = $schema->resultset("Artist")->find({ id => 4 }); + $artist->cds_80s->all; -Each key-value pair provided in a hashref will be used as Ced conditions. -To add an Ced condition, use an arrayref of hashrefs. See the -L documentation for more details. +Can skip a C altogether and instead produce: + + SELECT cds_80s.cdid, cds_80s.artist, cds_80s.title, cds_80s.year, cds_80s.genreid, cds_80s.single_track + FROM cd cds_80s + WHERE cds_80s.artist = ? + AND cds_80s.year < ? + AND cds_80s.year > ? + +With the bind values: + + '4', '1990', '1979' + +Note that in order to be able to use +L<< $row->create_related|DBIx::Class::Relationship::Base/create_related >>, +the coderef must not only return as its second such a "simple" condition +hashref which does not depend on joins being available, but the hashref must +contain only plain values/deflatable objects, such that the result can be +passed directly to L. For +instance the C constraint in the above example prevents the relationship +from being used to to create related objects (an exception will be thrown). + +In order to allow the user to go truly crazy when generating a custom C +clause, the C<$args> hashref passed to the subroutine contains some extra +metadata. Currently the supplied coderef is executed as: + + $relationship_info->{cond}->({ + self_alias => The alias of the invoking resultset ('me' in case of a row object), + foreign_alias => The alias of the to-be-joined resultset (often matches relname), + self_resultsource => The invocant's resultsource, + foreign_relname => The relationship name (does *not* always match foreign_alias), + self_rowobj => The invocant itself in case of $row_obj->relationship + }); =head3 attributes @@ -95,6 +249,12 @@ command immediately before C. =item proxy =E $column | \@columns | \%column +The 'proxy' attribute can be used to retrieve values, and to perform +updates if the relationship has 'cascade_update' set. The 'might_have' +and 'has_one' relationships have this set by default; if you want a proxy +to update across a 'belongs_to' relationship, you must set the attribute +yourself. + =over 4 =item \@columns @@ -102,23 +262,31 @@ command immediately before C. An arrayref containing a list of accessors in the foreign class to create in the main class. If, for example, you do the following: - MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes', + MyApp::Schema::CD->might_have(liner_notes => 'MyApp::Schema::LinerNotes', undef, { proxy => [ qw/notes/ ], }); -Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do: +Then, assuming MyApp::Schema::LinerNotes has an accessor named notes, you can do: - my $cd = MyDB::Schema::CD->find(1); + my $cd = MyApp::Schema::CD->find(1); $cd->notes('Notes go here'); # set notes -- LinerNotes object is # created if it doesn't exist +For a 'belongs_to relationship, note the 'cascade_update': + + MyApp::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd, + { proxy => ['title'], cascade_update => 1 } + ); + $track->title('New Title'); + $track->update; # updates title in CD + =item \%column A hashref where each key is the accessor you want installed in the main class, and its value is the name of the original in the fireign class. - MyDB::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', { + MyApp::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', { proxy => { cd_title => 'title' }, }); @@ -128,7 +296,7 @@ This will create an accessor named C on the C<$track> row object. NOTE: you can pass a nested struct too, for example: - MyDB::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', { + MyApp::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', { proxy => [ 'year', { cd_title => 'title' } ], }); @@ -177,6 +345,10 @@ C relationships. You can disable this behaviour on a per-relationship basis by supplying C<< cascade_update => 0 >> in the relationship attributes. +The C relationship does not update across relationships +by default, so if you have a 'proxy' attribute on a belongs_to and want to +use 'update' on it, you muse set C<< cascade_update => 1 >>. + This is not a RDMS style cascade update - it purely means that when an object has update called on it, all the related objects also have update called. It will not change foreign keys automatically - @@ -263,14 +435,8 @@ sub related_resultset { # condition resolution may fail if an incomplete master-object prefetch # is encountered - that is ok during prefetch construction (not yet in_storage) - - # if $rel_info->{cond} is a CODE, we might need to join from the - # current resultsource instead of just querying the target - # resultsource, in that case, the condition might provide an - # additional condition in order to avoid an unecessary join if - # that is at all possible. - my ($cond, $cond2) = try { - $source->_resolve_condition( $rel_info->{cond}, $rel, $self ) + my ($cond, $is_crosstable) = try { + $source->_resolve_condition( $rel_info->{cond}, $rel, $self, $rel ) } catch { if ($self->in_storage) { @@ -280,61 +446,70 @@ sub related_resultset { $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION; # RV }; - if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) { - my $reverse = $source->reverse_relationship_info($rel); - foreach my $rev_rel (keys %$reverse) { - if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') { - $attrs->{related_objects}{$rev_rel} = [ $self ]; - weaken $attrs->{related_object}{$rev_rel}[0]; - } else { - $attrs->{related_objects}{$rev_rel} = $self; - weaken $attrs->{related_object}{$rev_rel}; - } - } + # keep in mind that the following if() block is part of a do{} - no return()s!!! + if ($is_crosstable) { + $self->throw_exception ( + "A cross-table relationship condition returned for statically declared '$rel'") + unless ref $rel_info->{cond} eq 'CODE'; + + # A WHOREIFFIC hack to reinvoke the entire condition resolution + # with the correct alias. Another way of doing this involves a + # lot of state passing around, and the @_ positions are already + # mapped out, making this crap a less icky option. + # + # The point of this exercise is to retain the spirit of the original + # $obj->search_related($rel) where the resulting rset will have the + # root alias as 'me', instead of $rel (as opposed to invoking + # $rs->search_related) + + local $source->{_relationships}{me} = $source->{_relationships}{$rel}; # make the fake 'me' rel + my $obj_table_alias = lc($source->source_name) . '__row'; + $obj_table_alias =~ s/\W+/_/g; + + $source->resultset->search( + $self->ident_condition($obj_table_alias), + { alias => $obj_table_alias }, + )->search_related('me', $query, $attrs) } - if (ref $cond eq 'ARRAY') { - $cond = [ map { - if (ref $_ eq 'HASH') { - my $hash; - foreach my $key (keys %$_) { - my $newkey = $key !~ /\./ ? "me.$key" : $key; - $hash->{$newkey} = $_->{$key}; + else { + # FIXME - this conditional doesn't seem correct - got to figure out + # at some point what it does. Also the entire UNRESOLVABLE_CONDITION + # business seems shady - we could simply not query *at all* + if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) { + my $reverse = $source->reverse_relationship_info($rel); + foreach my $rev_rel (keys %$reverse) { + if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') { + weaken($attrs->{related_objects}{$rev_rel}[0] = $self); + } else { + weaken($attrs->{related_objects}{$rev_rel} = $self); } - $hash; - } else { - $_; } - } @$cond ]; - } elsif (ref $cond eq 'HASH') { - - # this is where we're going to check if we have an extended - # rel. In that case, we need to: 1) If there's a second - # condition, we use that instead. 2) If there is only one - # condition, we need to join the current resultsource and have - # additional conditions. - if (ref $rel_info->{cond} eq 'CODE') { - # this is an extended relationship. - if ($cond2) { - $cond = $cond2; - } else { - if (exists $attrs->{join} && $attrs->{join}) { - # it's a bit hard to find out what to do here. - $self->throw_exception('Extended relationship '.$rel.' with additional join not supported'); + } + elsif (ref $cond eq 'ARRAY') { + $cond = [ map { + if (ref $_ eq 'HASH') { + my $hash; + foreach my $key (keys %$_) { + my $newkey = $key !~ /\./ ? "me.$key" : $key; + $hash->{$newkey} = $_->{$key}; + } + $hash; } else { - $attrs->{join} = $rel; + $_; } - } - } else { - foreach my $key (grep { ! /\./ } keys %$cond) { + } @$cond ]; + } + elsif (ref $cond eq 'HASH') { + 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 - ); + $query = ($query ? { '-and' => [ $cond, $query ] } : $cond); + $self->result_source->related_source($rel)->resultset->search( + $query, $attrs + ); + } }; } @@ -396,8 +571,36 @@ on it. =cut sub new_related { - my ($self, $rel, $values, $attrs) = @_; - return $self->search_related($rel)->new($values, $attrs); + my ($self, $rel, $values) = @_; + + # FIXME - this is a bad position for this (also an identical copy in + # set_from_related), but I have no saner way to hook, and I absolutely + # want this to throw at least for coderefs, instead of the "insert a NULL + # when it gets hard" insanity --ribasushi + # + # sanity check - currently throw when a complex coderef rel is encountered + # FIXME - should THROW MOAR! + + if (ref $self) { # cdbi calls this as a class method, /me vomits + + my $rsrc = $self->result_source; + my (undef, $crosstable, $relcols) = $rsrc->_resolve_condition ( + $rsrc->relationship_info($rel)->{cond}, $rel, $self, $rel + ); + + $self->throw_exception("Custom relationship '$rel' does not resolve to a join-free condition fragment") + if $crosstable; + + if (@{$relcols || []} and @$relcols = grep { ! exists $values->{$_} } @$relcols) { + $self->throw_exception(sprintf ( + "Custom relationship '%s' not definitive - returns conditions instead of values for column(s): %s", + $rel, + map { "'$_'" } @$relcols + )); + } + } + + return $self->search_related($rel)->new_result($values); } =head2 create_related @@ -413,7 +616,7 @@ in L for details. sub create_related { my $self = shift; my $rel = shift; - my $obj = $self->search_related($rel)->create(@_); + my $obj = $self->new_related($rel, @_)->insert; delete $self->{related_resultsets}->{$rel}; return $obj; } @@ -499,28 +702,37 @@ set them in the storage. sub set_from_related { my ($self, $rel, $f_obj) = @_; - my $rel_info = $self->relationship_info($rel); - $self->throw_exception( "No such relationship ${rel}" ) unless $rel_info; - my $cond = $rel_info->{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 $rsrc = $self->result_source; + my $rel_info = $rsrc->relationship_info($rel) + or $self->throw_exception( "No such relationship ${rel}" ); + if (defined $f_obj) { my $f_class = $rel_info->{class}; $self->throw_exception( "Object $f_obj isn't a ".$f_class ) unless blessed $f_obj and $f_obj->isa($f_class); } - # _resolve_condition might return two hashrefs, specially in the - # current case, since we know $f_object is an object. - my ($condref1, $condref2) = $self->result_source->_resolve_condition - ($rel_info->{cond}, $f_obj, $rel); - # if we get two condrefs, we need to use the second, otherwise we - # use the first. - $self->set_columns($condref2 ? $condref2 : $condref1); + # FIXME - this is a bad position for this (also an identical copy in + # new_related), but I have no saner way to hook, and I absolutely + # want this to throw at least for coderefs, instead of the "insert a NULL + # when it gets hard" insanity --ribasushi + # + # sanity check - currently throw when a complex coderef rel is encountered + # FIXME - should THROW MOAR! + my ($cond, $crosstable, $relcols) = $rsrc->_resolve_condition ( + $rel_info->{cond}, $f_obj, $rel, $rel + ); + $self->throw_exception("Custom relationship '$rel' does not resolve to a join-free condition fragment") + if $crosstable; + $self->throw_exception(sprintf ( + "Custom relationship '%s' not definitive - returns conditions instead of values for column(s): %s", + $rel, + map { "'$_'" } @$relcols + )) if @{$relcols || []}; + + $self->set_columns($cond); return 1; } @@ -632,9 +844,9 @@ Removes the link between the current object and the related object. Note that the related object itself won't be deleted unless you call ->delete() on it. This method just removes the link between the two objects. -=head1 AUTHORS +=head1 AUTHOR AND CONTRIBUTORS -Matt S. Trout +See L and L in DBIx::Class =head1 LICENSE