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