X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FRelationship%2FBase.pm;h=44496c435f249aa711f6c510ce7c97353e6531c0;hb=13523f299f81871f7c33fb2e662fc2b5b009f9d2;hp=c0c74c78e2581933093b567f65f4aea793cf9ab1;hpb=aed5b8a46a2e48adeeb790c06906c4d48f190043;p=dbsrgits%2FDBIx-Class.git diff --git a/lib/DBIx/Class/Relationship/Base.pm b/lib/DBIx/Class/Relationship/Base.pm index c0c74c7..44496c4 100644 --- a/lib/DBIx/Class/Relationship/Base.pm +++ b/lib/DBIx/Class/Relationship/Base.pm @@ -3,15 +3,29 @@ package DBIx::Class::Relationship::Base; use strict; use warnings; -use Scalar::Util (); use base qw/DBIx::Class/; +use Scalar::Util qw/weaken blessed/; +use Try::Tiny; +use namespace::clean; + =head1 NAME DBIx::Class::Relationship::Base - Inter-table relationships =head1 SYNOPSIS + __PACKAGE__->add_relationship('spiders', + 'My::DB::Result::Creatures', + sub { + my ( $me_alias, $rel_alias) = @_; + return + { "${rel_alias}.id" => { '=' => \"${me_alias}.id"}, + "${rel_alias}.type" => { '=', "arachnid" }, + }; + + }); + =head1 DESCRIPTION This class provides methods to describe the relationships between the @@ -24,50 +38,159 @@ 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. -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. +=head3 condition -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: +The condition argument describes the JOIN 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: { 'foreign.author_id' => 'self.id' } -will result in the C clause +will result in the C clause: author me JOIN book book ON book.author_id = me.id -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"): +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 psuedo aliases and must be entered +literally. They will be replaced with the actual correct table alias +when the SQL is produced. + +Similarly: { 'foreign.publisher_id' => 'self.publisher_id', 'foreign.type_id' => 'self.type_id', } -This will result in the C clause: +will result in the C clause: book me JOIN edition edition ON edition.publisher_id = me.publisher_id AND edition.type_id = me.type_id -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. +This describes the relationship from C to C, where the +C table refers to a publisher and a type (e.g. "paperback"): + +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: + + [ + { 'foreign.left_itemid' => 'self.id' }, + { 'foreign.right_itemid' => 'self.id' }, + ] + +which results in the C clause: + + items me JOIN related_items rel_link ON rel_link.left_itemid = me.id + OR rel_link.right_itemid = me.id + +This describes the relationship from C to C, +where C is a many-to-many linking table, linking Items +back to themselves. + +To create joins which describe more than a simple equality of column +values, the custom join condition coderef syntax can be used: + + sub { + my ( $me_alias, $rel_alias ) = @_; + return + ({ "${rel_alias}.artist" => { '=' => \"${me_alias}.artistid"}, + "${rel_alias}.year" => { '>', "1979", + '<', "1990" } + }); + } + +this will result in the C clause: + + artist me LEFT JOIN cd cds_80s_noopt ON + ( cds_80s_noopt.artist = me.artistid + AND ( cds_80s_noopt.year < ? AND cds_80s_noopt.year > ? ) + ) + +with the bind values: + + '1990', '1979' + +C<$rel_alias> is the equivalent to C in the simple syntax, +and will be replaced by the actual remote table alias in the produced +SQL. Similarly, C<$me_alias> is the equivalent to C and will be +replaced with the local table alias in the SQL. + +The actual syntax returned by the coderef should be valid +L syntax, similar to normal +L conditions. + +To help optimise the SQL produced, a second optional hashref can be +returned to be used when the relationship accessor is called directly +on a Row object: + + sub { + my ( $me_alias, $rel_alias, $me_result_source, + $rel_name, $optional_me_object ) = @_; + return + ({ "${rel_alias}.artist" => { '=' => \"${me_alias}.artistid"}, + "${rel_alias}.year" => { '>', "1979", + '<', "1990" } + }, + $optional_me_object && + { "${rel_alias}.artist" => $optional_me_object->artistid, + "${rel_alias}.year" => { '>', "1979", + '<', "1990" } + }); + } + +Now this code: + + my $artist = $schema->resultset("Artist")->find({ id => 4 }); + $artist->cds_80s->all; + +Produces: + + SELECT me.cdid, me.artist, me.title, me.year, me.genreid, me.single_track + FROM cd me + WHERE ( ( me.artist = ? AND ( me.year < ? AND me.year > ? ) ) ) -In addition to standard result set attributes, the following attributes are also valid: +With the bind values: + + '4', '1990', '1979' + +The C<$optional_me_object> used to create the second hashref contains +a row object, the object that the relation accessor was called on. + +C<$me_result_source> the L of the table +being searched on, and C<$rel_name>, the name of the relation +containing this condition, are also provided as arguments. These may +be useful to more complicated condition calculation. + +=head3 attributes + +The L may +be used as relationship attributes. In particular, the 'where' attribute is +useful for filtering relationships: + + __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User', + { 'foreign.user_id' => 'self.user_id' }, + { where => { valid => 1 } } + ); + +The following attributes are also valid: =over 4 @@ -77,22 +200,45 @@ Explicitly specifies the type of join to use in the relationship. Any SQL join type is valid, e.g. C or C. It will be placed in the SQL command immediately before C. -=item proxy +=item proxy =E $column | \@columns | \%column + +=over 4 + +=item \@columns 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', undef, { proxy => [ qw/notes/ ], }); - + Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do: my $cd = MyDB::Schema::CD->find(1); $cd->notes('Notes go here'); # set notes -- LinerNotes object is # created if it doesn't exist - + +=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', { + proxy => { cd_title => 'title' }, + }); + +This will create an accessor named C on the C<$track> row object. + +=back + +NOTE: you can pass a nested struct too, for example: + + MyDB::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', { + proxy => [ 'year', { cd_title => 'title' } ], + }); + =item accessor Specifies the type of accessor that should be created for the relationship. @@ -105,10 +251,57 @@ created, which calls C for the relationship. =item is_foreign_key_constraint If you are using L to create SQL for you and you find that it -is creating constraints where it shouldn't, or not creating them where it +is creating constraints where it shouldn't, or not creating them where it should, set this attribute to a true or false value to override the detection of when to create constraints. +=item cascade_copy + +If C is true on a C relationship for an +object, then when you copy the object all the related objects will +be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >> +in the C<$attr> hashref. + +The behaviour defaults to C<< cascade_copy => 1 >> for C +relationships. + +=item cascade_delete + +By default, DBIx::Class cascades deletes across C, +C and C relationships. You can disable this +behaviour on a per-relationship basis by supplying +C<< cascade_delete => 0 >> in the relationship attributes. + +The cascaded operations are performed after the requested delete, +so if your database has a constraint on the relationship, it will +have deleted/updated the related records or raised an exception +before DBIx::Class gets to perform the cascaded operation. + +=item cascade_update + +By default, DBIx::Class cascades updates across C and +C relationships. You can disable this behaviour on a +per-relationship basis by supplying C<< cascade_update => 0 >> in +the relationship attributes. + +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 - +you must arrange to do this yourself. + +=item on_delete / on_update + +If you are using L to create SQL for you, you can use these +attributes to explicitly set the desired C or C constraint +type. If not supplied the SQLT parser will attempt to infer the constraint type by +interrogating the attributes of the B relationship. For any 'multi' +relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to +relationship will be created with an C constraint. For any +relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint +will be C. If you wish to disable this autodetection, and just +use the RDBMS' default constraint type, pass C<< on_delete => undef >> or +C<< on_delete => '' >>, and the same for C respectively. + =item is_deferrable Tells L that the foreign key constraint it creates should be @@ -116,6 +309,12 @@ deferrable. In other words, the user may request that the constraint be ignored until the end of the transaction. Currently, only the PostgreSQL producer actually supports this. +=item add_fk_index + +Tells L to add an index for this constraint. Can also be +specified globally in the args to L or +L. Default is on, set to 0 to disable. + =back =head2 register_relationship @@ -155,32 +354,99 @@ sub related_resultset { $self->throw_exception("Can't call *_related as class methods") unless ref $self; my $rel = shift; - my $rel_obj = $self->relationship_info($rel); + my $rel_info = $self->relationship_info($rel); $self->throw_exception( "No such relationship ${rel}" ) - unless $rel_obj; - + unless $rel_info; + return $self->{related_resultsets}{$rel} ||= do { my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {}); - $attrs = { %{$rel_obj->{attrs} || {}}, %$attrs }; + $attrs = { %{$rel_info->{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 - ); + my $source = $self->result_source; + + # 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, $extended_cond) = try { + $source->_resolve_condition( $rel_info->{cond}, $rel, $self ) + } + catch { + if ($self->in_storage) { + $self->throw_exception ($_); + } + + $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}; + } + } + } + + # 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 ($extended_cond) { + $cond = $extended_cond; + + } else { + + # it's a bit hard to find out what to do with other joins + $self->throw_exception('Extended relationship '.$rel.' with additional join requires optimized declaration') + if exists $attrs->{join} && $attrs->{join}; + + # aliases get a bit more complicated, so we won't accept additional queries + $self->throw_exception('Extended relationship '.$rel.' with additional query requires optimized declaration') + if $query; + + $attrs->{from} = + [ { $rel => $self->result_source->from }, + [ { 'me' => $self->result_source->related_source($rel)->from }, { 1 => 1 } ] ]; + + $cond->{"${rel}.${_}"} = $self->get_column($_) for $self->result_source->primary_columns; + } + } + 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 { + $cond = [ map { + if (ref $_ eq 'HASH') { + my $hash; + foreach my $key (keys %$_) { + my $newkey = $key !~ /\./ ? "me.$key" : $key; + $hash->{$newkey} = $_->{$key}; + } + $hash; + } else { + $_; + } + } @$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 @@ -207,8 +473,8 @@ sub search_related { ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs); -This method works exactly the same as search_related, except that -it garauntees a restultset, even in list context. +This method works exactly the same as search_related, except that +it guarantees a resultset, even in list context. =cut @@ -237,9 +503,9 @@ sub count_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 foreign key columns of the new object to the related primary -key columns of the source object for you. The newly created item will +L object, it will magically +set any foreign key columns of the new object to the related primary +key columns of the source object for you. The newly created item will not be saved into your storage until you call L on it. @@ -340,7 +606,7 @@ example, to set the correct author for a book, find the Author object, then call set_from_related on the book. This is called internally when you pass existing objects as values to -L, or pass an object to a belongs_to acessor. +L, or pass an object to a belongs_to accessor. The columns are only set in the local copy of the object, call L to set them in the storage. @@ -349,22 +615,29 @@ set them in the storage. sub set_from_related { my ($self, $rel, $f_obj) = @_; - my $rel_obj = $self->relationship_info($rel); - $self->throw_exception( "No such relationship ${rel}" ) unless $rel_obj; - my $cond = $rel_obj->{cond}; + 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'; if (defined $f_obj) { - my $f_class = $self->result_source->schema->class($rel_obj->{class}); + my $f_class = $rel_info->{class}; $self->throw_exception( "Object $f_obj isn't a ".$f_class ) - unless Scalar::Util::blessed($f_obj) and $f_obj->isa($f_class); + unless blessed $f_obj and $f_obj->isa($f_class); } - $self->set_columns( - $self->result_source->resolve_condition( - $rel_obj->{cond}, $f_obj, $rel)); + + # _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); + return 1; } @@ -429,17 +702,21 @@ B relationships.> =over 4 -=item Arguments: (\@hashrefs | \@objs) +=item Arguments: (\@hashrefs | \@objs), $link_vals? =back my $actor = $schema->resultset('Actor')->find(1); - my @roles = $schema->resultset('Role')->search({ role => - { '-in' -> ['Fred', 'Barney'] } } ); + my @roles = $schema->resultset('Role')->search({ role => + { '-in' => ['Fred', 'Barney'] } } ); $actor->set_roles(\@roles); # Replaces all of $actor's previous roles with the two named + $actor->set_roles(\@roles, { salary => 15_000_000 }); + # Sets a column in the link table for all roles + + Replace all the related objects with the given reference to a list of objects. This does a C B to remove the association between the current object and all related objects, then calls