Fix bogus reference to related class (introduced way back in 97c96475)
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Relationship / Base.pm
CommitLineData
55e2d745 1package DBIx::Class::Relationship::Base;
2
3use strict;
4use warnings;
5
1edd1722 6use base qw/DBIx::Class/;
6298a324 7
8use Scalar::Util qw/weaken blessed/;
ed7ab0f4 9use Try::Tiny;
fd323bf1 10use namespace::clean;
55e2d745 11
75d07914 12=head1 NAME
55e2d745 13
8918977e 14DBIx::Class::Relationship::Base - Inter-table relationships
55e2d745 15
16=head1 SYNOPSIS
17
6c4f4d69 18 __PACKAGE__->add_relationship(
19 spiders => 'My::DB::Result::Creatures',
20 sub {
21 my $args = shift;
22 return {
23 "$args->{foreign_alias}.id" => { -ident => "$args->{self_alias}.id" },
24 "$args->{foreign_alias}.type" => 'arachnid'
25 };
26 },
27 );
13523f29 28
55e2d745 29=head1 DESCRIPTION
30
30236e47 31This class provides methods to describe the relationships between the
32tables in your database model. These are the "bare bones" relationships
75d07914 33methods, for predefined ones, look in L<DBIx::Class::Relationship>.
55e2d745 34
35=head1 METHODS
36
8091aa91 37=head2 add_relationship
503536d5 38
27f01d1f 39=over 4
40
13523f29 41=item Arguments: 'relname', 'Foreign::Class', $condition, $attrs
27f01d1f 42
43=back
30236e47 44
6c4f4d69 45 __PACKAGE__->add_relationship('relname',
46 'Foreign::Class',
13523f29 47 $condition, $attrs);
48
49Create a custom relationship between one result source and another
50source, indicated by its class name.
503536d5 51
406734bb 52=head3 condition
53
6c4f4d69 54The condition argument describes the C<ON> clause of the C<JOIN>
55expression used to connect the two sources when creating SQL queries.
30236e47 56
5d2588cc 57=head4 Simple equality
58
59To create simple equality joins, supply a hashref containing the remote
60table column name as the key(s) prefixed by C<'foreign.'>, and the
61corresponding local table column name as the value(s) prefixed by C<'self.'>.
62Both C<foreign> and C<self> are pseudo aliases and must be entered
63literally. They will be replaced with the actual correct table alias
64when the SQL is produced.
65
66For example given:
503536d5 67
6c4f4d69 68 My::Schema::Author->has_many(
69 books => 'My::Schema::Book',
70 { 'foreign.author_id' => 'self.id' }
71 );
503536d5 72
6c4f4d69 73A query like:
74
75 $author_rs->search_related('books')->next
503536d5 76
6c4f4d69 77will result in the following C<JOIN> clause:
78
79 ... FROM author me LEFT JOIN book books ON books.author_id = me.id ...
503536d5 80
13523f29 81This describes a relationship between the C<Author> table and the
82C<Book> table where the C<Book> table has a column C<author_id>
83containing the ID value of the C<Author>.
84
13523f29 85Similarly:
5271499d 86
6c4f4d69 87 My::Schema::Book->has_many(
88 editions => 'My::Schema::Edition',
89 {
90 'foreign.publisher_id' => 'self.publisher_id',
91 'foreign.type_id' => 'self.type_id',
92 }
93 );
94
95 ...
96
97 $book_rs->search_related('editions')->next
5271499d 98
13523f29 99will result in the C<JOIN> clause:
5271499d 100
6c4f4d69 101 ... FROM book me
102 LEFT JOIN edition editions ON
103 editions.publisher_id = me.publisher_id
104 AND editions.type_id = me.type_id ...
5271499d 105
13523f29 106This describes the relationship from C<Book> to C<Edition>, where the
107C<Edition> table refers to a publisher and a type (e.g. "paperback"):
108
5d2588cc 109=head4 Multiple groups of simple equality conditions
110
13523f29 111As is the default in L<SQL::Abstract>, the key-value pairs will be
5d2588cc 112C<AND>ed in the resulting C<JOIN> clause. An C<OR> can be achieved with
113an arrayref. For example a condition like:
13523f29 114
6c4f4d69 115 My::Schema::Item->has_many(
116 related_item_links => My::Schema::Item::Links,
117 [
118 { 'foreign.left_itemid' => 'self.id' },
119 { 'foreign.right_itemid' => 'self.id' },
120 ],
121 );
13523f29 122
6c4f4d69 123will translate to the following C<JOIN> clause:
13523f29 124
6c4f4d69 125 ... FROM item me JOIN item_relations related_item_links ON
126 related_item_links.left_itemid = me.id
127 OR related_item_links.right_itemid = me.id ...
13523f29 128
6c4f4d69 129This describes the relationship from C<Item> to C<Item::Links>, where
130C<Item::Links> is a many-to-many linking table, linking items back to
131themselves in a peer fashion (without a "parent-child" designation)
13523f29 132
84d8c2ad 133=head4 Custom join conditions
134
5d2588cc 135 NOTE: The custom join condition specification mechanism is capable of
136 generating JOIN clauses of virtually unlimited complexity. This may limit
137 your ability to traverse some of the more involved relationship chains the
138 way you expect, *and* may bring your RDBMS to its knees. Exercise care
139 when declaring relationships as described here.
140
6c4f4d69 141To specify joins which describe more than a simple equality of column
142values, the custom join condition coderef syntax can be used. For
143example:
13523f29 144
6c4f4d69 145 My::Schema::Artist->has_many(
146 cds_80s => 'My::Schema::CD',
13523f29 147 sub {
6c4f4d69 148 my $args = shift;
13523f29 149
6c4f4d69 150 return {
151 "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
152 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
153 };
154 }
155 );
13523f29 156
6c4f4d69 157 ...
13523f29 158
6c4f4d69 159 $artist_rs->search_related('cds_80s')->next;
13523f29 160
6c4f4d69 161will result in the C<JOIN> clause:
13523f29 162
6c4f4d69 163 ... FROM artist me LEFT JOIN cd cds_80s ON
164 cds_80s.artist = me.artistid
165 AND cds_80s.year < ?
166 AND cds_80s.year > ?
13523f29 167
6c4f4d69 168with the bind values:
13523f29 169
6c4f4d69 170 '1990', '1979'
13523f29 171
6c4f4d69 172C<< $args->{foreign_alias} >> and C<< $args->{self_alias} >> are supplied the
173same values that would be otherwise substituted for C<foreign> and C<self>
174in the simple hashref syntax case.
175
176The coderef is expected to return a valid L<SQL::Abstract> query-structure, just
177like what one would supply as the first argument to
178L<DBIx::Class::ResultSet/search>. The return value will be passed directly to
179L<SQL::Abstract> and the resulting SQL will be used verbatim as the C<ON>
180clause of the C<JOIN> statement associated with this relationship.
181
182While every coderef-based condition must return a valid C<ON> clause, it may
8273e845 183elect to additionally return a simplified join-free condition hashref when
dad42de6 184invoked as C<< $result->relationship >>, as opposed to
185C<< $rs->related_resultset('relationship') >>. In this case C<$result> is
6c4f4d69 186passed to the coderef as C<< $args->{self_rowobj} >>, so a user can do the
187following:
188
189 sub {
190 my $args = shift;
191
192 return (
193 {
194 "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
195 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
196 },
197 $args->{self_rowobj} && {
198 "$args->{foreign_alias}.artist" => $args->{self_rowobj}->artistid,
199 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
200 },
201 );
13523f29 202 }
203
204Now this code:
205
206 my $artist = $schema->resultset("Artist")->find({ id => 4 });
207 $artist->cds_80s->all;
208
6c4f4d69 209Can skip a C<JOIN> altogether and instead produce:
13523f29 210
6c4f4d69 211 SELECT cds_80s.cdid, cds_80s.artist, cds_80s.title, cds_80s.year, cds_80s.genreid, cds_80s.single_track
212 FROM cd cds_80s
213 WHERE cds_80s.artist = ?
214 AND cds_80s.year < ?
215 AND cds_80s.year > ?
13523f29 216
217With the bind values:
218
219 '4', '1990', '1979'
220
6c4f4d69 221Note that in order to be able to use
47d7b769 222L<< $result->create_related|DBIx::Class::Relationship::Base/create_related >>,
6c4f4d69 223the coderef must not only return as its second such a "simple" condition
224hashref which does not depend on joins being available, but the hashref must
225contain only plain values/deflatable objects, such that the result can be
226passed directly to L<DBIx::Class::Relationship::Base/set_from_related>. For
227instance the C<year> constraint in the above example prevents the relationship
4a0eed52 228from being used to create related objects (an exception will be thrown).
6c4f4d69 229
230In order to allow the user to go truly crazy when generating a custom C<ON>
231clause, the C<$args> hashref passed to the subroutine contains some extra
232metadata. Currently the supplied coderef is executed as:
233
234 $relationship_info->{cond}->({
dad42de6 235 self_alias => The alias of the invoking resultset ('me' in case of a result object),
6c4f4d69 236 foreign_alias => The alias of the to-be-joined resultset (often matches relname),
237 self_resultsource => The invocant's resultsource,
238 foreign_relname => The relationship name (does *not* always match foreign_alias),
dad42de6 239 self_rowobj => The invocant itself in case of a $result_object->$relationship call
6c4f4d69 240 });
8091aa91 241
406734bb 242=head3 attributes
243
244The L<standard ResultSet attributes|DBIx::Class::ResultSet/ATTRIBUTES> may
245be used as relationship attributes. In particular, the 'where' attribute is
246useful for filtering relationships:
247
248 __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
249 { 'foreign.user_id' => 'self.user_id' },
250 { where => { valid => 1 } }
251 );
252
253The following attributes are also valid:
8091aa91 254
255=over 4
256
257=item join_type
258
259Explicitly specifies the type of join to use in the relationship. Any SQL
260join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
261command immediately before C<JOIN>.
262
97c96475 263=item proxy =E<gt> $column | \@columns | \%column
264
9ab122aa 265The 'proxy' attribute can be used to retrieve values, and to perform
266updates if the relationship has 'cascade_update' set. The 'might_have'
267and 'has_one' relationships have this set by default; if you want a proxy
268to update across a 'belongs_to' relationship, you must set the attribute
269yourself.
270
97c96475 271=over 4
272
273=item \@columns
8091aa91 274
30236e47 275An arrayref containing a list of accessors in the foreign class to create in
8091aa91 276the main class. If, for example, you do the following:
d4daee7b 277
03460bef 278 MyApp::Schema::CD->might_have(liner_notes => 'MyApp::Schema::LinerNotes',
27f01d1f 279 undef, {
280 proxy => [ qw/notes/ ],
281 });
d4daee7b 282
03460bef 283Then, assuming MyApp::Schema::LinerNotes has an accessor named notes, you can do:
8091aa91 284
03460bef 285 my $cd = MyApp::Schema::CD->find(1);
30236e47 286 $cd->notes('Notes go here'); # set notes -- LinerNotes object is
287 # created if it doesn't exist
d4daee7b 288
9ab122aa 289For a 'belongs_to relationship, note the 'cascade_update':
290
a5fc4975 291 MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd,
9ab122aa 292 { proxy => ['title'], cascade_update => 1 }
293 );
294 $track->title('New Title');
295 $track->update; # updates title in CD
296
97c96475 297=item \%column
298
299A hashref where each key is the accessor you want installed in the main class,
4a0eed52 300and its value is the name of the original in the foreign class.
97c96475 301
a5fc4975 302 MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd', {
97c96475 303 proxy => { cd_title => 'title' },
304 });
305
dad42de6 306This will create an accessor named C<cd_title> on the C<$track> result object.
97c96475 307
308=back
309
310NOTE: you can pass a nested struct too, for example:
311
a5fc4975 312 MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd', {
97c96475 313 proxy => [ 'year', { cd_title => 'title' } ],
314 });
315
8091aa91 316=item accessor
317
318Specifies the type of accessor that should be created for the relationship.
319Valid values are C<single> (for when there is only a single related object),
320C<multi> (when there can be many), and C<filter> (for when there is a single
321related object, but you also want the relationship accessor to double as
322a column accessor). For C<multi> accessors, an add_to_* method is also
323created, which calls C<create_related> for the relationship.
324
3d618782 325=item is_foreign_key_constraint
326
327If you are using L<SQL::Translator> to create SQL for you and you find that it
fd323bf1 328is creating constraints where it shouldn't, or not creating them where it
3d618782 329should, set this attribute to a true or false value to override the detection
330of when to create constraints.
331
5f7ac523 332=item cascade_copy
333
334If C<cascade_copy> is true on a C<has_many> relationship for an
335object, then when you copy the object all the related objects will
fd323bf1 336be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
337in the C<$attr> hashref.
b7bbc39f 338
339The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
340relationships.
5f7ac523 341
342=item cascade_delete
343
b7bbc39f 344By default, DBIx::Class cascades deletes across C<has_many>,
345C<has_one> and C<might_have> relationships. You can disable this
fd323bf1 346behaviour on a per-relationship basis by supplying
b7bbc39f 347C<< cascade_delete => 0 >> in the relationship attributes.
5f7ac523 348
349The cascaded operations are performed after the requested delete,
350so if your database has a constraint on the relationship, it will
351have deleted/updated the related records or raised an exception
352before DBIx::Class gets to perform the cascaded operation.
353
354=item cascade_update
355
b7bbc39f 356By default, DBIx::Class cascades updates across C<has_one> and
5f7ac523 357C<might_have> relationships. You can disable this behaviour on a
b7bbc39f 358per-relationship basis by supplying C<< cascade_update => 0 >> in
359the relationship attributes.
5f7ac523 360
9ab122aa 361The C<belongs_to> relationship does not update across relationships
362by default, so if you have a 'proxy' attribute on a belongs_to and want to
363use 'update' on it, you muse set C<< cascade_update => 1 >>.
364
cee0c9b1 365This is not a RDMS style cascade update - it purely means that when
366an object has update called on it, all the related objects also
367have update called. It will not change foreign keys automatically -
368you must arrange to do this yourself.
5f7ac523 369
e377d723 370=item on_delete / on_update
371
372If you are using L<SQL::Translator> to create SQL for you, you can use these
fd323bf1 373attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
374type. If not supplied the SQLT parser will attempt to infer the constraint type by
e377d723 375interrogating the attributes of the B<opposite> relationship. For any 'multi'
fd323bf1 376relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
377relationship will be created with an C<ON DELETE CASCADE> constraint. For any
e377d723 378relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
379will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
fd323bf1 380use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
e377d723 381C<< on_delete => '' >>, and the same for C<on_update> respectively.
382
13de943d 383=item is_deferrable
384
385Tells L<SQL::Translator> that the foreign key constraint it creates should be
386deferrable. In other words, the user may request that the constraint be ignored
387until the end of the transaction. Currently, only the PostgreSQL producer
388actually supports this.
389
2581038c 390=item add_fk_index
391
392Tells L<SQL::Translator> to add an index for this constraint. Can also be
393specified globally in the args to L<DBIx::Class::Schema/deploy> or
394L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
395
8091aa91 396=back
397
87c4e602 398=head2 register_relationship
399
27f01d1f 400=over 4
401
dad42de6 402=item Arguments: $rel_name, $rel_info
27f01d1f 403
404=back
71e65b39 405
30236e47 406Registers a relationship on the class. This is called internally by
71f9df37 407DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
71e65b39 408
55e2d745 409=cut
410
71e65b39 411sub register_relationship { }
412
27f01d1f 413=head2 related_resultset
414
415=over 4
416
dad42de6 417=item Arguments: $rel_name
27f01d1f 418
dad42de6 419=item Return Value: L<$related_resultset|DBIx::Class::ResultSet>
27f01d1f 420
421=back
30236e47 422
27f01d1f 423 $rs = $cd->related_resultset('artist');
30236e47 424
27f01d1f 425Returns a L<DBIx::Class::ResultSet> for the relationship named
dad42de6 426$rel_name.
30236e47 427
93711422 428=head2 $relationship_accessor
429
430=over 4
431
dad42de6 432=item Arguments: none
93711422 433
dad42de6 434=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | L<$related_resultset|DBIx::Class::ResultSet> | undef
93711422 435
436=back
437
438 # These pairs do the same thing
47d7b769 439 $result = $cd->related_resultset('artist')->single; # has_one relationship
440 $result = $cd->artist;
93711422 441 $rs = $cd->related_resultset('tracks'); # has_many relationship
442 $rs = $cd->tracks;
443
8ed69929 444This is the recommended way to traverse through relationships, based
93711422 445on the L</accessor> name given in the relationship definition.
446
dad42de6 447This will return either a L<Result|DBIx::Class::Manual::ResultClass> or a
93711422 448L<ResultSet|DBIx::Class::ResultSet>, depending on if the relationship is
449C<single> (returns only one row) or C<multi> (returns many rows). The
450method may also return C<undef> if the relationship doesn't exist for
451this instance (like in the case of C<might_have> relationships).
452
30236e47 453=cut
454
455sub related_resultset {
456 my $self = shift;
72c2540d 457
bc0c9800 458 $self->throw_exception("Can't call *_related as class methods")
459 unless ref $self;
72c2540d 460
30236e47 461 my $rel = shift;
d4daee7b 462
3d0733aa 463 return $self->{related_resultsets}{$rel}
464 if defined $self->{related_resultsets}{$rel};
465
466 return $self->{related_resultsets}{$rel} = do {
3b4c4d72 467
468 my $rel_info = $self->relationship_info($rel)
469 or $self->throw_exception( "No such relationship '$rel'" );
470
30236e47 471 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
164efde3 472 $attrs = { %{$rel_info->{attrs} || {}}, %$attrs };
30236e47 473
bc0c9800 474 $self->throw_exception( "Invalid query: @_" )
475 if (@_ > 1 && (@_ % 2 == 1));
30236e47 476 my $query = ((@_ > 1) ? {@_} : shift);
477
72c2540d 478 my $rsrc = $self->result_source;
d419ded6 479
480 # condition resolution may fail if an incomplete master-object prefetch
34b6b86f 481 # is encountered - that is ok during prefetch construction (not yet in_storage)
aa56106b 482 my ($cond, $is_crosstable) = try {
72c2540d 483 $rsrc->_resolve_condition( $rel_info->{cond}, $rel, $self, $rel )
52b420dd 484 }
ed7ab0f4 485 catch {
34b6b86f 486 if ($self->in_storage) {
ed7ab0f4 487 $self->throw_exception ($_);
34b6b86f 488 }
52b420dd 489
490 $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION; # RV
ed7ab0f4 491 };
d419ded6 492
aa56106b 493 # keep in mind that the following if() block is part of a do{} - no return()s!!!
494 if ($is_crosstable) {
495 $self->throw_exception (
e705f529 496 "A cross-table relationship condition returned for statically declared '$rel'"
497 ) unless ref $rel_info->{cond} eq 'CODE';
aa56106b 498
499 # A WHOREIFFIC hack to reinvoke the entire condition resolution
500 # with the correct alias. Another way of doing this involves a
501 # lot of state passing around, and the @_ positions are already
502 # mapped out, making this crap a less icky option.
503 #
504 # The point of this exercise is to retain the spirit of the original
505 # $obj->search_related($rel) where the resulting rset will have the
506 # root alias as 'me', instead of $rel (as opposed to invoking
507 # $rs->search_related)
508
72c2540d 509 local $rsrc->{_relationships}{me} = $rsrc->{_relationships}{$rel}; # make the fake 'me' rel
510 my $obj_table_alias = lc($rsrc->source_name) . '__row';
93508f48 511 $obj_table_alias =~ s/\W+/_/g;
aa56106b 512
72c2540d 513 $rsrc->resultset->search(
aa56106b 514 $self->ident_condition($obj_table_alias),
515 { alias => $obj_table_alias },
516 )->search_related('me', $query, $attrs)
68f3b0dd 517 }
aa56106b 518 else {
519 # FIXME - this conditional doesn't seem correct - got to figure out
520 # at some point what it does. Also the entire UNRESOLVABLE_CONDITION
521 # business seems shady - we could simply not query *at all*
522 if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
72c2540d 523 my $reverse = $rsrc->reverse_relationship_info($rel);
aa56106b 524 foreach my $rev_rel (keys %$reverse) {
525 if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
0a03206a 526 weaken($attrs->{related_objects}{$rev_rel}[0] = $self);
aa56106b 527 } else {
0a03206a 528 weaken($attrs->{related_objects}{$rev_rel} = $self);
aa56106b 529 }
530 }
9aae3566 531 }
aa56106b 532 elsif (ref $cond eq 'ARRAY') {
7689b9e5 533 $cond = [ map {
534 if (ref $_ eq 'HASH') {
535 my $hash;
536 foreach my $key (keys %$_) {
537 my $newkey = $key !~ /\./ ? "me.$key" : $key;
538 $hash->{$newkey} = $_->{$key};
539 }
540 $hash;
541 } else {
542 $_;
370f2ba2 543 }
7689b9e5 544 } @$cond ];
aa56106b 545 }
546 elsif (ref $cond eq 'HASH') {
547 foreach my $key (grep { ! /\./ } keys %$cond) {
7689b9e5 548 $cond->{"me.$key"} = delete $cond->{$key};
370f2ba2 549 }
30236e47 550 }
a126983e 551
7689b9e5 552 $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
72c2540d 553 $rsrc->related_source($rel)->resultset->search(
aa56106b 554 $query, $attrs
555 );
7689b9e5 556 }
30236e47 557 };
558}
559
8091aa91 560=head2 search_related
503536d5 561
dad42de6 562=over 4
563
564=item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
565
566=item Return Value: L<$resultset|DBIx::Class::ResultSet> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
567
568=back
30236e47 569
570Run a search on a related resultset. The search will be restricted to the
dad42de6 571results represented by the L<DBIx::Class::ResultSet> it was called
572upon.
573
574See L<DBIx::Class::ResultSet/search_related> for more information.
503536d5 575
576=cut
577
55e2d745 578sub search_related {
ff7bb7a1 579 return shift->related_resultset(shift)->search(@_);
b52e9bf8 580}
581
5b89a768 582=head2 search_related_rs
583
fd323bf1 584This method works exactly the same as search_related, except that
48580715 585it guarantees a resultset, even in list context.
5b89a768 586
587=cut
588
589sub search_related_rs {
590 return shift->related_resultset(shift)->search_rs(@_);
591}
592
b52e9bf8 593=head2 count_related
594
dad42de6 595=over 4
596
597=item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
598
599=item Return Value: $count
b52e9bf8 600
dad42de6 601=back
602
603Returns the count of all the rows in the related resultset, restricted by the
604current result or where conditions.
30236e47 605
b52e9bf8 606=cut
607
608sub count_related {
4b8a53ea 609 shift->search_related(@_)->count;
55e2d745 610}
611
30236e47 612=head2 new_related
613
dad42de6 614=over 4
615
616=item Arguments: $rel_name, \%col_data
617
618=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
30236e47 619
dad42de6 620=back
621
622Create a new result object of the related foreign class. It will magically set
623any foreign key columns of the new object to the related primary key columns
624of the source object for you. The newly created result will not be saved into
625your storage until you call L<DBIx::Class::Row/insert> on it.
30236e47 626
627=cut
628
629sub new_related {
81e4dc3d 630 my ($self, $rel, $values) = @_;
78b948c3 631
632 # FIXME - this is a bad position for this (also an identical copy in
633 # set_from_related), but I have no saner way to hook, and I absolutely
634 # want this to throw at least for coderefs, instead of the "insert a NULL
635 # when it gets hard" insanity --ribasushi
636 #
637 # sanity check - currently throw when a complex coderef rel is encountered
638 # FIXME - should THROW MOAR!
639
640 if (ref $self) { # cdbi calls this as a class method, /me vomits
641
642 my $rsrc = $self->result_source;
3f8affda 643 my $rel_info = $rsrc->relationship_info($rel)
644 or $self->throw_exception( "No such relationship '$rel'" );
72c2540d 645 my (undef, $crosstable, $cond_targets) = $rsrc->_resolve_condition (
3f8affda 646 $rel_info->{cond}, $rel, $self, $rel
78b948c3 647 );
648
649 $self->throw_exception("Custom relationship '$rel' does not resolve to a join-free condition fragment")
650 if $crosstable;
651
72c2540d 652 if (my @unspecified_rel_condition_chunks = grep { ! exists $values->{$_} } @{$cond_targets||[]} ) {
78b948c3 653 $self->throw_exception(sprintf (
654 "Custom relationship '%s' not definitive - returns conditions instead of values for column(s): %s",
655 $rel,
72c2540d 656 map { "'$_'" } @unspecified_rel_condition_chunks
78b948c3 657 ));
658 }
659 }
660
81e4dc3d 661 return $self->search_related($rel)->new_result($values);
30236e47 662}
663
8091aa91 664=head2 create_related
503536d5 665
dad42de6 666=over 4
30236e47 667
dad42de6 668=item Arguments: $rel_name, \%col_data
669
670=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
671
672=back
673
674 my $result = $obj->create_related($rel_name, \%col_data);
675
676Creates a new result object, similarly to new_related, and also inserts the
677result's data into your storage medium. See the distinction between C<create>
678and C<new> in L<DBIx::Class::ResultSet> for details.
503536d5 679
680=cut
681
55e2d745 682sub create_related {
3842b955 683 my $self = shift;
fea3d045 684 my $rel = shift;
78b948c3 685 my $obj = $self->new_related($rel, @_)->insert;
64acc2bc 686 delete $self->{related_resultsets}->{$rel};
687 return $obj;
55e2d745 688}
689
8091aa91 690=head2 find_related
503536d5 691
dad42de6 692=over 4
693
694=item Arguments: $rel_name, \%col_data | @pk_values, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
695
696=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
697
698=back
699
700 my $result = $obj->find_related($rel_name, \%col_data);
30236e47 701
702Attempt to find a related object using its primary key or unique constraints.
27f01d1f 703See L<DBIx::Class::ResultSet/find> for details.
503536d5 704
705=cut
706
1a14aa3f 707sub find_related {
4b8a53ea 708 #my ($self, $rel, @args) = @_;
709 return shift->search_related(shift)->find(@_);
1a14aa3f 710}
711
b3e1f1f5 712=head2 find_or_new_related
713
dad42de6 714=over 4
b3e1f1f5 715
dad42de6 716=item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
717
718=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
719
720=back
721
722Find a result object of a related class. See L<DBIx::Class::ResultSet/find_or_new>
723for details.
b3e1f1f5 724
725=cut
726
727sub find_or_new_related {
728 my $self = shift;
e60dc79f 729 my $obj = $self->find_related(@_);
730 return defined $obj ? $obj : $self->new_related(@_);
b3e1f1f5 731}
732
8091aa91 733=head2 find_or_create_related
503536d5 734
dad42de6 735=over 4
736
737=item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
738
739=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
740
741=back
30236e47 742
dad42de6 743Find or create a result object of a related class. See
b3e1f1f5 744L<DBIx::Class::ResultSet/find_or_create> for details.
503536d5 745
746=cut
747
55e2d745 748sub find_or_create_related {
749 my $self = shift;
9c2c91ea 750 my $obj = $self->find_related(@_);
751 return (defined($obj) ? $obj : $self->create_related(@_));
55e2d745 752}
753
045120e6 754=head2 update_or_create_related
755
dad42de6 756=over 4
757
758=item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
759
760=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
761
762=back
045120e6 763
dad42de6 764Update or create a result object of a related class. See
f7e1846f 765L<DBIx::Class::ResultSet/update_or_create> for details.
045120e6 766
767=cut
768
769sub update_or_create_related {
4b8a53ea 770 #my ($self, $rel, @args) = @_;
771 shift->related_resultset(shift)->update_or_create(@_);
045120e6 772}
773
8091aa91 774=head2 set_from_related
503536d5 775
dad42de6 776=over 4
777
778=item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
779
780=item Return Value: not defined
781
782=back
783
30236e47 784 $book->set_from_related('author', $author_obj);
ac8e89d7 785 $book->author($author_obj); ## same thing
30236e47 786
787Set column values on the current object, using related values from the given
788related object. This is used to associate previously separate objects, for
789example, to set the correct author for a book, find the Author object, then
790call set_from_related on the book.
791
ac8e89d7 792This is called internally when you pass existing objects as values to
48580715 793L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
ac8e89d7 794
27f01d1f 795The columns are only set in the local copy of the object, call L</update> to
796set them in the storage.
503536d5 797
798=cut
799
55e2d745 800sub set_from_related {
801 my ($self, $rel, $f_obj) = @_;
aa56106b 802
78b948c3 803 my $rsrc = $self->result_source;
804 my $rel_info = $rsrc->relationship_info($rel)
e705f529 805 or $self->throw_exception( "No such relationship '$rel'" );
aa56106b 806
2c037e6b 807 if (defined $f_obj) {
164efde3 808 my $f_class = $rel_info->{class};
e705f529 809 $self->throw_exception( "Object '$f_obj' isn't a ".$f_class )
6298a324 810 unless blessed $f_obj and $f_obj->isa($f_class);
2c037e6b 811 }
a126983e 812
a126983e 813
78b948c3 814 # FIXME - this is a bad position for this (also an identical copy in
815 # new_related), but I have no saner way to hook, and I absolutely
816 # want this to throw at least for coderefs, instead of the "insert a NULL
817 # when it gets hard" insanity --ribasushi
818 #
819 # sanity check - currently throw when a complex coderef rel is encountered
820 # FIXME - should THROW MOAR!
72c2540d 821 my ($cond, $crosstable, $cond_targets) = $rsrc->_resolve_condition (
78b948c3 822 $rel_info->{cond}, $f_obj, $rel, $rel
823 );
824 $self->throw_exception("Custom relationship '$rel' does not resolve to a join-free condition fragment")
825 if $crosstable;
826 $self->throw_exception(sprintf (
827 "Custom relationship '%s' not definitive - returns conditions instead of values for column(s): %s",
828 $rel,
72c2540d 829 map { "'$_'" } @$cond_targets
830 )) if $cond_targets;
aa56106b 831
832 $self->set_columns($cond);
a126983e 833
55e2d745 834 return 1;
835}
836
8091aa91 837=head2 update_from_related
503536d5 838
dad42de6 839=over 4
840
841=item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
842
843=item Return Value: not defined
844
845=back
846
30236e47 847 $book->update_from_related('author', $author_obj);
848
27f01d1f 849The same as L</"set_from_related">, but the changes are immediately updated
850in storage.
503536d5 851
852=cut
853
55e2d745 854sub update_from_related {
855 my $self = shift;
856 $self->set_from_related(@_);
857 $self->update;
858}
859
8091aa91 860=head2 delete_related
503536d5 861
dad42de6 862=over 4
30236e47 863
dad42de6 864=item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
865
69bc5f2b 866=item Return Value: $underlying_storage_rv
dad42de6 867
868=back
869
870Delete any related row, subject to the given conditions. Internally, this
871calls:
872
873 $self->search_related(@_)->delete
874
875And returns the result of that.
503536d5 876
877=cut
878
55e2d745 879sub delete_related {
880 my $self = shift;
64acc2bc 881 my $obj = $self->search_related(@_)->delete;
882 delete $self->{related_resultsets}->{$_[0]};
883 return $obj;
55e2d745 884}
885
ec353f53 886=head2 add_to_$rel
887
dad42de6 888B<Currently only available for C<has_many>, C<many_to_many> and 'multi' type
ec353f53 889relationships.>
890
dad42de6 891=head3 has_many / multi
892
ec353f53 893=over 4
894
dad42de6 895=item Arguments: \%col_data
896
897=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
898
899=back
900
901Creates/inserts a new result object. Internally, this calls:
902
903 $self->create_related($rel, @_)
904
905And returns the result of that.
906
907=head3 many_to_many
908
909=over 4
910
911=item Arguments: (\%col_data | L<$result|DBIx::Class::Manual::ResultClass>), \%link_col_data?
912
913=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
ec353f53 914
915=back
916
917 my $role = $schema->resultset('Role')->find(1);
918 $actor->add_to_roles($role);
dad42de6 919 # creates a My::DBIC::Schema::ActorRoles linking table result object
ec353f53 920
921 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
dad42de6 922 # creates a new My::DBIC::Schema::Role result object and the linking table
ec353f53 923 # object with an extra column in the link
924
dad42de6 925Adds a linking table object. If the first argument is a hash reference, the
926related object is created first with the column values in the hash. If an object
927reference is given, just the linking table object is created. In either case,
928any additional column values for the linking table object can be specified in
929C<\%link_col_data>.
930
931See L<DBIx::Class::Relationship/many_to_many> for additional details.
ec353f53 932
933=head2 set_$rel
934
dad42de6 935B<Currently only available for C<many_to_many> relationships.>
ec353f53 936
937=over 4
938
dad42de6 939=item Arguments: (\@hashrefs_of_col_data | L<\@result_objs|DBIx::Class::Manual::ResultClass>), $link_vals?
940
941=item Return Value: not defined
ec353f53 942
943=back
944
945 my $actor = $schema->resultset('Actor')->find(1);
fd323bf1 946 my @roles = $schema->resultset('Role')->search({ role =>
debccec3 947 { '-in' => ['Fred', 'Barney'] } } );
ec353f53 948
4d3a827d 949 $actor->set_roles(\@roles);
950 # Replaces all of $actor's previous roles with the two named
ec353f53 951
ac36a402 952 $actor->set_roles(\@roles, { salary => 15_000_000 });
953 # Sets a column in the link table for all roles
954
955
4d3a827d 956Replace all the related objects with the given reference to a list of
957objects. This does a C<delete> B<on the link table resultset> to remove the
958association between the current object and all related objects, then calls
959C<add_to_$rel> repeatedly to link all the new objects.
bba68c67 960
961Note that this means that this method will B<not> delete any objects in the
962table on the right side of the relation, merely that it will delete the link
963between them.
ec353f53 964
4d3a827d 965Due to a mistake in the original implementation of this method, it will also
966accept a list of objects or hash references. This is B<deprecated> and will be
967removed in a future version.
968
ec353f53 969=head2 remove_from_$rel
970
dad42de6 971B<Currently only available for C<many_to_many> relationships.>
ec353f53 972
973=over 4
974
dad42de6 975=item Arguments: L<$result|DBIx::Class::Manual::ResultClass>
976
977=item Return Value: not defined
ec353f53 978
979=back
980
981 my $role = $schema->resultset('Role')->find(1);
982 $actor->remove_from_roles($role);
dad42de6 983 # removes $role's My::DBIC::Schema::ActorRoles linking table result object
ec353f53 984
985Removes the link between the current object and the related object. Note that
986the related object itself won't be deleted unless you call ->delete() on
987it. This method just removes the link between the two objects.
988
0c11ad0e 989=head1 AUTHOR AND CONTRIBUTORS
55e2d745 990
0c11ad0e 991See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
55e2d745 992
993=head1 LICENSE
994
995You may distribute this code under the same terms as Perl itself.
996
997=cut
998
4d87db01 9991;