DBIx/Class/Relationship/Base.pm

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