Filename | /2home/ss5/perl5/perlbrew/perls/perl-5.12.3/lib/site_perl/5.12.3/DBIx/Class/Relationship.pm |
Statements | Executed 11 statements in 301µs |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
1 | 1 | 1 | 14µs | 16µs | BEGIN@3 | DBIx::Class::Relationship::
1 | 1 | 1 | 9µs | 26µs | BEGIN@4 | DBIx::Class::Relationship::
1 | 1 | 1 | 7µs | 103µs | BEGIN@6 | DBIx::Class::Relationship::
Line | State ments |
Time on line |
Calls | Time in subs |
Code |
---|---|---|---|---|---|
1 | package DBIx::Class::Relationship; | ||||
2 | |||||
3 | 3 | 18µs | 2 | 18µs | # spent 16µs (14+2) within DBIx::Class::Relationship::BEGIN@3 which was called:
# once (14µs+2µs) by Class::C3::Componentised::ensure_class_loaded at line 3 # spent 16µs making 1 call to DBIx::Class::Relationship::BEGIN@3
# spent 2µs making 1 call to strict::import |
4 | 3 | 29µs | 2 | 43µs | # spent 26µs (9+17) within DBIx::Class::Relationship::BEGIN@4 which was called:
# once (9µs+17µs) by Class::C3::Componentised::ensure_class_loaded at line 4 # spent 26µs making 1 call to DBIx::Class::Relationship::BEGIN@4
# spent 17µs making 1 call to warnings::import |
5 | |||||
6 | 3 | 240µs | 2 | 199µs | # spent 103µs (7+96) within DBIx::Class::Relationship::BEGIN@6 which was called:
# once (7µs+96µs) by Class::C3::Componentised::ensure_class_loaded at line 6 # spent 103µs making 1 call to DBIx::Class::Relationship::BEGIN@6
# spent 96µs making 1 call to base::import |
7 | |||||
8 | 1 | 10µs | 1 | 10.1ms | __PACKAGE__->load_own_components(qw/ # spent 10.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 | |||||
18 | DBIx::Class::Relationship - Inter-table relationships | ||||
19 | |||||
20 | =head1 SYNOPSIS | ||||
21 | |||||
22 | ## Creating relationships | ||||
23 | MyApp::Schema::Actor->has_many('actorroles' => 'MyApp::Schema::ActorRole', | ||||
24 | 'actor'); | ||||
25 | MyApp::Schema::Role->has_many('actorroles' => 'MyApp::Schema::ActorRole', | ||||
26 | 'role'); | ||||
27 | MyApp::Schema::ActorRole->belongs_to('role' => 'MyApp::Schema::Role'); | ||||
28 | MyApp::Schema::ActorRole->belongs_to('actor' => 'MyApp::Schema::Actor'); | ||||
29 | |||||
30 | MyApp::Schema::Role->many_to_many('actors' => 'actorroles', 'actor'); | ||||
31 | MyApp::Schema::Actor->many_to_many('roles' => 'actorroles', 'role'); | ||||
32 | |||||
33 | ## Using relationships | ||||
34 | $schema->resultset('Actor')->find({ id => 1})->roles(); | ||||
35 | $schema->resultset('Role')->find({ id => 1 })->actorroles->search_related('actor', { Name => 'Fred' }); | ||||
36 | $schema->resultset('Actor')->add_to_roles({ Name => 'Sherlock Holmes'}); | ||||
37 | |||||
38 | See L<DBIx::Class::Manual::Cookbook> for more. | ||||
39 | |||||
40 | =head1 DESCRIPTION | ||||
41 | |||||
42 | The word I<Relationship> has a specific meaning in DBIx::Class, see | ||||
43 | the definition in the L<Glossary|DBIx::Class::Manual::Glossary/Relationship>. | ||||
44 | |||||
45 | This class provides methods to set up relationships between the tables | ||||
46 | in your database model. Relationships are the most useful and powerful | ||||
47 | technique that L<DBIx::Class> provides. To create efficient database queries, | ||||
48 | create relationships between any and all tables that have something in | ||||
49 | common, for example if you have a table Authors: | ||||
50 | |||||
51 | ID | Name | Age | ||||
52 | ------------------ | ||||
53 | 1 | Fred | 30 | ||||
54 | 2 | Joe | 32 | ||||
55 | |||||
56 | and a table Books: | ||||
57 | |||||
58 | ID | Author | Name | ||||
59 | -------------------- | ||||
60 | 1 | 1 | Rulers of the universe | ||||
61 | 2 | 1 | Rulers of the galaxy | ||||
62 | |||||
63 | Then without relationships, the method of getting all books by Fred goes like | ||||
64 | this: | ||||
65 | |||||
66 | my $fred = $schema->resultset('Author')->find({ Name => 'Fred' }); | ||||
67 | my $fredsbooks = $schema->resultset('Book')->search({ Author => $fred->ID }); | ||||
68 | |||||
69 | With a has_many relationship called "books" on Author (see below for details), | ||||
70 | we can do this instead: | ||||
71 | |||||
72 | my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books; | ||||
73 | |||||
74 | Each relationship sets up an accessor method on the | ||||
75 | L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items | ||||
76 | of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects, | ||||
77 | the relationships can be searched using the "search_related" method. | ||||
78 | In list context, each returns a list of Row objects for the related class, | ||||
79 | in scalar context, a new ResultSet representing the joined tables is | ||||
80 | returned. Thus, the calls can be chained to produce complex queries. | ||||
81 | Since the database is not actually queried until you attempt to retrieve | ||||
82 | the data for an actual item, no time is wasted producing them. | ||||
83 | |||||
84 | my $cheapfredbooks = $schema->resultset('Author')->find({ | ||||
85 | Name => 'Fred', | ||||
86 | })->books->search_related('prices', { | ||||
87 | Price => { '<=' => '5.00' }, | ||||
88 | }); | ||||
89 | |||||
90 | will produce a query something like: | ||||
91 | |||||
92 | SELECT * FROM Author me | ||||
93 | LEFT JOIN Books books ON books.author = me.id | ||||
94 | LEFT JOIN Prices prices ON prices.book = books.id | ||||
95 | WHERE prices.Price <= 5.00 | ||||
96 | |||||
97 | all without needing multiple fetches. | ||||
98 | |||||
99 | Only the helper methods for setting up standard relationship types | ||||
100 | are documented here. For the basic, lower-level methods, and a description | ||||
101 | of all the useful *_related methods that you get for free, see | ||||
102 | L<DBIx::Class::Relationship::Base>. | ||||
103 | |||||
104 | =head1 METHODS | ||||
105 | |||||
106 | All helper methods are called similar to the following template: | ||||
107 | |||||
108 | __PACKAGE__->$method_name('relname', 'Foreign::Class', \%cond|\@cond|\&cond?, \%attrs?); | ||||
109 | |||||
110 | Both C<cond> and C<attrs> are optional. Pass C<undef> for C<cond> if | ||||
111 | you want to use the default value for it, but still want to set C<attrs>. | ||||
112 | |||||
113 | See L<DBIx::Class::Relationship::Base/condition> for full documentation on | ||||
114 | definition of the C<cond> argument. | ||||
115 | |||||
116 | See L<DBIx::Class::Relationship::Base/attributes> for documentation on the | ||||
117 | attributes that are allowed in the C<attrs> argument. | ||||
118 | |||||
119 | |||||
120 | =head2 belongs_to | ||||
121 | |||||
122 | =over 4 | ||||
123 | |||||
124 | =item Arguments: $accessor_name, $related_class, $our_fk_column|\%cond|\@cond|\$cond?, \%attrs? | ||||
125 | |||||
126 | =back | ||||
127 | |||||
128 | Creates a relationship where the calling class stores the foreign | ||||
129 | class's primary key in one (or more) of the calling class columns. | ||||
130 | This relationship defaults to using C<$accessor_name> as the column | ||||
131 | name in this class to resolve the join against the primary key from | ||||
132 | C<$related_class>, unless C<$our_fk_column> specifies the foreign key column | ||||
133 | in this class or C<cond> specifies a reference to a join condition. | ||||
134 | |||||
135 | =over | ||||
136 | |||||
137 | =item accessor_name | ||||
138 | |||||
139 | This argument is the name of the method you can call on a | ||||
140 | L<DBIx::Class::Row> object to retrieve the instance of the foreign | ||||
141 | class matching this relationship. This is often called the | ||||
142 | C<relation(ship) name>. | ||||
143 | |||||
144 | Use this accessor_name in L<DBIx::Class::ResultSet/join> | ||||
145 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table | ||||
146 | indicated by this relationship. | ||||
147 | |||||
148 | =item related_class | ||||
149 | |||||
150 | This is the class name of the table referenced by the foreign key in | ||||
151 | this class. | ||||
152 | |||||
153 | =item our_fk_column | ||||
154 | |||||
155 | The column name on this class that contains the foreign key. | ||||
156 | |||||
157 | OR | ||||
158 | |||||
159 | =item cond | ||||
160 | |||||
161 | A hashref, arrayref or coderef specifying a custom join expression. For | ||||
162 | more info see L<DBIx::Class::Relationship::Base/condition>. | ||||
163 | |||||
164 | =back | ||||
165 | |||||
166 | # in a Book class (where Author has many Books) | ||||
167 | My::DBIC::Schema::Book->belongs_to( | ||||
168 | author => | ||||
169 | 'My::DBIC::Schema::Author', | ||||
170 | 'author_id' | ||||
171 | ); | ||||
172 | |||||
173 | # OR (same result) | ||||
174 | My::DBIC::Schema::Book->belongs_to( | ||||
175 | author => | ||||
176 | 'My::DBIC::Schema::Author', | ||||
177 | { 'foreign.author_id' => 'self.author_id' } | ||||
178 | ); | ||||
179 | |||||
180 | # OR (similar result but uglier accessor name) | ||||
181 | My::DBIC::Schema::Book->belongs_to( | ||||
182 | author_id => | ||||
183 | 'My::DBIC::Schema::Author' | ||||
184 | ); | ||||
185 | |||||
186 | # Usage | ||||
187 | my $author_obj = $book->author; # get author object | ||||
188 | $book->author( $new_author_obj ); # set author object | ||||
189 | $book->author_id(); # get the plain id | ||||
190 | |||||
191 | # To retrieve the plain id if you used the ugly version: | ||||
192 | $book->get_column('author_id'); | ||||
193 | |||||
194 | |||||
195 | If the relationship is optional -- i.e. the column containing the | ||||
196 | foreign key can be NULL -- then the belongs_to relationship does the | ||||
197 | right thing. Thus, in the example above C<< $obj->author >> would | ||||
198 | return C<undef>. However in this case you would probably want to set | ||||
199 | the L<join_type|DBIx::Class::Relationship/join_type> attribute so that | ||||
200 | a C<LEFT JOIN> is done, which makes complex resultsets involving | ||||
201 | C<join> or C<prefetch> operations work correctly. The modified | ||||
202 | declaration is shown below: | ||||
203 | |||||
204 | # in a Book class (where Author has_many Books) | ||||
205 | __PACKAGE__->belongs_to( | ||||
206 | author => | ||||
207 | 'My::DBIC::Schema::Author', | ||||
208 | 'author', | ||||
209 | { join_type => 'left' } | ||||
210 | ); | ||||
211 | |||||
212 | |||||
213 | Cascading deletes are off by default on a C<belongs_to> | ||||
214 | relationship. To turn them on, pass C<< cascade_delete => 1 >> | ||||
215 | in the $attr hashref. | ||||
216 | |||||
217 | By default, DBIC will return undef and avoid querying the database if a | ||||
218 | C<belongs_to> accessor is called when any part of the foreign key IS NULL. To | ||||
219 | disable this behavior, pass C<< undef_on_null_fk => 0 >> in the C<\%attrs> | ||||
220 | hashref. | ||||
221 | |||||
222 | NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent | ||||
223 | of C<has_a>. | ||||
224 | |||||
225 | See L<DBIx::Class::Relationship::Base/attributes> for documentation on relationship | ||||
226 | methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet> | ||||
227 | for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES> | ||||
228 | which can be assigned to relationships as well. | ||||
229 | |||||
230 | =head2 has_many | ||||
231 | |||||
232 | =over 4 | ||||
233 | |||||
234 | =item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs? | ||||
235 | |||||
236 | =back | ||||
237 | |||||
238 | Creates a one-to-many relationship where the foreign class refers to | ||||
239 | this class's primary key. This relationship refers to zero or more | ||||
240 | records in the foreign table (e.g. a C<LEFT JOIN>). This relationship | ||||
241 | defaults to using the end of this classes namespace as the foreign key | ||||
242 | in C<$related_class> to resolve the join, unless C<$their_fk_column> | ||||
243 | specifies the foreign key column in C<$related_class> or C<cond> | ||||
244 | specifies a reference to a join condition. | ||||
245 | |||||
246 | =over | ||||
247 | |||||
248 | =item accessor_name | ||||
249 | |||||
250 | This argument is the name of the method you can call on a | ||||
251 | L<DBIx::Class::Row> object to retrieve a resultset of the related | ||||
252 | class restricted to the ones related to the row object. In list | ||||
253 | context it returns the row objects. This is often called the | ||||
254 | C<relation(ship) name>. | ||||
255 | |||||
256 | Use this accessor_name in L<DBIx::Class::ResultSet/join> | ||||
257 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table | ||||
258 | indicated by this relationship. | ||||
259 | |||||
260 | =item related_class | ||||
261 | |||||
262 | This is the class name of the table which contains a foreign key | ||||
263 | column containing PK values of this class. | ||||
264 | |||||
265 | =item their_fk_column | ||||
266 | |||||
267 | The column name on the related class that contains the foreign key. | ||||
268 | |||||
269 | OR | ||||
270 | |||||
271 | =item cond | ||||
272 | |||||
273 | A hashref, arrayref or coderef specifying a custom join expression. For | ||||
274 | more info see L<DBIx::Class::Relationship::Base/condition>. | ||||
275 | |||||
276 | =back | ||||
277 | |||||
278 | # in an Author class (where Author has_many Books) | ||||
279 | # assuming related class is storing our PK in "author_id" | ||||
280 | My::DBIC::Schema::Author->has_many( | ||||
281 | books => | ||||
282 | 'My::DBIC::Schema::Book', | ||||
283 | 'author_id' | ||||
284 | ); | ||||
285 | |||||
286 | # OR (same result) | ||||
287 | My::DBIC::Schema::Author->has_many( | ||||
288 | books => | ||||
289 | 'My::DBIC::Schema::Book', | ||||
290 | { 'foreign.author_id' => 'self.id' }, | ||||
291 | ); | ||||
292 | |||||
293 | # OR (similar result, assuming related_class is storing our PK, in "author") | ||||
294 | # (the "author" is guessed at from "Author" in the class namespace) | ||||
295 | My::DBIC::Schema::Author->has_many( | ||||
296 | books => | ||||
297 | 'My::DBIC::Schema::Book', | ||||
298 | ); | ||||
299 | |||||
300 | |||||
301 | # Usage | ||||
302 | # resultset of Books belonging to author | ||||
303 | my $booklist = $author->books; | ||||
304 | |||||
305 | # resultset of Books belonging to author, restricted by author name | ||||
306 | my $booklist = $author->books({ | ||||
307 | name => { LIKE => '%macaroni%' }, | ||||
308 | { prefetch => [qw/book/], | ||||
309 | }); | ||||
310 | |||||
311 | # array of Book objects belonging to author | ||||
312 | my @book_objs = $author->books; | ||||
313 | |||||
314 | # force resultset even in list context | ||||
315 | my $books_rs = $author->books; | ||||
316 | ( $books_rs ) = $obj->books_rs; | ||||
317 | |||||
318 | # create a new book for this author, the relation fields are auto-filled | ||||
319 | $author->create_related('books', \%col_data); | ||||
320 | # alternative method for the above | ||||
321 | $author->add_to_books(\%col_data); | ||||
322 | |||||
323 | |||||
324 | Three methods are created when you create a has_many relationship. | ||||
325 | The first method is the expected accessor method, C<$accessor_name()>. | ||||
326 | The second is almost exactly the same as the accessor method but "_rs" | ||||
327 | is added to the end of the method name, eg C<$accessor_name_rs()>. | ||||
328 | This method works just like the normal accessor, except that it always | ||||
329 | returns a resultset, even in list context. The third method, named C<< | ||||
330 | add_to_$relname >>, will also be added to your Row items; this allows | ||||
331 | you to insert new related items, using the same mechanism as in | ||||
332 | L<DBIx::Class::Relationship::Base/"create_related">. | ||||
333 | |||||
334 | If you delete an object in a class with a C<has_many> relationship, all | ||||
335 | the related objects will be deleted as well. To turn this behaviour off, | ||||
336 | pass C<< cascade_delete => 0 >> in the C<$attr> hashref. | ||||
337 | |||||
338 | The cascaded operations are performed after the requested delete or | ||||
339 | update, so if your database has a constraint on the relationship, it | ||||
340 | will have deleted/updated the related records or raised an exception | ||||
341 | before DBIx::Class gets to perform the cascaded operation. | ||||
342 | |||||
343 | If you copy an object in a class with a C<has_many> relationship, all | ||||
344 | the related objects will be copied as well. To turn this behaviour off, | ||||
345 | pass C<< cascade_copy => 0 >> in the C<$attr> hashref. The behaviour | ||||
346 | defaults to C<< cascade_copy => 1 >>. | ||||
347 | |||||
348 | See L<DBIx::Class::Relationship::Base/attributes> for documentation on | ||||
349 | relationship methods and valid relationship attributes. Also see | ||||
350 | L<DBIx::Class::ResultSet> for a L<list of standard resultset | ||||
351 | attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to | ||||
352 | relationships as well. | ||||
353 | |||||
354 | =head2 might_have | ||||
355 | |||||
356 | =over 4 | ||||
357 | |||||
358 | =item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs? | ||||
359 | |||||
360 | =back | ||||
361 | |||||
362 | Creates an optional one-to-one relationship with a class. This relationship | ||||
363 | defaults to using C<$accessor_name> as the foreign key in C<$related_class> to | ||||
364 | resolve the join, unless C<$their_fk_column> specifies the foreign key | ||||
365 | column in C<$related_class> or C<cond> specifies a reference to a join | ||||
366 | condition. | ||||
367 | |||||
368 | =over | ||||
369 | |||||
370 | =item accessor_name | ||||
371 | |||||
372 | This argument is the name of the method you can call on a | ||||
373 | L<DBIx::Class::Row> object to retrieve the instance of the foreign | ||||
374 | class matching this relationship. This is often called the | ||||
375 | C<relation(ship) name>. | ||||
376 | |||||
377 | Use this accessor_name in L<DBIx::Class::ResultSet/join> | ||||
378 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table | ||||
379 | indicated by this relationship. | ||||
380 | |||||
381 | =item related_class | ||||
382 | |||||
383 | This is the class name of the table which contains a foreign key | ||||
384 | column containing PK values of this class. | ||||
385 | |||||
386 | =item their_fk_column | ||||
387 | |||||
388 | The column name on the related class that contains the foreign key. | ||||
389 | |||||
390 | OR | ||||
391 | |||||
392 | =item cond | ||||
393 | |||||
394 | A hashref, arrayref or coderef specifying a custom join expression. For | ||||
395 | more info see L<DBIx::Class::Relationship::Base/condition>. | ||||
396 | |||||
397 | =back | ||||
398 | |||||
399 | # Author may have an entry in the pseudonym table | ||||
400 | My::DBIC::Schema::Author->might_have( | ||||
401 | pseudonym => | ||||
402 | 'My::DBIC::Schema::Pseudonym', | ||||
403 | 'author_id', | ||||
404 | ); | ||||
405 | |||||
406 | # OR (same result, assuming the related_class stores our PK) | ||||
407 | My::DBIC::Schema::Author->might_have( | ||||
408 | pseudonym => | ||||
409 | 'My::DBIC::Schema::Pseudonym', | ||||
410 | ); | ||||
411 | |||||
412 | # OR (same result) | ||||
413 | My::DBIC::Schema::Author->might_have( | ||||
414 | pseudonym => | ||||
415 | 'My::DBIC::Schema::Pseudonym', | ||||
416 | { 'foreign.author_id' => 'self.id' }, | ||||
417 | ); | ||||
418 | |||||
419 | # Usage | ||||
420 | my $pname = $author->pseudonym; # to get the Pseudonym object | ||||
421 | |||||
422 | If you update or delete an object in a class with a C<might_have> | ||||
423 | relationship, the related object will be updated or deleted as well. To | ||||
424 | turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr> | ||||
425 | hashref. | ||||
426 | |||||
427 | The cascaded operations are performed after the requested delete or | ||||
428 | update, so if your database has a constraint on the relationship, it | ||||
429 | will have deleted/updated the related records or raised an exception | ||||
430 | before DBIx::Class gets to perform the cascaded operation. | ||||
431 | |||||
432 | See L<DBIx::Class::Relationship::Base/attributes> for documentation on | ||||
433 | relationship methods and valid relationship attributes. Also see | ||||
434 | L<DBIx::Class::ResultSet> for a L<list of standard resultset | ||||
435 | attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to | ||||
436 | relationships as well. | ||||
437 | |||||
438 | Note that if you supply a condition on which to join, and the column in the | ||||
439 | current table allows nulls (i.e., has the C<is_nullable> attribute set to a | ||||
440 | true value), than C<might_have> will warn about this because it's naughty and | ||||
441 | you shouldn't do that. The warning will look something like: | ||||
442 | |||||
443 | "might_have/has_one" must not be on columns with is_nullable set to true (MySchema::SomeClass/key) | ||||
444 | |||||
445 | If you must be naughty, you can suppress the warning by setting | ||||
446 | C<DBIC_DONT_VALIDATE_RELS> environment variable to a true value. Otherwise, | ||||
447 | you probably just meant to use C<DBIx::Class::Relationship/belongs_to>. | ||||
448 | |||||
449 | =head2 has_one | ||||
450 | |||||
451 | =over 4 | ||||
452 | |||||
453 | =item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs? | ||||
454 | |||||
455 | =back | ||||
456 | |||||
457 | Creates a one-to-one relationship with a class. This relationship | ||||
458 | defaults to using C<$accessor_name> as the foreign key in C<$related_class> to | ||||
459 | resolve the join, unless C<$their_fk_column> specifies the foreign key | ||||
460 | column in C<$related_class> or C<cond> specifies a reference to a join | ||||
461 | condition. | ||||
462 | |||||
463 | =over | ||||
464 | |||||
465 | =item accessor_name | ||||
466 | |||||
467 | This argument is the name of the method you can call on a | ||||
468 | L<DBIx::Class::Row> object to retrieve the instance of the foreign | ||||
469 | class matching this relationship. This is often called the | ||||
470 | C<relation(ship) name>. | ||||
471 | |||||
472 | Use this accessor_name in L<DBIx::Class::ResultSet/join> | ||||
473 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table | ||||
474 | indicated by this relationship. | ||||
475 | |||||
476 | =item related_class | ||||
477 | |||||
478 | This is the class name of the table which contains a foreign key | ||||
479 | column containing PK values of this class. | ||||
480 | |||||
481 | =item their_fk_column | ||||
482 | |||||
483 | The column name on the related class that contains the foreign key. | ||||
484 | |||||
485 | OR | ||||
486 | |||||
487 | =item cond | ||||
488 | |||||
489 | A hashref, arrayref or coderef specifying a custom join expression. For | ||||
490 | more info see L<DBIx::Class::Relationship::Base/condition>. | ||||
491 | |||||
492 | =back | ||||
493 | |||||
494 | # Every book has exactly one ISBN | ||||
495 | My::DBIC::Schema::Book->has_one( | ||||
496 | isbn => | ||||
497 | 'My::DBIC::Schema::ISBN', | ||||
498 | 'book_id', | ||||
499 | ); | ||||
500 | |||||
501 | # OR (same result, assuming related_class stores our PK) | ||||
502 | My::DBIC::Schema::Book->has_one( | ||||
503 | isbn => | ||||
504 | 'My::DBIC::Schema::ISBN', | ||||
505 | ); | ||||
506 | |||||
507 | # OR (same result) | ||||
508 | My::DBIC::Schema::Book->has_one( | ||||
509 | isbn => | ||||
510 | 'My::DBIC::Schema::ISBN', | ||||
511 | { 'foreign.book_id' => 'self.id' }, | ||||
512 | ); | ||||
513 | |||||
514 | # Usage | ||||
515 | my $isbn_obj = $book->isbn; # to get the ISBN object | ||||
516 | |||||
517 | Creates a one-to-one relationship with another class. This is just | ||||
518 | like C<might_have>, except the implication is that the other object is | ||||
519 | always present. The only difference between C<has_one> and | ||||
520 | C<might_have> is that C<has_one> uses an (ordinary) inner join, | ||||
521 | whereas C<might_have> defaults to a left join. | ||||
522 | |||||
523 | The has_one relationship should be used when a row in the table must | ||||
524 | have exactly one related row in another table. If the related row | ||||
525 | might not exist in the foreign table, use the | ||||
526 | L<DBIx::Class::Relationship/might_have> relationship. | ||||
527 | |||||
528 | In the above example, each Book in the database is associated with exactly one | ||||
529 | ISBN object. | ||||
530 | |||||
531 | See L<DBIx::Class::Relationship::Base/attributes> for documentation on | ||||
532 | relationship methods and valid relationship attributes. Also see | ||||
533 | L<DBIx::Class::ResultSet> for a L<list of standard resultset | ||||
534 | attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to | ||||
535 | relationships as well. | ||||
536 | |||||
537 | Note that if you supply a condition on which to join, if the column in the | ||||
538 | current table allows nulls (i.e., has the C<is_nullable> attribute set to a | ||||
539 | true value), than warnings might apply just as with | ||||
540 | L<DBIx::Class::Relationship/might_have>. | ||||
541 | |||||
542 | =head2 many_to_many | ||||
543 | |||||
544 | =over 4 | ||||
545 | |||||
546 | =item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, \%attrs? | ||||
547 | |||||
548 | =back | ||||
549 | |||||
550 | C<many_to_many> is a I<Relationship bridge> which has a specific | ||||
551 | meaning in DBIx::Class, see the definition in the | ||||
552 | L<Glossary|DBIx::Class::Manual::Glossary/Relationship bridge>. | ||||
553 | |||||
554 | C<many_to_many> is not strictly a relationship in its own right. Instead, it is | ||||
555 | a bridge between two resultsets which provide the same kind of convenience | ||||
556 | accessors as true relationships provide. Although the accessor will return a | ||||
557 | resultset or collection of objects just like has_many does, you cannot call | ||||
558 | C<related_resultset> and similar methods which operate on true relationships. | ||||
559 | |||||
560 | =over | ||||
561 | |||||
562 | =item accessor_name | ||||
563 | |||||
564 | This argument is the name of the method you can call on a | ||||
565 | L<DBIx::Class::Row> object to retrieve the rows matching this | ||||
566 | relationship. | ||||
567 | |||||
568 | On a many_to_many, unlike other relationships, this cannot be used in | ||||
569 | L<DBIx::Class::ResultSet/search> to join tables. Use the relations | ||||
570 | bridged across instead. | ||||
571 | |||||
572 | =item link_rel_name | ||||
573 | |||||
574 | This is the accessor_name from the has_many relationship we are | ||||
575 | bridging from. | ||||
576 | |||||
577 | =item foreign_rel_name | ||||
578 | |||||
579 | This is the accessor_name of the belongs_to relationship in the link | ||||
580 | table that we are bridging across (which gives us the table we are | ||||
581 | bridging to). | ||||
582 | |||||
583 | =back | ||||
584 | |||||
585 | To create a many_to_many relationship from Actor to Role: | ||||
586 | |||||
587 | My::DBIC::Schema::Actor->has_many( actor_roles => | ||||
588 | 'My::DBIC::Schema::ActorRoles', | ||||
589 | 'actor' ); | ||||
590 | My::DBIC::Schema::ActorRoles->belongs_to( role => | ||||
591 | 'My::DBIC::Schema::Role' ); | ||||
592 | My::DBIC::Schema::ActorRoles->belongs_to( actor => | ||||
593 | 'My::DBIC::Schema::Actor' ); | ||||
594 | |||||
595 | My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles', | ||||
596 | 'role' ); | ||||
597 | |||||
598 | And, for the reverse relationship, from Role to Actor: | ||||
599 | |||||
600 | My::DBIC::Schema::Role->has_many( actor_roles => | ||||
601 | 'My::DBIC::Schema::ActorRoles', | ||||
602 | 'role' ); | ||||
603 | |||||
604 | My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' ); | ||||
605 | |||||
606 | To add a role for your actor, and fill in the year of the role in the | ||||
607 | actor_roles table: | ||||
608 | |||||
609 | $actor->add_to_roles($role, { year => 1995 }); | ||||
610 | |||||
611 | In the above example, ActorRoles is the link table class, and Role is the | ||||
612 | foreign class. The C<$link_rel_name> parameter is the name of the accessor for | ||||
613 | the has_many relationship from this table to the link table, and the | ||||
614 | C<$foreign_rel_name> parameter is the accessor for the belongs_to relationship | ||||
615 | from the link table to the foreign table. | ||||
616 | |||||
617 | To use many_to_many, existing relationships from the original table to the link | ||||
618 | table, and from the link table to the end table must already exist, these | ||||
619 | relation names are then used in the many_to_many call. | ||||
620 | |||||
621 | In the above example, the Actor class will have 3 many_to_many accessor methods | ||||
622 | set: C<roles>, C<add_to_roles>, C<set_roles>, and similarly named accessors | ||||
623 | will be created for the Role class for the C<actors> many_to_many | ||||
624 | relationship. | ||||
625 | |||||
626 | See L<DBIx::Class::Relationship::Base/attributes> for documentation on | ||||
627 | relationship methods and valid relationship attributes. Also see | ||||
628 | L<DBIx::Class::ResultSet> for a L<list of standard resultset | ||||
629 | attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to | ||||
630 | relationships as well. | ||||
631 | |||||
632 | =cut | ||||
633 | |||||
634 | 1 | 5µs | 1; | ||
635 | |||||
636 | =head1 AUTHORS | ||||
637 | |||||
638 | see L<DBIx::Class> | ||||
639 | |||||
640 | =head1 LICENSE | ||||
641 | |||||
642 | You may distribute this code under the same terms as Perl itself. | ||||
643 | |||||
644 | =cut | ||||
645 |