NAME

Class::ReluctantORM::Relationship::HasMany

SYNOPSIS

  # Add relationships to a ReluctantORM Class
  Ship->has_many('Pirate');
  Ship->has_many(
                 class       => 'Pirate'
                 local_key   => 'ship_id', # New in 0.4: multi-column keys allowed via
                 remote_key  => 'ship_id', # arrayrefs here!
                 method_name => 'pirates',
                );

  # Now you have:
  $pirates_collection  = $ship->pirates();

  # New in 0.4: in array context, implicitly do $pirates_collection->all_items
  @mateys = $ship->pirates();

  # Fetchers defined automatically
  $ship      = Ship->fetch_with_pirates($ship_id);
  @unarmed   = Ship->fetch_by_gun_count_with_pirates(0);

  # Get info about the relationship
  $rel = Ship->relationships('pirates');

  $str = $rel->type();                 # 'has_many';
  $str = $rel->linked_class();         # 'Pirate';
  $str = $rel->linking_class();        # 'Ship';
  @fields = $rel->local_key_fields();  # fields in Ship that link to Pirate
  @fields = $rel->remote_key_fields(); # fields in Pirate that link to Ship
  $int = $rel->join_depth();           # 1

  # Class::ReluctantORM::SQL integration
  @sql_cols = $rel->additional_output_sql_columns();
  @cols     = $rel->local_key_sql_columns();
  @cols     = $rel->remote_key_sql_columns();
  @empty    = $rel->join_local_key_sql_columns();  # always empty for HasMany
  @empty    = $rel->join_remote_key_sql_columns(); # always empty for HasMany

DESCRIPTION

CREATING A RELATIONSHIP

$tb_class->has_many('OtherClass');

$tb_class->has_many(class => 'OtherClass', local_key => 'key_column', remote_key => 'key_column', method_name => 'other_class');

$tb_class->has_many(... join_table => 'table_name' ...);

join_table => 'table_name', join_table_schema => 'schema_name',

Initiates a one-to-many relationship between two classes/tables. Results are handled with assistance of a simple container class, Class::ReluctantORM::Collection.

An accessor will be created named other_classes (or method_name). Note that this should be plural for readability. The accessor will return a Collection object.

Additionally, a new constructor is created, named $class->fetch_with_METHOD. This constructor has the special feature that it performs an outer join and prepopulates the Collection. Thus, Ship->fetch_with_pirates(23) is only one DB query.

Finally, additional constructors named $class->fetch_by_ATTRIBUTE_with_METHOD will also be available via AUTOLOAD.

Obtaining the Collection object does NOT result in trips to the database. Operations on the Collection object DO require trips to the database.

Note that a one-to-many relationship does not imply a reciprocal has_one relationship going the other way. It's OK to set that up manually, though.

In the first form, a relationship is setup to OtherClass using defaults, described below.

In the second form, options are made explicit:

class (required)

The linked class. This is the class on the remote end of the one-to-many. That means it will have foreign key(s) to the local (linking) class.

method_name

The name of the method that will be used to access the relationship. This is also the name for the relationship, which you can pass to $tb_class->relationships. Default is the lower-cased and pluralized OtherClass. For example, if you say Ship->has_many('Pirate'), you'll get $ship->pirates(). Pluralization is performed using Lingua.

local_key (optional string or arrayref)

Name or names of columns on the local table acting as keys in the relationship. Defaults to $tb_class->primary_key_columns().

remote_key (optional string or arrayref)

Name or names of columns on the remote table acting as keys in the relationship. Defaults to looking for columns in OtherClass with the names $tb_class->primary_key_columns().

foreign_key

Deprecated synonym for remote_key.

In the third form, all arguments will be passed to Class::ReluctantORM::Relationshipo::HasManyMany. This form is somewhat discouraged, but remains because some find it more readable.

$str = $rel->type();

Returns 'has_many'.

$int = $rel->join_depth();

Returns 1.

$str = $rel->join_type();

Returns 'LEFT OUTER'

$int = $rel->lower_multiplicity()

Returns 0.

$int = $rel->upper_multiplicity()

Returns undef.

$bool = $rel->is_has_many();

Returns true.

$bool = $rel->is_populated_in_object($cro_obj);

Returns true if the CRO object has had this relationship fetched.

cpanm Class::ReluctantORM

perl -MCPAN -e shell
install Class::ReluctantORM