lib/DBIx/Class/Relationship/Base.pm

   1 package DBIx::Class::Relationship::Base;
   2
   3 use strict;
   4 use warnings;
   5
   6 use Scalar::Util ();
   7 use base qw/DBIx::Class/;
   8
   9 =head1 NAME
  10
  11 DBIx::Class::Relationship::Base - Inter-table relationships
  12
  13 =head1 SYNOPSIS
  14
  15 =head1 DESCRIPTION
  16
  17 This class provides methods to describe the relationships between the
  18 tables in your database model. These are the "bare bones" relationships
  19 methods, for predefined ones, look in L<DBIx::Class::Relationship>.
  20
  21 =head1 METHODS
  22
  23 =head2 add_relationship
  24
  25 =over 4
  26
  27 =item Arguments: 'relname', 'Foreign::Class', $cond, $attrs
  28
  29 =back
  30
  31   __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);
  32
  33 The condition needs to be an L<SQL::Abstract>-style representation of the
  34 join between the tables. When resolving the condition for use in a C<JOIN>,
  35 keys using the pseudo-table C<foreign> are resolved to mean "the Table on the
  36 other side of the relationship", and values using the pseudo-table C<self>
  37 are resolved to mean "the Table this class is representing". Other
  38 restrictions, such as by value, sub-select and other tables, may also be
  39 used. Please check your database for C<JOIN> parameter support.
  40
  41 For example, if you're creating a relationship from C<Author> to C<Book>, where
  42 the C<Book> table has a column C<author_id> containing the ID of the C<Author>
  43 row:
  44
  45   { 'foreign.author_id' => 'self.id' }
  46
  47 will result in the C<JOIN> clause
  48
  49   author me JOIN book book ON book.author_id = me.id
  50
  51 For multi-column foreign keys, you will need to specify a C<foreign>-to-C<self>
  52 mapping for each column in the key. For example, if you're creating a
  53 relationship from C<Book> to C<Edition>, where the C<Edition> table refers to a
  54 publisher and a type (e.g. "paperback"):
  55
  56   {
  57     'foreign.publisher_id' => 'self.publisher_id',
  58     'foreign.type_id'      => 'self.type_id',
  59   }
  60
  61 This will result in the C<JOIN> clause:
  62
  63   book me JOIN edition edition ON edition.publisher_id = me.publisher_id
  64     AND edition.type_id = me.type_id
  65
  66 Each key-value pair provided in a hashref will be used as C<AND>ed conditions.
  67 To add an C<OR>ed condition, use an arrayref of hashrefs. See the
  68 L<SQL::Abstract> documentation for more details.
  69
  70 In addition to standard result set attributes, the following attributes are also valid:
  71
  72 =over 4
  73
  74 =item join_type
  75
  76 Explicitly specifies the type of join to use in the relationship. Any SQL
  77 join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
  78 command immediately before C<JOIN>.
  79
  80 =item proxy
  81
  82 An arrayref containing a list of accessors in the foreign class to create in
  83 the main class. If, for example, you do the following:
  84
  85   MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
  86     undef, {
  87       proxy => [ qw/notes/ ],
  88     });
  89
  90 Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:
  91
  92   my $cd = MyDB::Schema::CD->find(1);
  93   $cd->notes('Notes go here'); # set notes -- LinerNotes object is
  94                                # created if it doesn't exist
  95
  96 =item accessor
  97
  98 Specifies the type of accessor that should be created for the relationship.
  99 Valid values are C<single> (for when there is only a single related object),
 100 C<multi> (when there can be many), and C<filter> (for when there is a single
 101 related object, but you also want the relationship accessor to double as
 102 a column accessor). For C<multi> accessors, an add_to_* method is also
 103 created, which calls C<create_related> for the relationship.
 104
 105 =item is_foreign_key_constraint
 106
 107 If you are using L<SQL::Translator> to create SQL for you and you find that it
 108 is creating constraints where it shouldn't, or not creating them where it
 109 should, set this attribute to a true or false value to override the detection
 110 of when to create constraints.
 111
 112 =item on_delete / on_update
 113
 114 If you are using L<SQL::Translator> to create SQL for you, you can use these
 115 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
 116 type. If not supplied the SQLT parser will attempt to infer the constraint type by
 117 interrogating the attributes of the B<opposite> relationship. For any 'multi'
 118 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
 119 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
 120 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
 121 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
 122 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
 123 C<< on_delete => '' >>, and the same for C<on_update> respectively.
 124
 125 =item is_deferrable
 126
 127 Tells L<SQL::Translator> that the foreign key constraint it creates should be
 128 deferrable. In other words, the user may request that the constraint be ignored
 129 until the end of the transaction. Currently, only the PostgreSQL producer
 130 actually supports this.
 131
 132 =item add_fk_index
 133
 134 Tells L<SQL::Translator> to add an index for this constraint. Can also be
 135 specified globally in the args to L<DBIx::Class::Schema/deploy> or
 136 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
 137
 138 =back
 139
 140 =head2 register_relationship
 141
 142 =over 4
 143
 144 =item Arguments: $relname, $rel_info
 145
 146 =back
 147
 148 Registers a relationship on the class. This is called internally by
 149 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
 150
 151 =cut
 152
 153 sub register_relationship { }
 154
 155 =head2 related_resultset
 156
 157 =over 4
 158
 159 =item Arguments: $relationship_name
 160
 161 =item Return Value: $related_resultset
 162
 163 =back
 164
 165   $rs = $cd->related_resultset('artist');
 166
 167 Returns a L<DBIx::Class::ResultSet> for the relationship named
 168 $relationship_name.
 169
 170 =cut
 171
 172 sub related_resultset {
 173   my $self = shift;
 174   $self->throw_exception("Can't call *_related as class methods")
 175     unless ref $self;
 176   my $rel = shift;
 177   my $rel_obj = $self->relationship_info($rel);
 178   $self->throw_exception( "No such relationship ${rel}" )
 179     unless $rel_obj;
 180
 181   return $self->{related_resultsets}{$rel} ||= do {
 182     my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
 183     $attrs = { %{$rel_obj->{attrs} || {}}, %$attrs };
 184
 185     $self->throw_exception( "Invalid query: @_" )
 186       if (@_ > 1 && (@_ % 2 == 1));
 187     my $query = ((@_ > 1) ? {@_} : shift);
 188
 189     my $cond = $self->result_source->resolve_condition(
 190       $rel_obj->{cond}, $rel, $self
 191     );
 192     if (ref $cond eq 'ARRAY') {
 193       $cond = [ map {
 194         if (ref $_ eq 'HASH') {
 195           my $hash;
 196           foreach my $key (keys %$_) {
 197             my $newkey = $key =~ /\./ ? "me.$key" : $key;
 198             $hash->{$newkey} = $_->{$key};
 199           }
 200           $hash;
 201         } else {
 202           $_;
 203         }
 204       } @$cond ];
 205     } else {
 206       foreach my $key (grep { ! /\./ } keys %$cond) {
 207         $cond->{"me.$key"} = delete $cond->{$key};
 208       }
 209     }
 210     $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
 211     $self->result_source->related_source($rel)->resultset->search(
 212       $query, $attrs
 213     );
 214   };
 215 }
 216
 217 =head2 search_related
 218
 219   @objects = $rs->search_related('relname', $cond, $attrs);
 220   $objects_rs = $rs->search_related('relname', $cond, $attrs);
 221
 222 Run a search on a related resultset. The search will be restricted to the
 223 item or items represented by the L<DBIx::Class::ResultSet> it was called
 224 upon. This method can be called on a ResultSet, a Row or a ResultSource class.
 225
 226 =cut
 227
 228 sub search_related {
 229   return shift->related_resultset(shift)->search(@_);
 230 }
 231
 232 =head2 search_related_rs
 233
 234   ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
 235
 236 This method works exactly the same as search_related, except that
 237 it guarantees a restultset, even in list context.
 238
 239 =cut
 240
 241 sub search_related_rs {
 242   return shift->related_resultset(shift)->search_rs(@_);
 243 }
 244
 245 =head2 count_related
 246
 247   $obj->count_related('relname', $cond, $attrs);
 248
 249 Returns the count of all the items in the related resultset, restricted by the
 250 current item or where conditions. Can be called on a
 251 L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
 252 L<DBIx::Class::Manual::Glossary/"Row"> object.
 253
 254 =cut
 255
 256 sub count_related {
 257   my $self = shift;
 258   return $self->search_related(@_)->count;
 259 }
 260
 261 =head2 new_related
 262
 263   my $new_obj = $obj->new_related('relname', \%col_data);
 264
 265 Create a new item of the related foreign class. If called on a
 266 L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically
 267 set any foreign key columns of the new object to the related primary
 268 key columns of the source object for you.  The newly created item will
 269 not be saved into your storage until you call L<DBIx::Class::Row/insert>
 270 on it.
 271
 272 =cut
 273
 274 sub new_related {
 275   my ($self, $rel, $values, $attrs) = @_;
 276   return $self->search_related($rel)->new($values, $attrs);
 277 }
 278
 279 =head2 create_related
 280
 281   my $new_obj = $obj->create_related('relname', \%col_data);
 282
 283 Creates a new item, similarly to new_related, and also inserts the item's data
 284 into your storage medium. See the distinction between C<create> and C<new>
 285 in L<DBIx::Class::ResultSet> for details.
 286
 287 =cut
 288
 289 sub create_related {
 290   my $self = shift;
 291   my $rel = shift;
 292   my $obj = $self->search_related($rel)->create(@_);
 293   delete $self->{related_resultsets}->{$rel};
 294   return $obj;
 295 }
 296
 297 =head2 find_related
 298
 299   my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
 300
 301 Attempt to find a related object using its primary key or unique constraints.
 302 See L<DBIx::Class::ResultSet/find> for details.
 303
 304 =cut
 305
 306 sub find_related {
 307   my $self = shift;
 308   my $rel = shift;
 309   return $self->search_related($rel)->find(@_);
 310 }
 311
 312 =head2 find_or_new_related
 313
 314   my $new_obj = $obj->find_or_new_related('relname', \%col_data);
 315
 316 Find an item of a related class. If none exists, instantiate a new item of the
 317 related class. The object will not be saved into your storage until you call
 318 L<DBIx::Class::Row/insert> on it.
 319
 320 =cut
 321
 322 sub find_or_new_related {
 323   my $self = shift;
 324   my $obj = $self->find_related(@_);
 325   return defined $obj ? $obj : $self->new_related(@_);
 326 }
 327
 328 =head2 find_or_create_related
 329
 330   my $new_obj = $obj->find_or_create_related('relname', \%col_data);
 331
 332 Find or create an item of a related class. See
 333 L<DBIx::Class::ResultSet/find_or_create> for details.
 334
 335 =cut
 336
 337 sub find_or_create_related {
 338   my $self = shift;
 339   my $obj = $self->find_related(@_);
 340   return (defined($obj) ? $obj : $self->create_related(@_));
 341 }
 342
 343 =head2 update_or_create_related
 344
 345   my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
 346
 347 Update or create an item of a related class. See
 348 L<DBIx::Class::ResultSet/update_or_create> for details.
 349
 350 =cut
 351
 352 sub update_or_create_related {
 353   my $self = shift;
 354   my $rel = shift;
 355   return $self->related_resultset($rel)->update_or_create(@_);
 356 }
 357
 358 =head2 set_from_related
 359
 360   $book->set_from_related('author', $author_obj);
 361   $book->author($author_obj);                      ## same thing
 362
 363 Set column values on the current object, using related values from the given
 364 related object. This is used to associate previously separate objects, for
 365 example, to set the correct author for a book, find the Author object, then
 366 call set_from_related on the book.
 367
 368 This is called internally when you pass existing objects as values to
 369 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to acessor.
 370
 371 The columns are only set in the local copy of the object, call L</update> to
 372 set them in the storage.
 373
 374 =cut
 375
 376 sub set_from_related {
 377   my ($self, $rel, $f_obj) = @_;
 378   my $rel_obj = $self->relationship_info($rel);
 379   $self->throw_exception( "No such relationship ${rel}" ) unless $rel_obj;
 380   my $cond = $rel_obj->{cond};
 381   $self->throw_exception(
 382     "set_from_related can only handle a hash condition; the ".
 383     "condition for $rel is of type ".
 384     (ref $cond ? ref $cond : 'plain scalar')
 385   ) unless ref $cond eq 'HASH';
 386   if (defined $f_obj) {
 387     my $f_class = $self->result_source->schema->class($rel_obj->{class});
 388     $self->throw_exception( "Object $f_obj isn't a ".$f_class )
 389       unless Scalar::Util::blessed($f_obj) and $f_obj->isa($f_class);
 390   }
 391   $self->set_columns(
 392     $self->result_source->resolve_condition(
 393        $rel_obj->{cond}, $f_obj, $rel));
 394   return 1;
 395 }
 396
 397 =head2 update_from_related
 398
 399   $book->update_from_related('author', $author_obj);
 400
 401 The same as L</"set_from_related">, but the changes are immediately updated
 402 in storage.
 403
 404 =cut
 405
 406 sub update_from_related {
 407   my $self = shift;
 408   $self->set_from_related(@_);
 409   $self->update;
 410 }
 411
 412 =head2 delete_related
 413
 414   $obj->delete_related('relname', $cond, $attrs);
 415
 416 Delete any related item subject to the given conditions.
 417
 418 =cut
 419
 420 sub delete_related {
 421   my $self = shift;
 422   my $obj = $self->search_related(@_)->delete;
 423   delete $self->{related_resultsets}->{$_[0]};
 424   return $obj;
 425 }
 426
 427 =head2 add_to_$rel
 428
 429 B<Currently only available for C<has_many>, C<many-to-many> and 'multi' type
 430 relationships.>
 431
 432 =over 4
 433
 434 =item Arguments: ($foreign_vals | $obj), $link_vals?
 435
 436 =back
 437
 438   my $role = $schema->resultset('Role')->find(1);
 439   $actor->add_to_roles($role);
 440       # creates a My::DBIC::Schema::ActorRoles linking table row object
 441
 442   $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
 443       # creates a new My::DBIC::Schema::Role row object and the linking table
 444       # object with an extra column in the link
 445
 446 Adds a linking table object for C<$obj> or C<$foreign_vals>. If the first
 447 argument is a hash reference, the related object is created first with the
 448 column values in the hash. If an object reference is given, just the linking
 449 table object is created. In either case, any additional column values for the
 450 linking table object can be specified in C<$link_vals>.
 451
 452 =head2 set_$rel
 453
 454 B<Currently only available for C<many-to-many> relationships.>
 455
 456 =over 4
 457
 458 =item Arguments: (\@hashrefs | \@objs)
 459
 460 =back
 461
 462   my $actor = $schema->resultset('Actor')->find(1);
 463   my @roles = $schema->resultset('Role')->search({ role =>
 464      { '-in' => ['Fred', 'Barney'] } } );
 465
 466   $actor->set_roles(\@roles);
 467      # Replaces all of $actor's previous roles with the two named
 468
 469 Replace all the related objects with the given reference to a list of
 470 objects. This does a C<delete> B<on the link table resultset> to remove the
 471 association between the current object and all related objects, then calls
 472 C<add_to_$rel> repeatedly to link all the new objects.
 473
 474 Note that this means that this method will B<not> delete any objects in the
 475 table on the right side of the relation, merely that it will delete the link
 476 between them.
 477
 478 Due to a mistake in the original implementation of this method, it will also
 479 accept a list of objects or hash references. This is B<deprecated> and will be
 480 removed in a future version.
 481
 482 =head2 remove_from_$rel
 483
 484 B<Currently only available for C<many-to-many> relationships.>
 485
 486 =over 4
 487
 488 =item Arguments: $obj
 489
 490 =back
 491
 492   my $role = $schema->resultset('Role')->find(1);
 493   $actor->remove_from_roles($role);
 494       # removes $role's My::DBIC::Schema::ActorRoles linking table row object
 495
 496 Removes the link between the current object and the related object. Note that
 497 the related object itself won't be deleted unless you call ->delete() on
 498 it. This method just removes the link between the two objects.
 499
 500 =head1 AUTHORS
 501
 502 Matt S. Trout <mst@shadowcatsystems.co.uk>
 503
 504 =head1 LICENSE
 505
 506 You may distribute this code under the same terms as Perl itself.
 507
 508 =cut
 509
 510 1;