view release on metacpan or  search on metacpan

lib/DBIO/Relationship/Base.pm  view on Meta::CPAN

Will properly set the C<< $artist->artistid >> field of this new object to C<1>

Note that in order to be able to use L</set_from_related> (and by extension
L<< $result->create_related|DBIO::Relationship::Base/create_related >>),
the returned join free condition B<must> contain only plain values/deflatable
objects. For instance the C<year> constraint in the above example prevents
the relationship from being used to create related objects using
C<< $artst->create_related( cds_80s => { title => 'blah' } ) >> (an
exception will be thrown).

In order to allow the user to go truly crazy when generating a custom C<ON>
clause, the C<$args> hashref passed to the subroutine contains some extra
metadata. Currently the supplied coderef is executed as:

  $relationship_info->{cond}->({
    self_resultsource   => The resultsource instance on which rel_name is registered
    rel_name            => The relationship name (does *NOT* always match foreign_alias)

    self_alias          => The alias of the invoking resultset
    foreign_alias       => The alias of the to-be-joined resultset (does *NOT* always match rel_name)

    # only one of these (or none at all) will ever be supplied to aid in the
    # construction of a join-free condition

    self_result_object  => The invocant *object* itself in case of a call like
                           $result_object->$rel_name( ... )

    foreign_values      => A *hashref* of related data: may be passed in directly or
                           derived via ->get_columns() from a related object in case of
                           $result_object->set_from_related( $rel_name, $foreign_result_object )

    # deprecated inconsistent names, will be forever available for legacy code
    self_rowobj         => Old deprecated slot for self_result_object
    foreign_relname     => Old deprecated slot for rel_name
  });

=head3 attributes

The L<standard ResultSet attributes|DBIO::ResultSet/ATTRIBUTES> may
be used as relationship attributes. In particular, the 'where' attribute is
useful for filtering relationships:

     __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
        { 'foreign.user_id' => 'self.user_id' },
        { where => { valid => 1 } }
    );

The following attributes are also valid:

=over 4

=item join_type

Explicitly specifies the type of join to use in the relationship. Any SQL
join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
command immediately before C<JOIN>.

=item proxy =E<gt> $column | \@columns | \%column

The 'proxy' attribute can be used to retrieve values, and to perform
updates if the relationship has 'cascade_update' set. The 'might_have'
and 'has_one' relationships have this set by default; if you want a proxy
to update across a 'belongs_to' relationship, you must set the attribute
yourself.

=over 4

=item \@columns

An arrayref containing a list of accessors in the foreign class to create in
the main class. If, for example, you do the following:

  MyApp::Schema::CD->might_have(liner_notes => 'MyApp::Schema::LinerNotes',
    undef, {
      proxy => [ qw/notes/ ],
    });

Then, assuming MyApp::Schema::LinerNotes has an accessor named notes, you can do:

  my $cd = MyApp::Schema::CD->find(1);
  $cd->notes('Notes go here'); # set notes -- LinerNotes object is
                               # created if it doesn't exist

For a 'belongs_to relationship, note the 'cascade_update':

  MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd,
      { proxy => ['title'], cascade_update => 1 }
  );
  $track->title('New Title');
  $track->update; # updates title in CD

=item \%column

A hashref where each key is the accessor you want installed in the main class,
and its value is the name of the original in the foreign class.

  MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd', {
      proxy => { cd_title => 'title' },
  });

This will create an accessor named C<cd_title> on the C<$track> result object.

=back

NOTE: you can pass a nested struct too, for example:

  MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd', {
    proxy => [ 'year', { cd_title => 'title' } ],
  });

=item accessor

Specifies the type of accessor that should be created for the relationship.
Valid values are C<single> (for when there is only a single related object),
C<multi> (when there can be many), and C<filter> (for when there is a single
related object, but you also want the relationship accessor to double as
a column accessor). For C<multi> accessors, an add_to_* method is also
created, which calls C<create_related> for the relationship.

=item is_foreign_key_constraint

If you find that DBIO is creating constraints where it shouldn't, or not
creating them where it should, set this attribute to a true or false value
to override the detection of when to create constraints.

=item cascade_copy

If C<cascade_copy> is true on a C<has_many> relationship for an
object, then when you copy the object all the related objects will
be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
in the C<$attr> hashref.

The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
relationships.

=item cascade_delete

By default, DBIO cascades deletes across C<has_many>,
C<has_one> and C<might_have> relationships. You can disable this
behaviour on a per-relationship basis by supplying
C<< cascade_delete => 0 >> in the relationship attributes.

The cascaded operations are performed after the requested delete,
so if your database has a constraint on the relationship, it will
have deleted/updated the related records or raised an exception
before DBIO gets to perform the cascaded operation.

=item cascade_update

By default, DBIO cascades updates across C<has_one> and
C<might_have> relationships. You can disable this behaviour on a
per-relationship basis by supplying C<< cascade_update => 0 >> in
the relationship attributes.

The C<belongs_to> relationship does not update across relationships
by default, so if you have a 'proxy' attribute on a belongs_to and want to
use 'update' on it, you must set C<< cascade_update => 1 >>.

This is not a RDMS style cascade update - it purely means that when
an object has update called on it, all the related objects also
have update called. It will not change foreign keys automatically -
you must arrange to do this yourself.

=item on_delete / on_update

Use these attributes to explicitly set the desired C<ON DELETE> or
C<ON UPDATE> constraint type. For any 'multi' relationship with
C<< cascade_delete => 1 >>, the corresponding belongs_to relationship
will be created with an C<ON DELETE CASCADE> constraint. For any relationship
bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint will be
C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just use
the RDBMS' default constraint type, pass C<< on_delete => undef >> or
C<< on_delete => '' >>, and the same for C<on_update> respectively.

=item is_deferrable

Indicates that the foreign key constraint should be deferrable. In other
words, the user may request that the constraint be ignored until the end
of the transaction. Currently, only the PostgreSQL producer actually
supports this.

=item add_fk_index

If true, adds an index for this constraint. Can also be specified globally
in the args to L<DBIO::Schema/deploy>. Default is on, set to 0 to disable.

=back

=head2 register_relationship

=over 4

=item Arguments: $rel_name, $rel_info

=back

Registers a relationship on the class. This is called internally by
DBIO::ResultSourceProxy to set up Accessors and Proxies.

=head2 related_resultset

=over 4

=item Arguments: $rel_name

=item Return Value: L<$related_resultset|DBIO::ResultSet>

=back

  $rs = $cd->related_resultset('artist');

Returns a L<DBIO::ResultSet> for the relationship named
$rel_name.

=head2 $relationship_accessor

=over 4

=item Arguments: none

=item Return Value: L<$result|DBIO::Manual::ResultClass> | L<$related_resultset|DBIO::ResultSet> | undef

=back

  # These pairs do the same thing
  $result = $cd->related_resultset('artist')->single;  # has_one relationship
  $result = $cd->artist;
  $rs = $cd->related_resultset('tracks');           # has_many relationship
  $rs = $cd->tracks;