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