1 package DBIx::Class::Relationship::Base;
7 use base qw/DBIx::Class/;
11 DBIx::Class::Relationship::Base - Inter-table relationships
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>.
23 =head2 add_relationship
27 =item Arguments: 'relname', 'Foreign::Class', $cond, $attrs
31 __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);
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.
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>
45 { 'foreign.author_id' => 'self.id' }
47 will result in the C<JOIN> clause
49 author me JOIN book book ON book.author_id = me.id
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"):
57 'foreign.publisher_id' => 'self.publisher_id',
58 'foreign.type_id' => 'self.type_id',
61 This will result in the C<JOIN> clause:
63 book me JOIN edition edition ON edition.publisher_id = me.publisher_id
64 AND edition.type_id = me.type_id
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.
70 In addition to standard result set attributes, the following attributes are also valid:
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>.
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:
85 MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
87 proxy => [ qw/notes/ ],
90 Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:
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
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.
105 =item is_foreign_key_constraint
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.
112 =item on_delete / on_update
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.
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.
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.
140 =head2 register_relationship
144 =item Arguments: $relname, $rel_info
148 Registers a relationship on the class. This is called internally by
149 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
153 sub register_relationship { }
155 =head2 related_resultset
159 =item Arguments: $relationship_name
161 =item Return Value: $related_resultset
165 $rs = $cd->related_resultset('artist');
167 Returns a L<DBIx::Class::ResultSet> for the relationship named
172 sub related_resultset {
174 $self->throw_exception("Can't call *_related as class methods")
177 my $rel_obj = $self->relationship_info($rel);
178 $self->throw_exception( "No such relationship ${rel}" )
181 return $self->{related_resultsets}{$rel} ||= do {
182 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
183 $attrs = { %{$rel_obj->{attrs} || {}}, %$attrs };
185 $self->throw_exception( "Invalid query: @_" )
186 if (@_ > 1 && (@_ % 2 == 1));
187 my $query = ((@_ > 1) ? {@_} : shift);
189 my $source = $self->result_source;
190 my $cond = $source->resolve_condition(
191 $rel_obj->{cond}, $rel, $self
193 if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
194 my $reverse = $source->reverse_relationship_info($rel);
195 foreach my $rev_rel (keys %$reverse) {
196 if ($reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
197 $attrs->{related_objects}{$rev_rel} = [ $self ];
198 Scalar::Util::weaken($attrs->{related_object}{$rev_rel}[0]);
200 $attrs->{related_objects}{$rev_rel} = $self;
201 Scalar::Util::weaken($attrs->{related_object}{$rev_rel});
205 if (ref $cond eq 'ARRAY') {
207 if (ref $_ eq 'HASH') {
209 foreach my $key (keys %$_) {
210 my $newkey = $key =~ /\./ ? "me.$key" : $key;
211 $hash->{$newkey} = $_->{$key};
218 } elsif (ref $cond eq 'HASH') {
219 foreach my $key (grep { ! /\./ } keys %$cond) {
220 $cond->{"me.$key"} = delete $cond->{$key};
223 $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
224 $self->result_source->related_source($rel)->resultset->search(
230 =head2 search_related
232 @objects = $rs->search_related('relname', $cond, $attrs);
233 $objects_rs = $rs->search_related('relname', $cond, $attrs);
235 Run a search on a related resultset. The search will be restricted to the
236 item or items represented by the L<DBIx::Class::ResultSet> it was called
237 upon. This method can be called on a ResultSet, a Row or a ResultSource class.
242 return shift->related_resultset(shift)->search(@_);
245 =head2 search_related_rs
247 ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
249 This method works exactly the same as search_related, except that
250 it guarantees a restultset, even in list context.
254 sub search_related_rs {
255 return shift->related_resultset(shift)->search_rs(@_);
260 $obj->count_related('relname', $cond, $attrs);
262 Returns the count of all the items in the related resultset, restricted by the
263 current item or where conditions. Can be called on a
264 L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
265 L<DBIx::Class::Manual::Glossary/"Row"> object.
271 return $self->search_related(@_)->count;
276 my $new_obj = $obj->new_related('relname', \%col_data);
278 Create a new item of the related foreign class. If called on a
279 L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically
280 set any foreign key columns of the new object to the related primary
281 key columns of the source object for you. The newly created item will
282 not be saved into your storage until you call L<DBIx::Class::Row/insert>
288 my ($self, $rel, $values, $attrs) = @_;
289 return $self->search_related($rel)->new($values, $attrs);
292 =head2 create_related
294 my $new_obj = $obj->create_related('relname', \%col_data);
296 Creates a new item, similarly to new_related, and also inserts the item's data
297 into your storage medium. See the distinction between C<create> and C<new>
298 in L<DBIx::Class::ResultSet> for details.
305 my $obj = $self->search_related($rel)->create(@_);
306 delete $self->{related_resultsets}->{$rel};
312 my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
314 Attempt to find a related object using its primary key or unique constraints.
315 See L<DBIx::Class::ResultSet/find> for details.
322 return $self->search_related($rel)->find(@_);
325 =head2 find_or_new_related
327 my $new_obj = $obj->find_or_new_related('relname', \%col_data);
329 Find an item of a related class. If none exists, instantiate a new item of the
330 related class. The object will not be saved into your storage until you call
331 L<DBIx::Class::Row/insert> on it.
335 sub find_or_new_related {
337 my $obj = $self->find_related(@_);
338 return defined $obj ? $obj : $self->new_related(@_);
341 =head2 find_or_create_related
343 my $new_obj = $obj->find_or_create_related('relname', \%col_data);
345 Find or create an item of a related class. See
346 L<DBIx::Class::ResultSet/find_or_create> for details.
350 sub find_or_create_related {
352 my $obj = $self->find_related(@_);
353 return (defined($obj) ? $obj : $self->create_related(@_));
356 =head2 update_or_create_related
358 my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
360 Update or create an item of a related class. See
361 L<DBIx::Class::ResultSet/update_or_create> for details.
365 sub update_or_create_related {
368 return $self->related_resultset($rel)->update_or_create(@_);
371 =head2 set_from_related
373 $book->set_from_related('author', $author_obj);
374 $book->author($author_obj); ## same thing
376 Set column values on the current object, using related values from the given
377 related object. This is used to associate previously separate objects, for
378 example, to set the correct author for a book, find the Author object, then
379 call set_from_related on the book.
381 This is called internally when you pass existing objects as values to
382 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to acessor.
384 The columns are only set in the local copy of the object, call L</update> to
385 set them in the storage.
389 sub set_from_related {
390 my ($self, $rel, $f_obj) = @_;
391 my $rel_obj = $self->relationship_info($rel);
392 $self->throw_exception( "No such relationship ${rel}" ) unless $rel_obj;
393 my $cond = $rel_obj->{cond};
394 $self->throw_exception(
395 "set_from_related can only handle a hash condition; the ".
396 "condition for $rel is of type ".
397 (ref $cond ? ref $cond : 'plain scalar')
398 ) unless ref $cond eq 'HASH';
399 if (defined $f_obj) {
400 my $f_class = $self->result_source->schema->class($rel_obj->{class});
401 $self->throw_exception( "Object $f_obj isn't a ".$f_class )
402 unless Scalar::Util::blessed($f_obj) and $f_obj->isa($f_class);
405 $self->result_source->resolve_condition(
406 $rel_obj->{cond}, $f_obj, $rel));
410 =head2 update_from_related
412 $book->update_from_related('author', $author_obj);
414 The same as L</"set_from_related">, but the changes are immediately updated
419 sub update_from_related {
421 $self->set_from_related(@_);
425 =head2 delete_related
427 $obj->delete_related('relname', $cond, $attrs);
429 Delete any related item subject to the given conditions.
435 my $obj = $self->search_related(@_)->delete;
436 delete $self->{related_resultsets}->{$_[0]};
442 B<Currently only available for C<has_many>, C<many-to-many> and 'multi' type
447 =item Arguments: ($foreign_vals | $obj), $link_vals?
451 my $role = $schema->resultset('Role')->find(1);
452 $actor->add_to_roles($role);
453 # creates a My::DBIC::Schema::ActorRoles linking table row object
455 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
456 # creates a new My::DBIC::Schema::Role row object and the linking table
457 # object with an extra column in the link
459 Adds a linking table object for C<$obj> or C<$foreign_vals>. If the first
460 argument is a hash reference, the related object is created first with the
461 column values in the hash. If an object reference is given, just the linking
462 table object is created. In either case, any additional column values for the
463 linking table object can be specified in C<$link_vals>.
467 B<Currently only available for C<many-to-many> relationships.>
471 =item Arguments: (\@hashrefs | \@objs)
475 my $actor = $schema->resultset('Actor')->find(1);
476 my @roles = $schema->resultset('Role')->search({ role =>
477 { '-in' => ['Fred', 'Barney'] } } );
479 $actor->set_roles(\@roles);
480 # Replaces all of $actor's previous roles with the two named
482 Replace all the related objects with the given reference to a list of
483 objects. This does a C<delete> B<on the link table resultset> to remove the
484 association between the current object and all related objects, then calls
485 C<add_to_$rel> repeatedly to link all the new objects.
487 Note that this means that this method will B<not> delete any objects in the
488 table on the right side of the relation, merely that it will delete the link
491 Due to a mistake in the original implementation of this method, it will also
492 accept a list of objects or hash references. This is B<deprecated> and will be
493 removed in a future version.
495 =head2 remove_from_$rel
497 B<Currently only available for C<many-to-many> relationships.>
501 =item Arguments: $obj
505 my $role = $schema->resultset('Role')->find(1);
506 $actor->remove_from_roles($role);
507 # removes $role's My::DBIC::Schema::ActorRoles linking table row object
509 Removes the link between the current object and the related object. Note that
510 the related object itself won't be deleted unless you call ->delete() on
511 it. This method just removes the link between the two objects.
515 Matt S. Trout <mst@shadowcatsystems.co.uk>
519 You may distribute this code under the same terms as Perl itself.