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