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 | |
34d52be2 |
16 | =head1 NAME |
17 | |
18 | DBIx::Class::Relationship - Inter-table relationships |
19 | |
20 | =head1 SYNOPSIS |
21 | |
22 | =head1 DESCRIPTION |
23 | |
24 | This class handles relationships between the tables in your database |
bfab575a |
25 | model. It allows you to set up relationships and perform joins on them. |
34d52be2 |
26 | |
bfab575a |
27 | Only the helper methods for setting up standard relationship types |
28 | are documented here. For the basic, lower-level methods, see |
29 | L<DBIx::Class::Relationship::Base>. |
503536d5 |
30 | |
34d52be2 |
31 | =head1 METHODS |
32 | |
bfab575a |
33 | All helper methods take the following arguments: |
503536d5 |
34 | |
8091aa91 |
35 | __PACKAGE__>$method_name('relname', 'Foreign::Class', $cond, $attrs); |
bfab575a |
36 | |
37 | Both C<$cond> and C<$attrs> are optional. Pass C<undef> for C<$cond> if |
38 | you want to use the default value for it, but still want to set C<$attrs>. |
8091aa91 |
39 | See L<DBIx::Class::Relationship::Base> for a list of valid attributes. |
503536d5 |
40 | |
bfab575a |
41 | =head2 belongs_to |
503536d5 |
42 | |
8091aa91 |
43 | # in a Bar class (where Foo has many Bars) |
44 | __PACKAGE__->belongs_to(foo => Foo); |
45 | my $f_obj = $obj->foo; |
46 | $obj->foo($new_f_obj); |
503536d5 |
47 | |
8091aa91 |
48 | Creates a relationship where the calling class stores the foreign class's |
49 | primary key in one (or more) of its columns. If $cond is a column name |
50 | instead of a join condition hash, that is used as the name of the column |
51 | holding the foreign key. If $cond is not given, the relname is used as |
52 | the column name. |
bfab575a |
53 | |
8091aa91 |
54 | NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent |
55 | of C<has_a>. |
503536d5 |
56 | |
bfab575a |
57 | =head2 has_many |
503536d5 |
58 | |
8091aa91 |
59 | # in a Foo class (where Foo has many Bars) |
60 | __PACKAGE__->has_many(bar => Bar, 'foo'); |
61 | my $f_resultset = $obj->foo; |
62 | my $f_resultset = $obj->foo({ name => { LIKE => '%macaroni%' }, { prefetch => [qw/bar/] }); |
63 | my @f_obj = $obj->foo; |
503536d5 |
64 | |
8091aa91 |
65 | $obj->add_to_foo(\%col_data); |
503536d5 |
66 | |
8091aa91 |
67 | Creates a one-to-many relationship, where the corresponding elements of the |
68 | foreign class store the calling class's primary key in one (or more) of its |
69 | columns. You should pass the name of the column in the foreign class as the |
70 | $cond argument, or specify a complete join condition. |
71 | |
72 | If you delete an object in a class with a C<has_many> relationship, all |
73 | related objects will be deleted as well. However, any database-level |
74 | cascade or restrict will take precedence. |
503536d5 |
75 | |
bfab575a |
76 | =head2 might_have |
503536d5 |
77 | |
8091aa91 |
78 | __PACKAGE__->might_have(baz => Baz); |
79 | my $f_obj = $obj->baz; # to get the baz object |
80 | |
81 | Creates an optional one-to-one relationship with a class, where the foreign class |
82 | stores our primary key in one of its columns. Defaults to the primary key of the |
83 | foreign class unless $cond specifies a column or join condition. |
503536d5 |
84 | |
8091aa91 |
85 | If you update or delete an object in a class with a C<might_have> relationship, |
86 | the related object will be updated or deleted as well. Any database-level update |
87 | or delete constraints will override this behavior. |
503536d5 |
88 | |
bfab575a |
89 | =head2 has_one |
90 | |
8091aa91 |
91 | __PACKAGE__->has_one(gorch => Gorch); |
92 | my $f_obj = $obj->gorch; |
bfab575a |
93 | |
8091aa91 |
94 | Creates a one-to-one relationship with another class. This is just like C<might_have>, |
95 | except the implication is that the other object is always present. The only different |
96 | between C<has_one> and C<might_have> is that C<has_one> uses an (ordinary) inner join, |
97 | whereas C<might_have> uses a left join. |
503536d5 |
98 | |
7411204b |
99 | |
87c4e602 |
100 | =head2 many_to_many |
101 | |
b8eca5ce |
102 | __PACKAGE__->many_to_many( 'accessorname' => 'a_to_b', 'table_b' ); |
103 | my @f_objs = $obj_a->accessorname; |
104 | |
105 | Creates an accessor bridging two relationships; not strictly a relationship |
106 | in its own right, although the accessor will return a resultset or collection |
107 | of objects just as a has_many would. |
7411204b |
108 | |
34d52be2 |
109 | =cut |
110 | |
b8e1e21f |
111 | 1; |
34d52be2 |
112 | |
34d52be2 |
113 | =head1 AUTHORS |
114 | |
daec44b8 |
115 | Matt S. Trout <mst@shadowcatsystems.co.uk> |
34d52be2 |
116 | |
117 | =head1 LICENSE |
118 | |
119 | You may distribute this code under the same terms as Perl itself. |
120 | |
121 | =cut |
122 | |