lib/DBIx/Class/Relationship/Base.pm

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