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   HasMany
  10   HasOne
  11   BelongsTo
  12   Accessor
  13   CascadeActions
  14   ProxyMethods
  15   Base
  16 /);
  17
  18 __PACKAGE__->mk_classdata('_relationships', { } );
  19
  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
  29 model. It allows you to set up relationships and perform joins on them.
  30
  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>.
  34
  35 =head1 METHODS
  36
  37 All helper methods take the following arguments:
  38
  39   __PACKAGE__>$method_name('relname', 'Foreign::Class', $cond, $attrs);
  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>.
  43 See L<DBIx::Class::Relationship::Base> for a list of valid attributes.
  44
  45 =head2 belongs_to
  46
  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);
  51
  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.
  57
  58 NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
  59 of C<has_a>.
  60
  61 =head2 has_many
  62
  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;
  68
  69   $obj->add_to_foo(\%col_data);
  70
  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.
  79
  80 =head2 might_have
  81
  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.
  88
  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.
  92
  93 =head2 has_one
  94
  95   __PACKAGE__->has_one(gorch => Gorch);
  96   my $f_obj = $obj->gorch;
  97
  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.
 102
 103 =cut
 104
 105 1;
 106
 107 =head1 AUTHORS
 108
 109 Matt S. Trout <mst@shadowcatsystems.co.uk>
 110
 111 =head1 LICENSE
 112
 113 You may distribute this code under the same terms as Perl itself.
 114
 115 =cut
 116