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