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 |
d2113a68 |
34 | $schema->resultset('Actor')->roles(); |
35 | $schema->resultset('Role')->search_related('actors', { Name => 'Fred' }); |
fca27358 |
36 | $schema->resultset('ActorRole')->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 | |
951ab5ab |
118 | =item Arguments: $accessor_name, $related_class, $fk_column|\%cond|\@cond?, \%attr? |
2f3105ce |
119 | |
120 | =back |
121 | |
951ab5ab |
122 | Creates a relationship where the calling class stores the foreign |
123 | class's primary key in one (or more) of its columns. This relationship |
124 | defaults to using C<$accessor_name> as the column in this class |
125 | to resolve the join against the primary key from C<$related_class>, |
126 | unless C<$fk_column> specifies the foreign key column in this class or |
127 | 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 | |
8457faf7 |
147 | =item 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 |
156 | the values are C<self.$foreign_key_column>. This is useful for |
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 |
215 | methods and valid relationship attributes. |
2535b501 |
216 | |
bfab575a |
217 | =head2 has_many |
503536d5 |
218 | |
2f3105ce |
219 | =over 4 |
220 | |
951ab5ab |
221 | =item Arguments: $accessor_name, $related_class, $foreign_key_column|\%cond|\@cond?, \%attr? |
2f3105ce |
222 | |
223 | =back |
224 | |
e951858e |
225 | Creates a one-to-many relationship, where the corresponding elements |
226 | of the foreign class store the calling class's primary key in one (or |
227 | more) of its columns. This relationship defaults to using the end of |
228 | this classes namespace as the foreign key in C<$related_class> to |
229 | resolve the join, unless C<$foreign_key_column> specifies the foreign |
230 | key column in C<$related_class> or C<cond> specifies a reference to a |
231 | join condition hash. |
7a2c1380 |
232 | |
233 | =over |
234 | |
235 | =item accessor_name |
236 | |
237 | This argument is the name of the method you can call on a |
238 | L<DBIx::Class::Row> object to retrieve a resultset of the related |
239 | class restricted to the ones related to the row object. In list |
951ab5ab |
240 | context it returns the row objects. This is often called the |
241 | C<relation(ship) name>. |
7a2c1380 |
242 | |
951ab5ab |
243 | Use this accessor_name in L<DBIx::Class::ResultSet/join> |
7a2c1380 |
244 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table |
245 | indicated by this relationship. |
246 | |
247 | =item related_class |
248 | |
249 | This is the class name of the table which contains a foreign key |
250 | column containing PK values of this class. |
251 | |
252 | =item foreign_key_column |
253 | |
254 | The column name on the related class that contains the foreign key. |
255 | |
256 | OR |
257 | |
258 | =item cond |
259 | |
951ab5ab |
260 | A hashref where the keys are C<foreign.$foreign_key_column> and |
261 | the values are C<self.$matching_column>. This is useful for |
7a2c1380 |
262 | relations that are across multiple columns. |
263 | |
951ab5ab |
264 | OR |
265 | |
266 | An arrayref containing an SQL::Abstract-like condition. For example a |
267 | link table where two columns link back to the same table. This is an |
268 | OR condition. |
269 | |
270 | My::Schema::Item->has_many('rels', 'My::Schema::Relationships', |
271 | [ { 'foreign.LItemID' => 'self.ID' }, |
272 | { 'foreign.RItemID' => 'self.ID'} ]); |
da2e2b76 |
273 | |
7a2c1380 |
274 | =back |
275 | |
b8810cc5 |
276 | # in an Author class (where Author has_many Books) |
e951858e |
277 | # assuming related class is storing our PK in "author_id" |
951ab5ab |
278 | My::DBIC::Schema::Author->has_many( |
279 | books => |
280 | 'My::DBIC::Schema::Book', |
281 | 'author_id' |
282 | ); |
283 | |
e951858e |
284 | # OR (same result) |
951ab5ab |
285 | My::DBIC::Schema::Author->has_many( |
286 | books => |
287 | 'My::DBIC::Schema::Book', |
e951858e |
288 | { 'foreign.author_id' => 'self.id' }, |
951ab5ab |
289 | ); |
e951858e |
290 | |
291 | # OR (similar result, assuming related_class is storing our PK, in "author") |
292 | # (the "author" is guessed at from "Author" in the class namespace) |
951ab5ab |
293 | My::DBIC::Schema::Author->has_many( |
294 | books => |
295 | 'My::DBIC::Schema::Book', |
951ab5ab |
296 | ); |
e951858e |
297 | |
2535b501 |
298 | |
951ab5ab |
299 | # Usage |
300 | # resultset of Books belonging to author |
301 | my $booklist = $author->books; |
302 | |
303 | # resultset of Books belonging to author, restricted by author name |
304 | my $booklist = $author->books({ |
bc0c9800 |
305 | name => { LIKE => '%macaroni%' }, |
306 | { prefetch => [qw/book/], |
307 | }); |
503536d5 |
308 | |
951ab5ab |
309 | # array of Book objects belonging to author |
310 | my @book_objs = $author->books; |
503536d5 |
311 | |
951ab5ab |
312 | # force resultset even in list context |
313 | my $books_rs = $author->books; |
314 | ( $books_rs ) = $obj->books_rs; |
315 | |
316 | # create a new book for this author, the relation fields are auto-filled |
317 | $author->create_related('books', \%col_data); |
318 | # alternative method for the above |
319 | $author->add_to_books(\%col_data); |
2535b501 |
320 | |
2535b501 |
321 | |
60a8fb95 |
322 | Three methods are created when you create a has_many relationship. The first |
2f3105ce |
323 | method is the expected accessor method, C<$accessor_name()>. The second is |
324 | almost exactly the same as the accessor method but "_rs" is added to the end of |
325 | the method name. This method works just like the normal accessor, except that |
951ab5ab |
326 | it always returns a resultset, even in list context. The third method, |
2535b501 |
327 | named C<< add_to_$relname >>, will also be added to your Row items; this |
2f3105ce |
328 | allows you to insert new related items, using the same mechanism as in |
5b89a768 |
329 | L<DBIx::Class::Relationship::Base/"create_related">. |
d2113a68 |
330 | |
8091aa91 |
331 | If you delete an object in a class with a C<has_many> relationship, all |
b8810cc5 |
332 | the related objects will be deleted as well. To turn this behaviour off, |
2a2ab6ab |
333 | pass C<< cascade_delete => 0 >> in the C<$attr> hashref. |
334 | |
335 | The cascaded operations are performed after the requested delete or |
336 | update, so if your database has a constraint on the relationship, it |
337 | will have deleted/updated the related records or raised an exception |
338 | before DBIx::Class gets to perform the cascaded operation. |
503536d5 |
339 | |
f4e92c39 |
340 | If you copy an object in a class with a C<has_many> relationship, all |
341 | the related objects will be copied as well. To turn this behaviour off, |
2fef093d |
342 | pass C<< cascade_copy => 0 >> in the C<$attr> hashref. The behaviour |
343 | defaults to C<< cascade_copy => 1 >>. |
f4e92c39 |
344 | |
9e64dfbf |
345 | See L<DBIx::Class::Relationship::Base> for documentation on relationship |
346 | methods and valid relationship attributes. |
2535b501 |
347 | |
bfab575a |
348 | =head2 might_have |
503536d5 |
349 | |
2f3105ce |
350 | =over 4 |
351 | |
951ab5ab |
352 | =item Arguments: $accessor_name, $related_class, $foreign_key_column|\%cond|\@cond?, \%attr? |
2f3105ce |
353 | |
354 | =back |
355 | |
7a2c1380 |
356 | Creates an optional one-to-one relationship with a class. This relationship |
357 | defaults to using C<$accessor_name> as the foreign key in C<$related_class> to |
358 | resolve the join, unless C<$foreign_key_column> specifies the foreign key |
951ab5ab |
359 | column in C<$related_class> or C<cond> specifies a reference to a join |
7a2c1380 |
360 | condition hash. |
361 | |
362 | =over |
363 | |
364 | =item accessor_name |
365 | |
366 | This argument is the name of the method you can call on a |
367 | L<DBIx::Class::Row> object to retrieve the instance of the foreign |
951ab5ab |
368 | class matching this relationship. This is often called the |
369 | C<relation(ship) name>. |
7a2c1380 |
370 | |
951ab5ab |
371 | Use this accessor_name in L<DBIx::Class::ResultSet/join> |
7a2c1380 |
372 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table |
373 | indicated by this relationship. |
374 | |
375 | =item related_class |
376 | |
377 | This is the class name of the table which contains a foreign key |
378 | column containing PK values of this class. |
379 | |
380 | =item foreign_key_column |
381 | |
382 | The column name on the related class that contains the foreign key. |
383 | |
384 | OR |
385 | |
386 | =item cond |
387 | |
388 | A hashref where the keys are C<foreign.$column_on_related_table> and |
b281b5e9 |
389 | the values are C<self.$matching_column>. This is useful for |
7a2c1380 |
390 | relations that are across multiple columns. |
391 | |
392 | =back |
393 | |
951ab5ab |
394 | # Author may have an entry in the pseudonym table |
395 | My::DBIC::Schema::Author->might_have( |
396 | pseudonym => |
397 | 'My::DBIC::Schema::Pseudonym', |
398 | 'author_id', |
399 | ); |
400 | |
401 | # OR (same result, assuming the related_class stores our PK) |
402 | My::DBIC::Schema::Author->might_have( |
403 | pseudonym => |
404 | 'My::DBIC::Schema::Pseudonym', |
405 | ); |
406 | |
407 | # OR (same result) |
408 | My::DBIC::Schema::Author->might_have( |
409 | pseudonym => |
410 | 'My::DBIC::Schema::Pseudonym', |
411 | { 'foreign.author_id' => 'self.id' }, |
412 | ); |
413 | |
414 | # Usage |
415 | my $pname = $author->pseudonym; # to get the Pseudonym object |
9e64dfbf |
416 | |
c99393ff |
417 | If you update or delete an object in a class with a C<might_have> |
b8810cc5 |
418 | relationship, the related object will be updated or deleted as well. To |
419 | turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr> |
2a2ab6ab |
420 | hashref. |
421 | |
422 | The cascaded operations are performed after the requested delete or |
423 | update, so if your database has a constraint on the relationship, it |
424 | will have deleted/updated the related records or raised an exception |
425 | before DBIx::Class gets to perform the cascaded operation. |
503536d5 |
426 | |
9e64dfbf |
427 | See L<DBIx::Class::Relationship::Base> for documentation on relationship |
428 | methods and valid relationship attributes. |
2f3105ce |
429 | |
bfab575a |
430 | =head2 has_one |
431 | |
2f3105ce |
432 | =over 4 |
433 | |
951ab5ab |
434 | =item Arguments: $accessor_name, $related_class, $foreign_key_column|\%cond|\@cond?, \%attr? |
2f3105ce |
435 | |
436 | =back |
437 | |
951ab5ab |
438 | Creates a one-to-one relationship with a class. This relationship |
439 | defaults to using C<$accessor_name> as the foreign key in C<$related_class> to |
440 | resolve the join, unless C<$foreign_key_column> specifies the foreign key |
441 | column in C<$related_class> or C<cond> specifies a reference to a join |
442 | condition hash. |
2f3105ce |
443 | |
951ab5ab |
444 | =over |
445 | |
446 | =item accessor_name |
447 | |
448 | This argument is the name of the method you can call on a |
449 | L<DBIx::Class::Row> object to retrieve the instance of the foreign |
450 | class matching this relationship. This is often called the |
451 | C<relation(ship) name>. |
452 | |
453 | Use this accessor_name in L<DBIx::Class::ResultSet/join> |
454 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table |
455 | indicated by this relationship. |
456 | |
457 | =item related_class |
458 | |
459 | This is the class name of the table which contains a foreign key |
460 | column containing PK values of this class. |
461 | |
462 | =item foreign_key_column |
463 | |
464 | The column name on the related class that contains the foreign key. |
465 | |
466 | OR |
467 | |
468 | =item cond |
469 | |
470 | A hashref where the keys are C<foreign.$column_on_related_table> and |
b281b5e9 |
471 | the values are C<self.$matching_column>. This is useful for |
951ab5ab |
472 | relations that are across multiple columns. |
473 | |
474 | =back |
bfab575a |
475 | |
951ab5ab |
476 | # Every book has exactly one ISBN |
477 | My::DBIC::Schema::Book->has_one( |
478 | isbn => |
479 | 'My::DBIC::Schema::ISBN', |
480 | 'book_id', |
481 | ); |
482 | |
483 | # OR (same result, assuming related_class stores our PK) |
484 | My::DBIC::Schema::Book->has_one( |
485 | isbn => |
486 | 'My::DBIC::Schema::ISBN', |
487 | ); |
488 | |
489 | # OR (same result) |
490 | My::DBIC::Schema::Book->has_one( |
491 | isbn => |
492 | 'My::DBIC::Schema::ISBN', |
493 | { 'foreign.book_id' => 'self.id' }, |
494 | ); |
495 | |
496 | # Usage |
497 | my $isbn_obj = $book->isbn; # to get the ISBN object |
498 | |
499 | Creates a one-to-one relationship with another class. This is just |
500 | like C<might_have>, except the implication is that the other object is |
501 | always present. The only difference between C<has_one> and |
502 | C<might_have> is that C<has_one> uses an (ordinary) inner join, |
503 | whereas C<might_have> defaults to a left join. |
503536d5 |
504 | |
2f3105ce |
505 | The has_one relationship should be used when a row in the table has exactly one |
506 | related row in another table. If the related row might not exist in the foreign |
507 | table, use the L<DBIx::Class::Relationship/might_have> relationship. |
508 | |
509 | In the above example, each Book in the database is associated with exactly one |
510 | ISBN object. |
7411204b |
511 | |
9e64dfbf |
512 | See L<DBIx::Class::Relationship::Base> for documentation on relationship |
513 | methods and valid relationship attributes. |
87c4e602 |
514 | |
2535b501 |
515 | =head2 many_to_many |
2f3105ce |
516 | |
517 | =over 4 |
518 | |
951ab5ab |
519 | =item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, \%attr? |
303cf522 |
520 | |
2f3105ce |
521 | =back |
522 | |
7a2c1380 |
523 | C<many_to_many> is not strictly a relationship in its own right. Instead, it is |
524 | a bridge between two resultsets which provide the same kind of convenience |
525 | accessors as true relationships provide. Although the accessor will return a |
526 | resultset or collection of objects just like has_many does, you cannot call |
527 | C<related_resultset> and similar methods which operate on true relationships. |
528 | |
529 | =over |
530 | |
531 | =item accessor_name |
532 | |
533 | This argument is the name of the method you can call on a |
534 | L<DBIx::Class::Row> object to retrieve the rows matching this |
535 | relationship. |
536 | |
537 | On a many_to_many, unlike other relationships, this cannot be used in |
538 | L<DBIx::Class::ResultSet/search> to join tables. Use the relations |
539 | bridged across instead. |
540 | |
541 | =item link_rel_name |
542 | |
543 | This is the accessor_name from the has_many relationship we are |
544 | bridging from. |
545 | |
546 | =item foreign_rel_name |
547 | |
548 | This is the accessor_name of the belongs_to relationship in the link |
549 | table that we are bridging across (which gives us the table we are |
550 | bridging to). |
551 | |
552 | =back |
553 | |
2f3105ce |
554 | To create a many_to_many relationship from Actor to Role: |
555 | |
75d07914 |
556 | My::DBIC::Schema::Actor->has_many( actor_roles => |
d2113a68 |
557 | 'My::DBIC::Schema::ActorRoles', |
558 | 'actor' ); |
75d07914 |
559 | My::DBIC::Schema::ActorRoles->belongs_to( role => |
d2113a68 |
560 | 'My::DBIC::Schema::Role' ); |
75d07914 |
561 | My::DBIC::Schema::ActorRoles->belongs_to( actor => |
d2113a68 |
562 | 'My::DBIC::Schema::Actor' ); |
563 | |
564 | My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles', |
71d5ed18 |
565 | 'role' ); |
bc0c9800 |
566 | |
2f3105ce |
567 | And, for the reverse relationship, from Role to Actor: |
568 | |
569 | My::DBIC::Schema::Role->has_many( actor_roles => |
570 | 'My::DBIC::Schema::ActorRoles', |
571 | 'role' ); |
572 | |
573 | My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' ); |
574 | |
787d6a29 |
575 | To add a role for your actor, and fill in the year of the role in the |
576 | actor_roles table: |
577 | |
578 | $actor->add_to_roles($role, { year => 1995 }); |
579 | |
2535b501 |
580 | In the above example, ActorRoles is the link table class, and Role is the |
581 | foreign class. The C<$link_rel_name> parameter is the name of the accessor for |
582 | the has_many relationship from this table to the link table, and the |
583 | C<$foreign_rel_name> parameter is the accessor for the belongs_to relationship |
584 | from the link table to the foreign table. |
585 | |
d2113a68 |
586 | To use many_to_many, existing relationships from the original table to the link |
75d07914 |
587 | table, and from the link table to the end table must already exist, these |
d2113a68 |
588 | relation names are then used in the many_to_many call. |
7411204b |
589 | |
2535b501 |
590 | In the above example, the Actor class will have 3 many_to_many accessor methods |
951ab5ab |
591 | set: C<roles>, C<add_to_roles>, C<set_roles>, and similarly named accessors |
2535b501 |
592 | will be created for the Role class for the C<actors> many_to_many |
593 | relationship. |
594 | |
9e64dfbf |
595 | See L<DBIx::Class::Relationship::Base> for documentation on relationship |
596 | methods and valid relationship attributes. |
2f3105ce |
597 | |
34d52be2 |
598 | =cut |
599 | |
b8e1e21f |
600 | 1; |
34d52be2 |
601 | |
34d52be2 |
602 | =head1 AUTHORS |
603 | |
951ab5ab |
604 | see L<DBIx::Class> |
34d52be2 |
605 | |
606 | =head1 LICENSE |
607 | |
608 | You may distribute this code under the same terms as Perl itself. |
609 | |
610 | =cut |
611 | |