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 The following attributes are recognize:
  44
  45 =over 4
  46
  47 =item join_type
  48
  49 Explicitly specifies the type of join to use in the relationship. Any SQL
  50 join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
  51 command immediately before C<JOIN>.
  52
  53 =item proxy
  54
  55 An arrayref containing a list of accessors in the foreign class to proxy in
  56 the main class. If, for example, you do the following:
  57
  58   __PACKAGE__->might_have(bar => 'Bar', undef, { proxy => qw[/ margle /] });
  59
  60 Then, assuming Bar has an accessor named margle, you can do:
  61
  62   my $obj = Foo->find(1);
  63   $obj->margle(10); # set margle; Bar object is created if it doesn't exist
  64
  65 =back
  66
  67 =head2 belongs_to
  68
  69   my $f_obj = $obj->relname;
  70
  71   $obj->relname($new_f_obj);
  72
  73 Creates a relationship where we store the foreign class' PK; if $join is a
  74 column name instead of a condition that is assumed to be the FK, if not
  75 has_many assumes the FK is the relname is that is a column on the current
  76 class.
  77
  78 =head2 has_many
  79
  80   my @f_obj = $obj->relname($cond?, $attrs?);
  81   my $f_result_set = $obj->relname($cond?, $attrs?);
  82
  83   $obj->add_to_relname(\%col_data);
  84
  85 Creates a one-many relationship with another class;
  86
  87 =head2 might_have
  88
  89   my $f_obj = $obj->relname;
  90
  91 Creates an optional one-one relationship with another class; defaults to PK-PK
  92 for the join condition unless a condition is specified.
  93
  94 =head2 has_one
  95
  96   my $f_obj = $obj->relname;
  97
  98 Creates a one-one relationship with another class; defaults to PK-PK for
  99 the join condition unless a condition is specified.
 100
 101 =cut
 102
 103 1;
 104
 105 =head1 AUTHORS
 106
 107 Matt S. Trout <mst@shadowcatsystems.co.uk>
 108
 109 =head1 LICENSE
 110
 111 You may distribute this code under the same terms as Perl itself.
 112
 113 =cut
 114