← Index
Performance Profile   « block view • line view • sub view »
For /wise/base/deliv/dev/bin/getfix
  Run on Thu May 20 15:30:03 2010
Reported on Thu May 20 16:25:44 2010

File/wise/base/static/lib/perl5/site_perl/5.10.0/DBIx/Class/Relationship.pm
Statements Executed11
Total Time0.000232 seconds

Subroutines — ordered by exclusive time
Calls P F Exclusive
Time		 Inclusive
Time		 Subroutine
00000DBIx::Class::Relationship::BEGIN

LineStmts.Exclusive
Time		Avg.Code
1package DBIx::Class::Relationship;
2
334.3e-51.4e-5use strict;
# spent 11µs making 1 call to strict::import
432.9e-59.7e-6use warnings;
# spent 21µs making 1 call to warnings::import
5
630.000124.1e-5use base qw/DBIx::Class/;
# spent 91µs making 1 call to base::import
7
813.4e-53.4e-5__PACKAGE__->load_own_components(qw/
# spent 15.1ms making 1 call to Class::C3::Componentised::load_own_components
9 Helpers
10 Accessor
11 CascadeActions
12 ProxyMethods
13 Base
14/);
15
16=head1 NAME
17
18DBIx::Class::Relationship - Inter-table relationships
19
20=head1 SYNOPSIS
21
22 MyDB::Schema::Actor->has_many('actorroles' => 'MyDB::Schema::ActorRole',
23 'actor');
24 MyDB::Schema::Role->has_many('actorroles' => 'MyDB::Schema::ActorRole',
25 'role');
26 MyDB::Schema::ActorRole->belongs_to('role' => 'MyDB::Schema::Role');
27 MyDB::Schema::ActorRole->belongs_to('actor' => 'MyDB::Schema::Actor');
28
29 MyDB::Schema::Role->many_to_many('actors' => 'actorroles', 'actor');
30 MyDB::Schema::Actor->many_to_many('roles' => 'actorroles', 'role');
31
32 $schema->resultset('Actor')->roles();
33 $schema->resultset('Role')->search_related('actors', { Name => 'Fred' });
34 $schema->resultset('ActorRole')->add_to_roles({ Name => 'Sherlock Holmes'});
35
36See L<DBIx::Class::Manual::Cookbook> for more.
37
38=head1 DESCRIPTION
39
40This class provides methods to set up relationships between the tables
41in your database model. Relationships are the most useful and powerful
42technique that L<DBIx::Class> provides. To create efficient database queries,
43create relationships between any and all tables that have something in
44common, for example if you have a table Authors:
45
46 ID | Name | Age
47 ------------------
48 1 | Fred | 30
49 2 | Joe | 32
50
51and a table Books:
52
53 ID | Author | Name
54 --------------------
55 1 | 1 | Rulers of the universe
56 2 | 1 | Rulers of the galaxy
57
58Then without relationships, the method of getting all books by Fred goes like
59this:
60
61 my $fred = $schema->resultset('Author')->find({ Name => 'Fred' });
62 my $fredsbooks = $schema->resultset('Book')->search({ Author => $fred->ID });
63With a has_many relationship called "books" on Author (see below for details),
64we can do this instead:
65
66 my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books;
67
68Each relationship sets up an accessor method on the
69L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items
70of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects,
71the relationships can be searched using the "search_related" method.
72In list context, each returns a list of Row objects for the related class,
73in scalar context, a new ResultSet representing the joined tables is
74returned. Thus, the calls can be chained to produce complex queries.
75Since the database is not actually queried until you attempt to retrieve
76the data for an actual item, no time is wasted producing them.
77
78 my $cheapfredbooks = $schema->resultset('Author')->find({
79 Name => 'Fred',
80 })->books->search_related('prices', {
81 Price => { '<=' => '5.00' },
82 });
83
84will produce a query something like:
85
86 SELECT * FROM Author me
87 LEFT JOIN Books books ON books.author = me.id
88 LEFT JOIN Prices prices ON prices.book = books.id
89 WHERE prices.Price <= 5.00
90
91all without needing multiple fetches.
92
93Only the helper methods for setting up standard relationship types
94are documented here. For the basic, lower-level methods, and a description
95of all the useful *_related methods that you get for free, see
96L<DBIx::Class::Relationship::Base>.
97
98=head1 METHODS
99
100All helper methods take the following arguments:
101
102 __PACKAGE__>$method_name('relname', 'Foreign::Class', $cond, $attrs);
103
104Both C<$cond> and C<$attrs> are optional. Pass C<undef> for C<$cond> if
105you want to use the default value for it, but still want to set C<$attrs>.
106
107See L<DBIx::Class::Relationship::Base> for a list of valid attributes and valid
108relationship attributes.
109
110=head2 belongs_to
111
112=over 4
113
114=item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr?
115
116=back
117
118Creates a relationship where the calling class stores the foreign class's
119primary key in one (or more) of its columns. This relationship defaults to
120using C<$accessor_name> as the foreign key in C<$related_class> to resolve the
121join, unless C<$foreign_key_column> specifies the foreign key column in
122C<$related_class> or C<$cond> specifies a reference to a join condition hash.
123
124=over
125
126=item accessor_name
127
128This argument is the name of the method you can call on a
129L<DBIx::Class::Row> object to retrieve the instance of the foreign
130class matching this relationship.
131
132Use this accessor_name (relation name) in L<DBIx::Class::ResultSet/join>
133or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
134indicated by this relationship.
135
136=item related_class
137
138This is the class name of the table referenced by the foreign key in
139this class.
140
141=item foreign_key_column
142
143The column name on this class that contains the foreign key.
144
145OR
146
147=item cond
148
149A hashref where the keys are C<foreign.$column_on_related_table> and
150the values are C<self.$foreign_key_column>. This is useful for
151relations that are across multiple columns.
152
153=back
154
155
156 # in a Book class (where Author has many Books)
157 My::DBIC::Schema::Book->belongs_to( author => 'My::DBIC::Schema::Author' );
158
159 my $author_obj = $obj->author; # get author object
160 $obj->author( $new_author_obj ); # set author object
161
162The above belongs_to relationship could also have been specified as,
163
164 My::DBIC::Schema::Book->belongs_to( author,
165 'My::DBIC::Schema::Author',
166 { 'foreign.author' => 'self.author' } );
167
168If the relationship is optional -- i.e. the column containing the foreign key
169can be NULL -- then the belongs_to relationship does the right thing. Thus, in
170the example above C<$obj-E<gt>author> would return C<undef>. However in this
171case you would probably want to set the C<join_type> attribute so that a C<LEFT
172JOIN> is done, which makes complex resultsets involving C<join> or C<prefetch>
173operations work correctly. The modified declaration is shown below:
174
175 # in a Book class (where Author has_many Books)
176 __PACKAGE__->belongs_to(author => 'My::DBIC::Schema::Author',
177 'author', {join_type => 'left'});
178
179
180Cascading deletes are off by default on a C<belongs_to>
181relationship. To turn them on, pass C<< cascade_delete => 1 >>
182in the $attr hashref.
183
184NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
185of C<has_a>.
186
187See L<DBIx::Class::Relationship::Base> for documentation on relationship
188methods and valid relationship attributes.
189
190=head2 has_many
191
192=over 4
193
194=item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr?
195
196=back
197
198Creates a one-to-many relationship, where the corresponding elements of the
199foreign class store the calling class's primary key in one (or more) of its
200columns. This relationship defaults to using C<$accessor_name> as the foreign
201key in C<$related_class> to resolve the join, unless C<$foreign_key_column>
202specifies the foreign key column in C<$related_class> or C<$cond> specifies a
203reference to a join condition hash.
204
205=over
206
207=item accessor_name
208
209This argument is the name of the method you can call on a
210L<DBIx::Class::Row> object to retrieve a resultset of the related
211class restricted to the ones related to the row object. In list
212context it returns the row objects.
213
214Use this accessor_name (relation name) in L<DBIx::Class::ResultSet/join>
215or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
216indicated by this relationship.
217
218=item related_class
219
220This is the class name of the table which contains a foreign key
221column containing PK values of this class.
222
223=item foreign_key_column
224
225The column name on the related class that contains the foreign key.
226
227OR
228
229=item cond
230
231A hashref where the keys are C<foreign.$column_on_related_table> and
232the values are C<self.$foreign_key_column>. This is useful for
233relations that are across multiple columns.
234
235=back
236
237 # in an Author class (where Author has_many Books)
238 My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author');
239
240 my $booklist = $obj->books;
241 my $booklist = $obj->books({
242 name => { LIKE => '%macaroni%' },
243 { prefetch => [qw/book/],
244 });
245 my @book_objs = $obj->books;
246 my $books_rs = $obj->books;
247 ( $books_rs ) = $obj->books_rs;
248
249 $obj->add_to_books(\%col_data);
250
251The above C<has_many> relationship could also have been specified with an
252explicit join condition:
253
254 My::DBIC::Schema::Author->has_many( books => 'My::DBIC::Schema::Book', {
255 'foreign.author' => 'self.author',
256 });
257
258Three methods are created when you create a has_many relationship. The first
259method is the expected accessor method, C<$accessor_name()>. The second is
260almost exactly the same as the accessor method but "_rs" is added to the end of
261the method name. This method works just like the normal accessor, except that
262it returns a resultset no matter what, even in list context. The third method,
263named C<< add_to_$relname >>, will also be added to your Row items; this
264allows you to insert new related items, using the same mechanism as in
265L<DBIx::Class::Relationship::Base/"create_related">.
266
267If you delete an object in a class with a C<has_many> relationship, all
268the related objects will be deleted as well. To turn this behaviour off,
269pass C<< cascade_delete => 0 >> in the C<$attr> hashref. However, any
270database-level cascade or restrict will take precedence over a
271DBIx-Class-based cascading delete.
272
273See L<DBIx::Class::Relationship::Base> for documentation on relationship
274methods and valid relationship attributes.
275
276=head2 might_have
277
278=over 4
279
280=item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr?
281
282=back
283
284Creates an optional one-to-one relationship with a class. This relationship
285defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
286resolve the join, unless C<$foreign_key_column> specifies the foreign key
287column in C<$related_class> or C<$cond> specifies a reference to a join
288condition hash.
289
290=over
291
292=item accessor_name
293
294This argument is the name of the method you can call on a
295L<DBIx::Class::Row> object to retrieve the instance of the foreign
296class matching this relationship.
297
298Use this accessor_name (relation name) in L<DBIx::Class::ResultSet/join>
299or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
300indicated by this relationship.
301
302=item related_class
303
304This is the class name of the table which contains a foreign key
305column containing PK values of this class.
306
307=item foreign_key_column
308
309The column name on the related class that contains the foreign key.
310
311OR
312
313=item cond
314
315A hashref where the keys are C<foreign.$column_on_related_table> and
316the values are C<self.$foreign_key_column>. This is useful for
317relations that are across multiple columns.
318
319=back
320
321 My::DBIC::Schema::Author->might_have( pseudonym =>
322 'My::DBIC::Schema::Pseudonym' );
323
324 my $pname = $obj->pseudonym; # to get the Pseudonym object
325
326The above might_have relationship could have been specified as:
327
328 My::DBIC::Schema::Author->might_have( pseudonym =>
329 'My::DBIC::Schema::Pseudonym',
330 'author' );
331
332Or even:
333
334 My::DBIC::Schema::Author->might_have( pseudonym =>
335 'My::DBIC::Schema::Pseudonym',
336 { 'foreign.author' => 'self.author' } );
337
338If you update or delete an object in a class with a C<might_have>
339relationship, the related object will be updated or deleted as well. To
340turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr>
341hashref. Any database-level update or delete constraints will override
342this behavior.
343
344See L<DBIx::Class::Relationship::Base> for documentation on relationship
345methods and valid relationship attributes.
346
347=head2 has_one
348
349=over 4
350
351=item Arguments: $accessor_name, $related_class_name, $join_condition?, $attr?
352
353=back
354
355 My::DBIC::Schema::Book->has_one(isbn => 'My::DBIC::Schema::ISBN');
356
357 my $isbn_obj = $obj->isbn; # to get the ISBN object
358
359Creates a one-to-one relationship with another class. This is just like
360C<might_have>, except the implication is that the other object is always
361present. The only difference between C<has_one> and C<might_have> is that
362C<has_one> uses an (ordinary) inner join, whereas C<might_have> uses a
363left join.
364
365The has_one relationship should be used when a row in the table has exactly one
366related row in another table. If the related row might not exist in the foreign
367table, use the L<DBIx::Class::Relationship/might_have> relationship.
368
369In the above example, each Book in the database is associated with exactly one
370ISBN object.
371
372See L<DBIx::Class::Relationship::Base> for documentation on relationship
373methods and valid relationship attributes.
374
375=head2 many_to_many
376
377=over 4
378
379=item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, $attr?
380
381=back
382
383C<many_to_many> is not strictly a relationship in its own right. Instead, it is
384a bridge between two resultsets which provide the same kind of convenience
385accessors as true relationships provide. Although the accessor will return a
386resultset or collection of objects just like has_many does, you cannot call
387C<related_resultset> and similar methods which operate on true relationships.
388
389=over
390
391=item accessor_name
392
393This argument is the name of the method you can call on a
394L<DBIx::Class::Row> object to retrieve the rows matching this
395relationship.
396
397On a many_to_many, unlike other relationships, this cannot be used in
398L<DBIx::Class::ResultSet/search> to join tables. Use the relations
399bridged across instead.
400
401=item link_rel_name
402
403This is the accessor_name from the has_many relationship we are
404bridging from.
405
406=item foreign_rel_name
407
408This is the accessor_name of the belongs_to relationship in the link
409table that we are bridging across (which gives us the table we are
410bridging to).
411
412=back
413
414To create a many_to_many relationship from Actor to Role:
415
416 My::DBIC::Schema::Actor->has_many( actor_roles =>
417 'My::DBIC::Schema::ActorRoles',
418 'actor' );
419 My::DBIC::Schema::ActorRoles->belongs_to( role =>
420 'My::DBIC::Schema::Role' );
421 My::DBIC::Schema::ActorRoles->belongs_to( actor =>
422 'My::DBIC::Schema::Actor' );
423
424 My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
425 'role' );
426
427And, for the reverse relationship, from Role to Actor:
428
429 My::DBIC::Schema::Role->has_many( actor_roles =>
430 'My::DBIC::Schema::ActorRoles',
431 'role' );
432
433 My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' );
434
435To add a role for your actor, and fill in the year of the role in the
436actor_roles table:
437
438 $actor->add_to_roles($role, { year => 1995 });
439
440In the above example, ActorRoles is the link table class, and Role is the
441foreign class. The C<$link_rel_name> parameter is the name of the accessor for
442the has_many relationship from this table to the link table, and the
443C<$foreign_rel_name> parameter is the accessor for the belongs_to relationship
444from the link table to the foreign table.
445
446To use many_to_many, existing relationships from the original table to the link
447table, and from the link table to the end table must already exist, these
448relation names are then used in the many_to_many call.
449
450In the above example, the Actor class will have 3 many_to_many accessor methods
451set: C<$roles>, C<$add_to_roles>, C<$set_roles>, and similarly named accessors
452will be created for the Role class for the C<actors> many_to_many
453relationship.
454
455See L<DBIx::Class::Relationship::Base> for documentation on relationship
456methods and valid relationship attributes.
457
458=cut
459
46014.0e-64.0e-61;
461
462=head1 AUTHORS
463
464Matt S. Trout <mst@shadowcatsystems.co.uk>
465
466=head1 LICENSE
467
468You may distribute this code under the same terms as Perl itself.
469
470=cut
471

Report produced by the NYTProf 2.07 Perl profiler, developed by Tim Bunce and Adam Kaplan.