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