lib/DBIx/Class/Relationship.pm

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