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