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