lib/DBIx/Class/Relationship/Base.pm

   1 package DBIx::Class::Relationship::Base;
   2
   3 use strict;
   4 use warnings;
   5
   6 use base qw/DBIx::Class/;
   7
   8 __PACKAGE__->mk_classdata('_relationships', { } );
   9
  10 =head1 NAME
  11
  12 DBIx::Class::Relationship::Base - Inter-table relationships
  13
  14 =head1 SYNOPSIS
  15
  16 =head1 DESCRIPTION
  17
  18 This class provides methods to describe the relationships between the
  19 tables in your database model. These are the "bare bones" relationships
  20 methods, for predefined ones, look in L<DBIx::Class::Relationship>.
  21
  22 =head1 METHODS
  23
  24 =head2 add_relationship
  25
  26 =head3 Arguments: ('relname', 'Foreign::Class', $cond, $attrs)
  27
  28   __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);
  29
  30 The condition needs to be an SQL::Abstract-style representation of the
  31 join between the tables. When resolving the condition for use in a JOIN,
  32 keys using the psuedo-table I<foreign> are resolved to mean "the Table on the
  33 other side of the relationship", and values using the psuedo-table I<self>
  34 are resolved to mean "the Table this class is representing". Other
  35 restrictions, such as by value, sub-select and other tables, may also be
  36 used. Please check your database for JOIN parameter support.
  37
  38 For example, if you're creating a rel from Author to Book, where the Book
  39 table has a column author_id containing the ID of the Author row:
  40
  41   { 'foreign.author_id' => 'self.id' }
  42
  43 will result in the JOIN clause
  44
  45   author me JOIN book book ON bar.author_id = me.id
  46
  47 You can specify as many foreign => self mappings as necessary. Each key/value
  48 pair provided in a hashref will be used as ANDed conditions, to add an ORed
  49 condition, use an arrayref of hashrefs. See the L<SQL::Abstract> documentation
  50 for more details.
  51
  52 Valid attributes are as follows:
  53
  54 =over 4
  55
  56 =item join_type
  57
  58 Explicitly specifies the type of join to use in the relationship. Any SQL
  59 join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
  60 command immediately before C<JOIN>.
  61
  62 =item proxy
  63
  64 An arrayref containing a list of accessors in the foreign class to create in
  65 the main class. If, for example, you do the following:
  66
  67   MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes', undef, {
  68     proxy => [ qw/notes/ ],
  69   });
  70
  71 Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:
  72
  73   my $cd = MyDB::Schema::CD->find(1);
  74   $cd->notes('Notes go here'); # set notes -- LinerNotes object is
  75                                # created if it doesn't exist
  76
  77 =item accessor
  78
  79 Specifies the type of accessor that should be created for the relationship.
  80 Valid values are C<single> (for when there is only a single related object),
  81 C<multi> (when there can be many), and C<filter> (for when there is a single
  82 related object, but you also want the relationship accessor to double as
  83 a column accessor). For C<multi> accessors, an add_to_* method is also
  84 created, which calls C<create_related> for the relationship.
  85
  86 =back
  87
  88 =head2 register_relationship
  89
  90 =head3 Arguments: ($relname, $rel_info)
  91
  92 Registers a relationship on the class. This is called internally by
  93 L<DBIx::Class::ResultSourceProxy> to set up Accessors and Proxies.
  94
  95 =cut
  96
  97 sub register_relationship { }
  98
  99 =head2 related_resultset($name)
 100
 101   $rs = $obj->related_resultset('related_table');
 102
 103 Returns a L<DBIx::Class::ResultSet> for the relationship named $name.
 104
 105 =cut
 106
 107 sub related_resultset {
 108   my $self = shift;
 109   $self->throw_exception("Can't call *_related as class methods") unless ref $self;
 110   my $rel = shift;
 111   my $rel_obj = $self->relationship_info($rel);
 112   $self->throw_exception( "No such relationship ${rel}" ) unless $rel_obj;
 113
 114   return $self->{related_resultsets}{$rel} ||= do {
 115     my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
 116     $attrs = { %{$rel_obj->{attrs} || {}}, %$attrs };
 117
 118     $self->throw_exception( "Invalid query: @_" ) if (@_ > 1 && (@_ % 2 == 1));
 119     my $query = ((@_ > 1) ? {@_} : shift);
 120
 121     my $cond = $self->result_source->resolve_condition($rel_obj->{cond}, $rel, $self);
 122     if (ref $cond eq 'ARRAY') {
 123       $cond = [ map { my $hash;
 124         foreach my $key (keys %$_) {
 125           my $newkey = $key =~ /\./ ? "me.$key" : $key;
 126           $hash->{$newkey} = $_->{$key};
 127         }; $hash } @$cond ];
 128     } else {
 129       foreach my $key (grep { ! /\./ } keys %$cond) {
 130         $cond->{"me.$key"} = delete $cond->{$key};
 131       }
 132     }
 133     $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
 134     $self->result_source->related_source($rel)->resultset->search($query, $attrs);
 135   };
 136 }
 137
 138 =head2 search_related
 139
 140   $rs->search_related('relname', $cond, $attrs);
 141
 142 Run a search on a related resultset. The search will be restricted to the
 143 item or items represented by the L<DBIx::Class::ResultSet> it was called
 144 upon. This method can be called on a ResultSet, a Row or a ResultSource class.
 145
 146 =cut
 147
 148 sub search_related {
 149   return shift->related_resultset(shift)->search(@_);
 150 }
 151
 152 =head2 count_related
 153
 154   $obj->count_related('relname', $cond, $attrs);
 155
 156 Returns the count of all the items in the related resultset, restricted by
 157 the current item or where conditions. Can be called on a L<DBIx::Classl::Manual::Glossary/"ResultSet"> or a L<DBIx::Class::Manual::Glossary/"Row"> object.
 158
 159 =cut
 160
 161 sub count_related {
 162   my $self = shift;
 163   return $self->search_related(@_)->count;
 164 }
 165
 166 =head2 new_related
 167
 168   my $new_obj = $obj->new_related('relname', \%col_data);
 169
 170 Create a new item of the related foreign class. If called on a
 171 L<DBIx::Class::Manual::Glossary/"Row"> object, it will magically
 172 set any primary key values into foreign key columns for you. The newly
 173 created item will not be saved into your storage until you call C<insert>
 174 on it.
 175
 176 =cut
 177
 178 sub new_related {
 179   my ($self, $rel, $values, $attrs) = @_;
 180   return $self->search_related($rel)->new($values, $attrs);
 181 }
 182
 183 =head2 create_related
 184
 185   my $new_obj = $obj->create_related('relname', \%col_data);
 186
 187 Creates a new item, similarly to new_related, and also inserts the item's data
 188 into your storage medium. See the distinction between C<create> and C<new>
 189 in L<DBIx::Class::ResultSet> for details.
 190
 191 =cut
 192
 193 sub create_related {
 194   my $self = shift;
 195   my $rel = shift;
 196   my $obj = $self->search_related($rel)->create(@_);
 197   delete $self->{related_resultsets}->{$rel};
 198   return $obj;
 199 }
 200
 201 =head2 find_related
 202
 203   my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
 204
 205 Attempt to find a related object using its primary key or unique constraints.
 206 See C<find> in L<DBIx::Class::ResultSet> for details.
 207
 208 =cut
 209
 210 sub find_related {
 211   my $self = shift;
 212   my $rel = shift;
 213   return $self->search_related($rel)->find(@_);
 214 }
 215
 216 =head2 find_or_create_related
 217
 218   my $new_obj = $obj->find_or_create_related('relname', \%col_data);
 219
 220 Find or create an item of a related class. See C<find_or_create> in
 221 L<DBIx::Class::ResultSet> for details.
 222
 223 =cut
 224
 225 sub find_or_create_related {
 226   my $self = shift;
 227   return $self->find_related(@_) || $self->create_related(@_);
 228 }
 229
 230 =head2 set_from_related
 231
 232   $book->set_from_related('author', $author_obj);
 233
 234 Set column values on the current object, using related values from the given
 235 related object. This is used to associate previously separate objects, for
 236 example, to set the correct author for a book, find the Author object, then
 237 call set_from_related on the book.
 238
 239 The columns are only set in the local copy of the object, call C<update> to set
 240 them in the storage.
 241
 242 =cut
 243
 244 sub set_from_related {
 245   my ($self, $rel, $f_obj) = @_;
 246   my $rel_obj = $self->relationship_info($rel);
 247   $self->throw_exception( "No such relationship ${rel}" ) unless $rel_obj;
 248   my $cond = $rel_obj->{cond};
 249   $self->throw_exception( "set_from_related can only handle a hash condition; the "
 250     ."condition for $rel is of type ".(ref $cond ? ref $cond : 'plain scalar'))
 251       unless ref $cond eq 'HASH';
 252   my $f_class = $self->result_source->schema->class($rel_obj->{class});
 253   $self->throw_exception( "Object $f_obj isn't a ".$f_class )
 254     unless $f_obj->isa($f_class);
 255   $self->set_columns(
 256     $self->result_source->resolve_condition(
 257        $rel_obj->{cond}, $f_obj, $rel));
 258   return 1;
 259 }
 260
 261 =head2 update_from_related
 262
 263   $book->update_from_related('author', $author_obj);
 264
 265 As C<set_from_related>, but the changes are immediately updated onto your
 266 storage.
 267
 268 =cut
 269
 270 sub update_from_related {
 271   my $self = shift;
 272   $self->set_from_related(@_);
 273   $self->update;
 274 }
 275
 276 =head2 delete_related
 277
 278   $obj->delete_related('relname', $cond, $attrs);
 279
 280 Delete any related item subject to the given conditions.
 281
 282 =cut
 283
 284 sub delete_related {
 285   my $self = shift;
 286   my $obj = $self->search_related(@_)->delete;
 287   delete $self->{related_resultsets}->{$_[0]};
 288   return $obj;
 289 }
 290
 291 1;
 292
 293 =head1 AUTHORS
 294
 295 Matt S. Trout <mst@shadowcatsystems.co.uk>
 296
 297 =head1 LICENSE
 298
 299 You may distribute this code under the same terms as Perl itself.
 300
 301 =cut
 302