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<< $row_object->relationship >>, as opposed to
 172 C<< $rs->related_resultset('relationship') >>. In this case C<$row_object> 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<< $row->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 row 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 $row_obj->relationship
 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 =over 4
 253
 254 =item \@columns
 255
 256 An arrayref containing a list of accessors in the foreign class to create in
 257 the main class. If, for example, you do the following:
 258
 259   MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
 260     undef, {
 261       proxy => [ qw/notes/ ],
 262     });
 263
 264 Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:
 265
 266   my $cd = MyDB::Schema::CD->find(1);
 267   $cd->notes('Notes go here'); # set notes -- LinerNotes object is
 268                                # created if it doesn't exist
 269
 270 =item \%column
 271
 272 A hashref where each key is the accessor you want installed in the main class,
 273 and its value is the name of the original in the fireign class.
 274
 275   MyDB::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', {
 276       proxy => { cd_title => 'title' },
 277   });
 278
 279 This will create an accessor named C<cd_title> on the C<$track> row object.
 280
 281 =back
 282
 283 NOTE: you can pass a nested struct too, for example:
 284
 285   MyDB::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', {
 286     proxy => [ 'year', { cd_title => 'title' } ],
 287   });
 288
 289 =item accessor
 290
 291 Specifies the type of accessor that should be created for the relationship.
 292 Valid values are C<single> (for when there is only a single related object),
 293 C<multi> (when there can be many), and C<filter> (for when there is a single
 294 related object, but you also want the relationship accessor to double as
 295 a column accessor). For C<multi> accessors, an add_to_* method is also
 296 created, which calls C<create_related> for the relationship.
 297
 298 =item is_foreign_key_constraint
 299
 300 If you are using L<SQL::Translator> to create SQL for you and you find that it
 301 is creating constraints where it shouldn't, or not creating them where it
 302 should, set this attribute to a true or false value to override the detection
 303 of when to create constraints.
 304
 305 =item cascade_copy
 306
 307 If C<cascade_copy> is true on a C<has_many> relationship for an
 308 object, then when you copy the object all the related objects will
 309 be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
 310 in the C<$attr> hashref.
 311
 312 The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
 313 relationships.
 314
 315 =item cascade_delete
 316
 317 By default, DBIx::Class cascades deletes across C<has_many>,
 318 C<has_one> and C<might_have> relationships. You can disable this
 319 behaviour on a per-relationship basis by supplying
 320 C<< cascade_delete => 0 >> in the relationship attributes.
 321
 322 The cascaded operations are performed after the requested delete,
 323 so if your database has a constraint on the relationship, it will
 324 have deleted/updated the related records or raised an exception
 325 before DBIx::Class gets to perform the cascaded operation.
 326
 327 =item cascade_update
 328
 329 By default, DBIx::Class cascades updates across C<has_one> and
 330 C<might_have> relationships. You can disable this behaviour on a
 331 per-relationship basis by supplying C<< cascade_update => 0 >> in
 332 the relationship attributes.
 333
 334 This is not a RDMS style cascade update - it purely means that when
 335 an object has update called on it, all the related objects also
 336 have update called. It will not change foreign keys automatically -
 337 you must arrange to do this yourself.
 338
 339 =item on_delete / on_update
 340
 341 If you are using L<SQL::Translator> to create SQL for you, you can use these
 342 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
 343 type. If not supplied the SQLT parser will attempt to infer the constraint type by
 344 interrogating the attributes of the B<opposite> relationship. For any 'multi'
 345 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
 346 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
 347 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
 348 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
 349 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
 350 C<< on_delete => '' >>, and the same for C<on_update> respectively.
 351
 352 =item is_deferrable
 353
 354 Tells L<SQL::Translator> that the foreign key constraint it creates should be
 355 deferrable. In other words, the user may request that the constraint be ignored
 356 until the end of the transaction. Currently, only the PostgreSQL producer
 357 actually supports this.
 358
 359 =item add_fk_index
 360
 361 Tells L<SQL::Translator> to add an index for this constraint. Can also be
 362 specified globally in the args to L<DBIx::Class::Schema/deploy> or
 363 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
 364
 365 =back
 366
 367 =head2 register_relationship
 368
 369 =over 4
 370
 371 =item Arguments: $relname, $rel_info
 372
 373 =back
 374
 375 Registers a relationship on the class. This is called internally by
 376 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
 377
 378 =cut
 379
 380 sub register_relationship { }
 381
 382 =head2 related_resultset
 383
 384 =over 4
 385
 386 =item Arguments: $relationship_name
 387
 388 =item Return Value: $related_resultset
 389
 390 =back
 391
 392   $rs = $cd->related_resultset('artist');
 393
 394 Returns a L<DBIx::Class::ResultSet> for the relationship named
 395 $relationship_name.
 396
 397 =cut
 398
 399 sub related_resultset {
 400   my $self = shift;
 401   $self->throw_exception("Can't call *_related as class methods")
 402     unless ref $self;
 403   my $rel = shift;
 404   my $rel_info = $self->relationship_info($rel);
 405   $self->throw_exception( "No such relationship ${rel}" )
 406     unless $rel_info;
 407
 408   return $self->{related_resultsets}{$rel} ||= do {
 409     my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
 410     $attrs = { %{$rel_info->{attrs} || {}}, %$attrs };
 411
 412     $self->throw_exception( "Invalid query: @_" )
 413       if (@_ > 1 && (@_ % 2 == 1));
 414     my $query = ((@_ > 1) ? {@_} : shift);
 415
 416     my $source = $self->result_source;
 417
 418     # condition resolution may fail if an incomplete master-object prefetch
 419     # is encountered - that is ok during prefetch construction (not yet in_storage)
 420     my ($cond, $is_crosstable) = try {
 421       $source->_resolve_condition( $rel_info->{cond}, $rel, $self, $rel )
 422     }
 423     catch {
 424       if ($self->in_storage) {
 425         $self->throw_exception ($_);
 426       }
 427
 428       $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION;  # RV
 429     };
 430
 431     # keep in mind that the following if() block is part of a do{} - no return()s!!!
 432     if ($is_crosstable) {
 433       $self->throw_exception (
 434         "A cross-table relationship condition returned for statically declared '$rel'")
 435           unless ref $rel_info->{cond} eq 'CODE';
 436
 437       # A WHOREIFFIC hack to reinvoke the entire condition resolution
 438       # with the correct alias. Another way of doing this involves a
 439       # lot of state passing around, and the @_ positions are already
 440       # mapped out, making this crap a less icky option.
 441       #
 442       # The point of this exercise is to retain the spirit of the original
 443       # $obj->search_related($rel) where the resulting rset will have the
 444       # root alias as 'me', instead of $rel (as opposed to invoking
 445       # $rs->search_related)
 446
 447
 448       local $source->{_relationships}{me} = $source->{_relationships}{$rel};  # make the fake 'me' rel
 449       my $obj_table_alias = lc($source->source_name) . '__row';
 450
 451       $source->resultset->search(
 452         $self->ident_condition($obj_table_alias),
 453         { alias => $obj_table_alias },
 454       )->search_related('me', $query, $attrs)
 455     }
 456     else {
 457       # FIXME - this conditional doesn't seem correct - got to figure out
 458       # at some point what it does. Also the entire UNRESOLVABLE_CONDITION
 459       # business seems shady - we could simply not query *at all*
 460       if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
 461         my $reverse = $source->reverse_relationship_info($rel);
 462         foreach my $rev_rel (keys %$reverse) {
 463           if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
 464             $attrs->{related_objects}{$rev_rel} = [ $self ];
 465             weaken $attrs->{related_object}{$rev_rel}[0];
 466           } else {
 467             $attrs->{related_objects}{$rev_rel} = $self;
 468             weaken $attrs->{related_object}{$rev_rel};
 469           }
 470         }
 471       }
 472       elsif (ref $cond eq 'ARRAY') {
 473         $cond = [ map {
 474           if (ref $_ eq 'HASH') {
 475             my $hash;
 476             foreach my $key (keys %$_) {
 477               my $newkey = $key !~ /\./ ? "me.$key" : $key;
 478               $hash->{$newkey} = $_->{$key};
 479             }
 480             $hash;
 481           } else {
 482             $_;
 483           }
 484         } @$cond ];
 485       }
 486       elsif (ref $cond eq 'HASH') {
 487        foreach my $key (grep { ! /\./ } keys %$cond) {
 488           $cond->{"me.$key"} = delete $cond->{$key};
 489         }
 490       }
 491
 492       $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
 493       $self->result_source->related_source($rel)->resultset->search(
 494         $query, $attrs
 495       );
 496     }
 497   };
 498 }
 499
 500 =head2 search_related
 501
 502   @objects = $rs->search_related('relname', $cond, $attrs);
 503   $objects_rs = $rs->search_related('relname', $cond, $attrs);
 504
 505 Run a search on a related resultset. The search will be restricted to the
 506 item or items represented by the L<DBIx::Class::ResultSet> it was called
 507 upon. This method can be called on a ResultSet, a Row or a ResultSource class.
 508
 509 =cut
 510
 511 sub search_related {
 512   return shift->related_resultset(shift)->search(@_);
 513 }
 514
 515 =head2 search_related_rs
 516
 517   ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
 518
 519 This method works exactly the same as search_related, except that
 520 it guarantees a resultset, even in list context.
 521
 522 =cut
 523
 524 sub search_related_rs {
 525   return shift->related_resultset(shift)->search_rs(@_);
 526 }
 527
 528 =head2 count_related
 529
 530   $obj->count_related('relname', $cond, $attrs);
 531
 532 Returns the count of all the items in the related resultset, restricted by the
 533 current item or where conditions. Can be called on a
 534 L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
 535 L<DBIx::Class::Manual::Glossary/"Row"> object.
 536
 537 =cut
 538
 539 sub count_related {
 540   my $self = shift;
 541   return $self->search_related(@_)->count;
 542 }
 543
 544 =head2 new_related
 545
 546   my $new_obj = $obj->new_related('relname', \%col_data);
 547
 548 Create a new item of the related foreign class. If called on a
 549 L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically
 550 set any foreign key columns of the new object to the related primary
 551 key columns of the source object for you.  The newly created item will
 552 not be saved into your storage until you call L<DBIx::Class::Row/insert>
 553 on it.
 554
 555 =cut
 556
 557 sub new_related {
 558   my ($self, $rel, $values, $attrs) = @_;
 559   return $self->search_related($rel)->new($values, $attrs);
 560 }
 561
 562 =head2 create_related
 563
 564   my $new_obj = $obj->create_related('relname', \%col_data);
 565
 566 Creates a new item, similarly to new_related, and also inserts the item's data
 567 into your storage medium. See the distinction between C<create> and C<new>
 568 in L<DBIx::Class::ResultSet> for details.
 569
 570 =cut
 571
 572 sub create_related {
 573   my $self = shift;
 574   my $rel = shift;
 575
 576   $self->throw_exception("Can't call *_related as class methods")
 577     unless ref $self;
 578
 579   # we need to stop and check if this is at all possible. If this is
 580   # an extended relationship with an incomplete definition, we should
 581   # just forbid it right now.
 582   my $rel_info = $self->result_source->relationship_info($rel);
 583   if (ref $rel_info->{cond} eq 'CODE') {
 584     my ($cond, $ext) = $rel_info->{cond}->({
 585       self_alias => 'me',
 586       foreign_alias => $rel,
 587       self_rowobj => $self,
 588       self_resultsource => $self->result_source,
 589       foreign_relname => $rel,
 590     });
 591     $self->throw_exception("unable to set_from_related - no simplified condition available for '${rel}'")
 592       unless $ext;
 593
 594     # now we need to make sure all non-identity relationship
 595     # definitions are overriden.
 596     my ($argref) = @_;
 597     while ( my($col, $value) = each %$ext ) {
 598       $col =~ s/^$rel\.//;
 599       my $vref = ref $value;
 600       if ($vref eq 'HASH') {
 601         if (keys(%$value) && (keys %$value)[0] ne '=' &&
 602             !exists $argref->{$col}) {
 603           $self->throw_exception("unable to set_from_related via complex '${rel}' condition on column(s): '${col}'")
 604         }
 605       }
 606     }
 607   }
 608
 609   my $obj = $self->search_related($rel)->create(@_);
 610   delete $self->{related_resultsets}->{$rel};
 611   return $obj;
 612 }
 613
 614 =head2 find_related
 615
 616   my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
 617
 618 Attempt to find a related object using its primary key or unique constraints.
 619 See L<DBIx::Class::ResultSet/find> for details.
 620
 621 =cut
 622
 623 sub find_related {
 624   my $self = shift;
 625   my $rel = shift;
 626   return $self->search_related($rel)->find(@_);
 627 }
 628
 629 =head2 find_or_new_related
 630
 631   my $new_obj = $obj->find_or_new_related('relname', \%col_data);
 632
 633 Find an item of a related class. If none exists, instantiate a new item of the
 634 related class. The object will not be saved into your storage until you call
 635 L<DBIx::Class::Row/insert> on it.
 636
 637 =cut
 638
 639 sub find_or_new_related {
 640   my $self = shift;
 641   my $obj = $self->find_related(@_);
 642   return defined $obj ? $obj : $self->new_related(@_);
 643 }
 644
 645 =head2 find_or_create_related
 646
 647   my $new_obj = $obj->find_or_create_related('relname', \%col_data);
 648
 649 Find or create an item of a related class. See
 650 L<DBIx::Class::ResultSet/find_or_create> for details.
 651
 652 =cut
 653
 654 sub find_or_create_related {
 655   my $self = shift;
 656   my $obj = $self->find_related(@_);
 657   return (defined($obj) ? $obj : $self->create_related(@_));
 658 }
 659
 660 =head2 update_or_create_related
 661
 662   my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
 663
 664 Update or create an item of a related class. See
 665 L<DBIx::Class::ResultSet/update_or_create> for details.
 666
 667 =cut
 668
 669 sub update_or_create_related {
 670   my $self = shift;
 671   my $rel = shift;
 672   return $self->related_resultset($rel)->update_or_create(@_);
 673 }
 674
 675 =head2 set_from_related
 676
 677   $book->set_from_related('author', $author_obj);
 678   $book->author($author_obj);                      ## same thing
 679
 680 Set column values on the current object, using related values from the given
 681 related object. This is used to associate previously separate objects, for
 682 example, to set the correct author for a book, find the Author object, then
 683 call set_from_related on the book.
 684
 685 This is called internally when you pass existing objects as values to
 686 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
 687
 688 The columns are only set in the local copy of the object, call L</update> to
 689 set them in the storage.
 690
 691 =cut
 692
 693 sub set_from_related {
 694   my ($self, $rel, $f_obj) = @_;
 695
 696   my $rel_info = $self->relationship_info($rel)
 697     or $self->throw_exception( "No such relationship ${rel}" );
 698
 699   if (defined $f_obj) {
 700     my $f_class = $rel_info->{class};
 701     $self->throw_exception( "Object $f_obj isn't a ".$f_class )
 702       unless blessed $f_obj and $f_obj->isa($f_class);
 703   }
 704
 705   my ($cond, $crosstable) = $self->result_source->_resolve_condition
 706     ($rel_info->{cond}, $f_obj, $rel, $rel);
 707
 708   $self->throw_exception(
 709     "Custom relationship '$rel' does not resolve to a join-free condition fragment"
 710   ) if $crosstable;
 711
 712   $self->set_columns($cond);
 713
 714   return 1;
 715 }
 716
 717 =head2 update_from_related
 718
 719   $book->update_from_related('author', $author_obj);
 720
 721 The same as L</"set_from_related">, but the changes are immediately updated
 722 in storage.
 723
 724 =cut
 725
 726 sub update_from_related {
 727   my $self = shift;
 728   $self->set_from_related(@_);
 729   $self->update;
 730 }
 731
 732 =head2 delete_related
 733
 734   $obj->delete_related('relname', $cond, $attrs);
 735
 736 Delete any related item subject to the given conditions.
 737
 738 =cut
 739
 740 sub delete_related {
 741   my $self = shift;
 742   my $obj = $self->search_related(@_)->delete;
 743   delete $self->{related_resultsets}->{$_[0]};
 744   return $obj;
 745 }
 746
 747 =head2 add_to_$rel
 748
 749 B<Currently only available for C<has_many>, C<many-to-many> and 'multi' type
 750 relationships.>
 751
 752 =over 4
 753
 754 =item Arguments: ($foreign_vals | $obj), $link_vals?
 755
 756 =back
 757
 758   my $role = $schema->resultset('Role')->find(1);
 759   $actor->add_to_roles($role);
 760       # creates a My::DBIC::Schema::ActorRoles linking table row object
 761
 762   $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
 763       # creates a new My::DBIC::Schema::Role row object and the linking table
 764       # object with an extra column in the link
 765
 766 Adds a linking table object for C<$obj> or C<$foreign_vals>. If the first
 767 argument is a hash reference, the related object is created first with the
 768 column values in the hash. If an object reference is given, just the linking
 769 table object is created. In either case, any additional column values for the
 770 linking table object can be specified in C<$link_vals>.
 771
 772 =head2 set_$rel
 773
 774 B<Currently only available for C<many-to-many> relationships.>
 775
 776 =over 4
 777
 778 =item Arguments: (\@hashrefs | \@objs), $link_vals?
 779
 780 =back
 781
 782   my $actor = $schema->resultset('Actor')->find(1);
 783   my @roles = $schema->resultset('Role')->search({ role =>
 784      { '-in' => ['Fred', 'Barney'] } } );
 785
 786   $actor->set_roles(\@roles);
 787      # Replaces all of $actor's previous roles with the two named
 788
 789   $actor->set_roles(\@roles, { salary => 15_000_000 });
 790      # Sets a column in the link table for all roles
 791
 792
 793 Replace all the related objects with the given reference to a list of
 794 objects. This does a C<delete> B<on the link table resultset> to remove the
 795 association between the current object and all related objects, then calls
 796 C<add_to_$rel> repeatedly to link all the new objects.
 797
 798 Note that this means that this method will B<not> delete any objects in the
 799 table on the right side of the relation, merely that it will delete the link
 800 between them.
 801
 802 Due to a mistake in the original implementation of this method, it will also
 803 accept a list of objects or hash references. This is B<deprecated> and will be
 804 removed in a future version.
 805
 806 =head2 remove_from_$rel
 807
 808 B<Currently only available for C<many-to-many> relationships.>
 809
 810 =over 4
 811
 812 =item Arguments: $obj
 813
 814 =back
 815
 816   my $role = $schema->resultset('Role')->find(1);
 817   $actor->remove_from_roles($role);
 818       # removes $role's My::DBIC::Schema::ActorRoles linking table row object
 819
 820 Removes the link between the current object and the related object. Note that
 821 the related object itself won't be deleted unless you call ->delete() on
 822 it. This method just removes the link between the two objects.
 823
 824 =head1 AUTHORS
 825
 826 Matt S. Trout <mst@shadowcatsystems.co.uk>
 827
 828 =head1 LICENSE
 829
 830 You may distribute this code under the same terms as Perl itself.
 831
 832 =cut
 833
 834 1;