view release on metacpan or  search on metacpan

lib/DBIx/Class/Relationship.pm  view on Meta::CPAN

The column name on this class that contains the foreign key.

OR

=item cond

A hashref, arrayref or coderef specifying a custom join expression. For
more info see L<DBIx::Class::Relationship::Base/condition>.

=back

  # in a Book class (where Author has many Books)
  My::DBIC::Schema::Book->belongs_to(
    author =>
    'My::DBIC::Schema::Author',
    'author_id'
  );

  # OR (same result)
  My::DBIC::Schema::Book->belongs_to(
    author =>
    'My::DBIC::Schema::Author',
    { 'foreign.author_id' => 'self.author_id' }
  );

  # OR (similar result but uglier accessor name)
  My::DBIC::Schema::Book->belongs_to(
    author_id =>
    'My::DBIC::Schema::Author'
  );

  # Usage
  my $author_obj = $book->author; # get author object
  $book->author( $new_author_obj ); # set author object
  $book->author_id(); # get the plain id

  # To retrieve the plain id if you used the ugly version:
  $book->get_column('author_id');

If some of the foreign key columns are
L<nullable|DBIx::Class::ResultSource/is_nullable> you probably want to set
the L<join_type|DBIx::Class::Relationship::Base/join_type> attribute to
C<left> explicitly so that SQL expressing this relation is composed with
a C<LEFT JOIN> (as opposed to C<INNER JOIN> which is default for
L</belongs_to> relationships). This ensures that relationship traversal
works consistently in all situations. (i.e. resultsets involving
L<join|DBIx::Class::ResultSet/join> or
L<prefetch|DBIx::Class::ResultSet/prefetch>).
The modified declaration is shown below:

  # in a Book class (where Author has_many Books)
  __PACKAGE__->belongs_to(
    author =>
    'My::DBIC::Schema::Author',
    'author',
    { join_type => 'left' }
  );

Cascading deletes are off by default on a C<belongs_to>
relationship. To turn them on, pass C<< cascade_delete => 1 >>
in the $attr hashref.

By default, DBIC will return undef and avoid querying the database if a
C<belongs_to> accessor is called when any part of the foreign key IS NULL. To
disable this behavior, pass C<< undef_on_null_fk => 0 >> in the C<\%attrs>
hashref.

NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
of C<has_a>.

See L<DBIx::Class::Relationship::Base/attributes> for documentation on relationship
methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet>
for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES>
which can be assigned to relationships as well.

=head2 has_many

=over 4

=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>

=back

Creates a one-to-many relationship where the foreign class refers to
this class's primary key. This relationship refers to zero or more
records in the foreign table (e.g. a C<LEFT JOIN>). This relationship
defaults to using the end of this classes namespace as the foreign key
in C<$related_class> to resolve the join, unless C<$their_fk_column>
specifies the foreign key column in C<$related_class> or C<cond>
specifies a reference to a join condition.

=over

=item accessor_name

This argument is the name of the method you can call on a
L<Result|DBIx::Class::Manual::ResultClass> object to retrieve a resultset of the related
class restricted to the ones related to the result object. In list
context it returns the result objects. This is often called the
C<relation(ship) name>.

Use this accessor_name in L<DBIx::Class::ResultSet/join>
or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
indicated by this relationship.

=item related_class

This is the class name of the table which contains a foreign key
column containing PK values of this class.

=item their_fk_column

The column name on the related class that contains the foreign key.

OR

=item cond

A hashref, arrayref  or coderef specifying a custom join expression. For
more info see L<DBIx::Class::Relationship::Base/condition>.

lib/DBIx/Class/Relationship.pm  view on Meta::CPAN

=back

  # in an Author class (where Author has_many Books)
  # assuming related class is storing our PK in "author_id"
  My::DBIC::Schema::Author->has_many(
    books =>
    'My::DBIC::Schema::Book',
    'author_id'
  );

  # OR (same result)
  My::DBIC::Schema::Author->has_many(
    books =>
    'My::DBIC::Schema::Book',
    { 'foreign.author_id' => 'self.id' },
  );

  # OR (similar result, assuming related_class is storing our PK, in "author")
  # (the "author" is guessed at from "Author" in the class namespace)
  My::DBIC::Schema::Author->has_many(
    books =>
    'My::DBIC::Schema::Book',
  );


  # Usage
  # resultset of Books belonging to author
  my $booklist = $author->books;

  # resultset of Books belonging to author, restricted by author name
  my $booklist = $author->books({
    name => { LIKE => '%macaroni%' },
    { prefetch => [qw/book/],
  });

  # array of Book objects belonging to author
  my @book_objs = $author->books;

  # force resultset even in list context
  my $books_rs = $author->books;
  ( $books_rs ) = $obj->books_rs;

  # create a new book for this author, the relation fields are auto-filled
  $author->create_related('books', \%col_data);
  # alternative method for the above
  $author->add_to_books(\%col_data);


Three methods are created when you create a has_many relationship.
The first method is the expected accessor method, C<$accessor_name()>.
The second is almost exactly the same as the accessor method but "_rs"
is added to the end of the method name, eg C<$accessor_name_rs()>.
This method works just like the normal accessor, except that it always
returns a resultset, even in list context. The third method, named C<<
add_to_$rel_name >>, will also be added to your Row items; this allows
you to insert new related items, using the same mechanism as in
L<DBIx::Class::Relationship::Base/"create_related">.

If you delete an object in a class with a C<has_many> relationship, all
the related objects will be deleted as well.  To turn this behaviour off,
pass C<< cascade_delete => 0 >> in the C<$attr> hashref.

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

If you copy an object in a class with a C<has_many> relationship, all
the related objects will be copied as well. To turn this behaviour off,
pass C<< cascade_copy => 0 >> in the C<$attr> hashref. The behaviour
defaults to C<< cascade_copy => 1 >>.

See L<DBIx::Class::Relationship::Base/attributes> for documentation on
relationship methods and valid relationship attributes. Also see
L<DBIx::Class::ResultSet> for a L<list of standard resultset
attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to
relationships as well.

=head2 might_have

=over 4

=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>

=back

Creates an optional one-to-one relationship with a class. This relationship
defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
resolve the join, unless C<$their_fk_column> specifies the foreign key
column in C<$related_class> or C<cond> specifies a reference to a join
condition.

=over

=item accessor_name

This argument is the name of the method you can call on a
L<Result|DBIx::Class::Manual::ResultClass> object to retrieve the instance of the foreign
class matching this relationship. This is often called the
C<relation(ship) name>.

Use this accessor_name in L<DBIx::Class::ResultSet/join>
or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
indicated by this relationship.

=item related_class

This is the class name of the table which contains a foreign key
column containing PK values of this class.

=item their_fk_column

The column name on the related class that contains the foreign key.

OR

=item cond

A hashref, arrayref  or coderef specifying a custom join expression. For
more info see L<DBIx::Class::Relationship::Base/condition>.

=back

  # Author may have an entry in the pseudonym table
  My::DBIC::Schema::Author->might_have(
    pseudonym =>
    'My::DBIC::Schema::Pseudonym',
    'author_id',
  );

  # OR (same result, assuming the related_class stores our PK)
  My::DBIC::Schema::Author->might_have(
    pseudonym =>
    'My::DBIC::Schema::Pseudonym',
  );

  # OR (same result)
  My::DBIC::Schema::Author->might_have(
    pseudonym =>
    'My::DBIC::Schema::Pseudonym',
    { 'foreign.author_id' => 'self.id' },
  );

  # Usage
  my $pname = $author->pseudonym; # to get the Pseudonym object

If you update or delete an object in a class with a C<might_have>
relationship, the related object will be updated or deleted as well. To
turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr>
hashref.

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

See L<DBIx::Class::Relationship::Base/attributes> for documentation on
relationship methods and valid relationship attributes. Also see
L<DBIx::Class::ResultSet> for a L<list of standard resultset
attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to
relationships as well.

Note that if you supply a condition on which to join, and the column in the
current table allows nulls (i.e., has the C<is_nullable> attribute set to a
true value), than C<might_have> will warn about this because it's naughty and
you shouldn't do that. The warning will look something like:

  "might_have/has_one" must not be on columns with is_nullable set to true (MySchema::SomeClass/key)

If you must be naughty, you can suppress the warning by setting
C<DBIC_DONT_VALIDATE_RELS> environment variable to a true value.  Otherwise,
you probably just meant to use C<DBIx::Class::Relationship/belongs_to>.

=head2 has_one

=over 4

=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>

=back

Creates a one-to-one relationship with a class. This relationship
defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
resolve the join, unless C<$their_fk_column> specifies the foreign key
column in C<$related_class> or C<cond> specifies a reference to a join
condition.

=over

=item accessor_name

This argument is the name of the method you can call on a
L<Result|DBIx::Class::Manual::ResultClass> object to retrieve the instance of the foreign
class matching this relationship. This is often called the
C<relation(ship) name>.

Use this accessor_name in L<DBIx::Class::ResultSet/join>
or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
indicated by this relationship.

=item related_class

This is the class name of the table which contains a foreign key
column containing PK values of this class.

=item their_fk_column

The column name on the related class that contains the foreign key.

OR

=item cond

A hashref, arrayref  or coderef specifying a custom join expression. For
more info see L<DBIx::Class::Relationship::Base/condition>.