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