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