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   $_[0]->throw_exception(
 503     '$result->related_resultset() no longer accepts extra search arguments, '
 504   . 'you need to switch to ...->related_resultset($relname)->search_rs(...) '
 505   . 'instead (it was never documented and more importantly could never work '
 506   . 'reliably due to the heavy caching involved)'
 507   ) if @_ > 2;
 508
 509   $_[0]->throw_exception("Can't call *_related as class methods")
 510     unless ref $_[0];
 511
 512   return $_[0]->{related_resultsets}{$_[1]}
 513     if defined $_[0]->{related_resultsets}{$_[1]};
 514
 515   my ($self, $rel) = @_;
 516
 517   return $self->{related_resultsets}{$rel} = do {
 518
 519     my $rsrc = $self->result_source;
 520
 521     my $rel_info = $rsrc->relationship_info($rel)
 522       or $self->throw_exception( "No such relationship '$rel'" );
 523
 524     my $cond_res = $rsrc->_resolve_relationship_condition(
 525       rel_name => $rel,
 526       self_result_object => $self,
 527
 528       # this may look weird, but remember that we are making a resultset
 529       # out of an existing object, with the new source being at the head
 530       # of the FROM chain. Having a 'me' alias is nothing but expected there
 531       foreign_alias => 'me',
 532
 533       self_alias => "!!!\xFF()!!!_SHOULD_NEVER_BE_SEEN_IN_USE_!!!()\xFF!!!",
 534
 535       # not strictly necessary, but shouldn't hurt either
 536       require_join_free_condition => !!(ref $rel_info->{cond} ne 'CODE'),
 537     );
 538
 539     # keep in mind that the following if() block is part of a do{} - no return()s!!!
 540     if (
 541       ! $cond_res->{join_free_condition}
 542         and
 543       ref $rel_info->{cond} eq 'CODE'
 544     ) {
 545
 546       # A WHOREIFFIC hack to reinvoke the entire condition resolution
 547       # with the correct alias. Another way of doing this involves a
 548       # lot of state passing around, and the @_ positions are already
 549       # mapped out, making this crap a less icky option.
 550       #
 551       # The point of this exercise is to retain the spirit of the original
 552       # $obj->search_related($rel) where the resulting rset will have the
 553       # root alias as 'me', instead of $rel (as opposed to invoking
 554       # $rs->search_related)
 555
 556       # make the fake 'me' rel
 557       local $rsrc->{_relationships}{me} = {
 558         %{ $rsrc->{_relationships}{$rel} },
 559         _original_name => $rel,
 560       };
 561
 562       my $obj_table_alias = lc($rsrc->source_name) . '__row';
 563       $obj_table_alias =~ s/\W+/_/g;
 564
 565       $rsrc->resultset->search(
 566         $self->ident_condition($obj_table_alias),
 567         { alias => $obj_table_alias },
 568       )->search_related('me', undef, $rel_info->{attrs})
 569     }
 570     else {
 571
 572       # FIXME - this conditional doesn't seem correct - got to figure out
 573       # at some point what it does. Also the entire UNRESOLVABLE_CONDITION
 574       # business seems shady - we could simply not query *at all*
 575       my $attrs;
 576       if ( $cond_res->{join_free_condition} eq UNRESOLVABLE_CONDITION ) {
 577         $attrs = { %{$rel_info->{attrs}} };
 578         my $reverse = $rsrc->reverse_relationship_info($rel);
 579         foreach my $rev_rel (keys %$reverse) {
 580           if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
 581             weaken($attrs->{related_objects}{$rev_rel}[0] = $self);
 582           } else {
 583             weaken($attrs->{related_objects}{$rev_rel} = $self);
 584           }
 585         }
 586       }
 587
 588       $rsrc->related_source($rel)->resultset->search(
 589         $cond_res->{join_free_condition},
 590         $attrs || $rel_info->{attrs},
 591       );
 592     }
 593   };
 594 }
 595
 596 =head2 search_related
 597
 598 =over 4
 599
 600 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
 601
 602 =item Return Value: L<$resultset|DBIx::Class::ResultSet> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
 603
 604 =back
 605
 606 Run a search on a related resultset. The search will be restricted to the
 607 results represented by the L<DBIx::Class::ResultSet> it was called
 608 upon.
 609
 610 See L<DBIx::Class::ResultSet/search_related> for more information.
 611
 612 =cut
 613
 614 sub search_related {
 615   return shift->related_resultset(shift)->search(@_);
 616 }
 617
 618 =head2 search_related_rs
 619
 620 This method works exactly the same as search_related, except that
 621 it guarantees a resultset, even in list context.
 622
 623 =cut
 624
 625 sub search_related_rs {
 626   return shift->related_resultset(shift)->search_rs(@_);
 627 }
 628
 629 =head2 count_related
 630
 631 =over 4
 632
 633 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
 634
 635 =item Return Value: $count
 636
 637 =back
 638
 639 Returns the count of all the rows in the related resultset, restricted by the
 640 current result or where conditions.
 641
 642 =cut
 643
 644 sub count_related {
 645   shift->search_related(@_)->count;
 646 }
 647
 648 =head2 new_related
 649
 650 =over 4
 651
 652 =item Arguments: $rel_name, \%col_data
 653
 654 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 655
 656 =back
 657
 658 Create a new result object of the related foreign class.  It will magically set
 659 any foreign key columns of the new object to the related primary key columns
 660 of the source object for you.  The newly created result will not be saved into
 661 your storage until you call L<DBIx::Class::Row/insert> on it.
 662
 663 =cut
 664
 665 sub new_related {
 666   my ($self, $rel, $data) = @_;
 667
 668   return $self->search_related($rel)->new_result( $self->result_source->_resolve_relationship_condition (
 669     infer_values_based_on => $data,
 670     rel_name => $rel,
 671     self_result_object => $self,
 672     foreign_alias => $rel,
 673     self_alias => 'me',
 674   )->{inferred_values} );
 675 }
 676
 677 =head2 create_related
 678
 679 =over 4
 680
 681 =item Arguments: $rel_name, \%col_data
 682
 683 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 684
 685 =back
 686
 687   my $result = $obj->create_related($rel_name, \%col_data);
 688
 689 Creates a new result object, similarly to new_related, and also inserts the
 690 result's data into your storage medium. See the distinction between C<create>
 691 and C<new> in L<DBIx::Class::ResultSet> for details.
 692
 693 =cut
 694
 695 sub create_related {
 696   my $self = shift;
 697   my $rel = shift;
 698   my $obj = $self->new_related($rel, @_)->insert;
 699   delete $self->{related_resultsets}->{$rel};
 700   return $obj;
 701 }
 702
 703 =head2 find_related
 704
 705 =over 4
 706
 707 =item Arguments: $rel_name, \%col_data | @pk_values, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
 708
 709 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
 710
 711 =back
 712
 713   my $result = $obj->find_related($rel_name, \%col_data);
 714
 715 Attempt to find a related object using its primary key or unique constraints.
 716 See L<DBIx::Class::ResultSet/find> for details.
 717
 718 =cut
 719
 720 sub find_related {
 721   #my ($self, $rel, @args) = @_;
 722   return shift->search_related(shift)->find(@_);
 723 }
 724
 725 =head2 find_or_new_related
 726
 727 =over 4
 728
 729 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
 730
 731 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 732
 733 =back
 734
 735 Find a result object of a related class.  See L<DBIx::Class::ResultSet/find_or_new>
 736 for details.
 737
 738 =cut
 739
 740 sub find_or_new_related {
 741   my $self = shift;
 742   my $obj = $self->find_related(@_);
 743   return defined $obj ? $obj : $self->new_related(@_);
 744 }
 745
 746 =head2 find_or_create_related
 747
 748 =over 4
 749
 750 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
 751
 752 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 753
 754 =back
 755
 756 Find or create a result object of a related class. See
 757 L<DBIx::Class::ResultSet/find_or_create> for details.
 758
 759 =cut
 760
 761 sub find_or_create_related {
 762   my $self = shift;
 763   my $obj = $self->find_related(@_);
 764   return (defined($obj) ? $obj : $self->create_related(@_));
 765 }
 766
 767 =head2 update_or_create_related
 768
 769 =over 4
 770
 771 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
 772
 773 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 774
 775 =back
 776
 777 Update or create a result object of a related class. See
 778 L<DBIx::Class::ResultSet/update_or_create> for details.
 779
 780 =cut
 781
 782 sub update_or_create_related {
 783   #my ($self, $rel, @args) = @_;
 784   shift->related_resultset(shift)->update_or_create(@_);
 785 }
 786
 787 =head2 set_from_related
 788
 789 =over 4
 790
 791 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
 792
 793 =item Return Value: not defined
 794
 795 =back
 796
 797   $book->set_from_related('author', $author_obj);
 798   $book->author($author_obj);                      ## same thing
 799
 800 Set column values on the current object, using related values from the given
 801 related object. This is used to associate previously separate objects, for
 802 example, to set the correct author for a book, find the Author object, then
 803 call set_from_related on the book.
 804
 805 This is called internally when you pass existing objects as values to
 806 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
 807
 808 The columns are only set in the local copy of the object, call
 809 L<update|DBIx::Class::Row/update> to update them in the storage.
 810
 811 =cut
 812
 813 sub set_from_related {
 814   my ($self, $rel, $f_obj) = @_;
 815
 816   $self->set_columns( $self->result_source->_resolve_relationship_condition (
 817     infer_values_based_on => {},
 818     rel_name => $rel,
 819     foreign_values => $f_obj,
 820     foreign_alias => $rel,
 821     self_alias => 'me',
 822   )->{inferred_values} );
 823
 824   return 1;
 825 }
 826
 827 =head2 update_from_related
 828
 829 =over 4
 830
 831 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
 832
 833 =item Return Value: not defined
 834
 835 =back
 836
 837   $book->update_from_related('author', $author_obj);
 838
 839 The same as L</"set_from_related">, but the changes are immediately updated
 840 in storage.
 841
 842 =cut
 843
 844 sub update_from_related {
 845   my $self = shift;
 846   $self->set_from_related(@_);
 847   $self->update;
 848 }
 849
 850 =head2 delete_related
 851
 852 =over 4
 853
 854 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
 855
 856 =item Return Value: $underlying_storage_rv
 857
 858 =back
 859
 860 Delete any related row, subject to the given conditions.  Internally, this
 861 calls:
 862
 863   $self->search_related(@_)->delete
 864
 865 And returns the result of that.
 866
 867 =cut
 868
 869 sub delete_related {
 870   my $self = shift;
 871   my $obj = $self->search_related(@_)->delete;
 872   delete $self->{related_resultsets}->{$_[0]};
 873   return $obj;
 874 }
 875
 876 =head2 add_to_$rel
 877
 878 B<Currently only available for C<has_many>, C<many_to_many> and 'multi' type
 879 relationships.>
 880
 881 =head3 has_many / multi
 882
 883 =over 4
 884
 885 =item Arguments: \%col_data
 886
 887 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 888
 889 =back
 890
 891 Creates/inserts a new result object.  Internally, this calls:
 892
 893   $self->create_related($rel, @_)
 894
 895 And returns the result of that.
 896
 897 =head3 many_to_many
 898
 899 =over 4
 900
 901 =item Arguments: (\%col_data | L<$result|DBIx::Class::Manual::ResultClass>), \%link_col_data?
 902
 903 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 904
 905 =back
 906
 907   my $role = $schema->resultset('Role')->find(1);
 908   $actor->add_to_roles($role);
 909       # creates a My::DBIC::Schema::ActorRoles linking table result object
 910
 911   $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
 912       # creates a new My::DBIC::Schema::Role result object and the linking table
 913       # object with an extra column in the link
 914
 915 Adds a linking table object. If the first argument is a hash reference, the
 916 related object is created first with the column values in the hash. If an object
 917 reference is given, just the linking table object is created. In either case,
 918 any additional column values for the linking table object can be specified in
 919 C<\%link_col_data>.
 920
 921 See L<DBIx::Class::Relationship/many_to_many> for additional details.
 922
 923 =head2 set_$rel
 924
 925 B<Currently only available for C<many_to_many> relationships.>
 926
 927 =over 4
 928
 929 =item Arguments: (\@hashrefs_of_col_data | L<\@result_objs|DBIx::Class::Manual::ResultClass>), $link_vals?
 930
 931 =item Return Value: not defined
 932
 933 =back
 934
 935   my $actor = $schema->resultset('Actor')->find(1);
 936   my @roles = $schema->resultset('Role')->search({ role =>
 937      { '-in' => ['Fred', 'Barney'] } } );
 938
 939   $actor->set_roles(\@roles);
 940      # Replaces all of $actor's previous roles with the two named
 941
 942   $actor->set_roles(\@roles, { salary => 15_000_000 });
 943      # Sets a column in the link table for all roles
 944
 945
 946 Replace all the related objects with the given reference to a list of
 947 objects. This does a C<delete> B<on the link table resultset> to remove the
 948 association between the current object and all related objects, then calls
 949 C<add_to_$rel> repeatedly to link all the new objects.
 950
 951 Note that this means that this method will B<not> delete any objects in the
 952 table on the right side of the relation, merely that it will delete the link
 953 between them.
 954
 955 Due to a mistake in the original implementation of this method, it will also
 956 accept a list of objects or hash references. This is B<deprecated> and will be
 957 removed in a future version.
 958
 959 =head2 remove_from_$rel
 960
 961 B<Currently only available for C<many_to_many> relationships.>
 962
 963 =over 4
 964
 965 =item Arguments: L<$result|DBIx::Class::Manual::ResultClass>
 966
 967 =item Return Value: not defined
 968
 969 =back
 970
 971   my $role = $schema->resultset('Role')->find(1);
 972   $actor->remove_from_roles($role);
 973       # removes $role's My::DBIC::Schema::ActorRoles linking table result object
 974
 975 Removes the link between the current object and the related object. Note that
 976 the related object itself won't be deleted unless you call ->delete() on
 977 it. This method just removes the link between the two objects.
 978
 979 =head1 FURTHER QUESTIONS?
 980
 981 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
 982
 983 =head1 COPYRIGHT AND LICENSE
 984
 985 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
 986 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
 987 redistribute it and/or modify it under the same terms as the
 988 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
 989
 990 =cut
 991
 992 1;