Defining and using one-to-many associations

A type of record is marked with a one-to-many association if one of its property define a "belongs_to" property in the "meta_field" array.

Faculatively, one the other side of the relation, it is also possible to define a property with an "has_many" key and get more methods.

Methods available with the "belongs_to" property

Method set{AssocRecordType}
Associate an associated record with the current record. It either accept a new record, a saved record or the primary key value of a saved record.
Calling the save method on the current record will also save the provided associated record.
- param PorteRecord || int || string: The associated record or its primary key value
- return PorteRecord: The current record
Method get{AssocRecordType}
Retrieve the associated record. If the current record has no associated record, the method return "null". The method does not take any argument.
- return PorteRecord || null: The associated record or null if no associated record
Method delete{AssocRecordType}
Break the association between the associated record and the current record. If no associated record exists, the method does nothing. The method does not take any argument. Note, calling this method will not remove the associated record from the database but only break its association.
- return PorteRecord: The current record

Methods available with the "has_many" property

Method add{AssocRecordType}
Add an associated record to the current record. It either accept a new record, a saved record or the primary key value of a saved record.
Calling the save method on the current record will also save the provided associated record.
- param PorteRecord || int || string: The associated record or its primary key value
- return PorteRecord: The current record
Method set{AssocRecordType}
Method set{AssocRecordTypes}
Method delete{AssocRecordType}
Method delete{AssocRecordTypes}
Method count{AssocRecordTypes}

Quick exemple

Let's consider two types of records: files and file formats. Each record of type "File" may be given one and only one "Format" (being ".gif", ".txt", ".php", ...).

The key while defining this sort of relationship is the proper usage of the "belongs_to" keyword.

In our exemple, a file belongs to a type of format, meaning a new property in "File" shall be defined with the property "belongs_to".

Using optional Porte naming conventions, an array identified by the key "format" will be added to the "meta_fields" array of the File objects, and its value will be an array containing the key "belongs_to" set to true.

In such a case, Porte will automatically look for a class "Format" and hook up each new file objects with a new set of methods to access/define/modify their associated format.

Moreover, format objects may also recieve a new set of methods. To achieve this, using optional Porte naming conventions, an array identified by the key "files" (notice the plurality) will be added to the "meta_fields" array of the Format objects.

Using the belongs_to property


class File extends PorteRecord{
  $meta_fields = array(
    'format' => array( 'belongs_to' )
  );
}

class Format extends PorteRecord{
  $meta_fields = array(
    'files' => array( 'has_many' )
  );
}

$file = new File();
$format = new Format();
$file->setFormat($format);
$file->save();

Setting up the "belongs_to" property

The following keys may be used:

Key "field": Define the database field storing the primary key of the associated record, default to the property name.
Key "belongs_to": An array defining various internal properties. Also, it may be a value, or its value may be a boolean, as string or an array. If the value is a string, it correspond to the "type" of the associated record.
- Key "type": Define the type of the associated record
- Key "class": Define the class of the associated record, used as an alternative to define the "type" of records if not set
- Key "property": Define the name of the property defining the "belongs_to" association, default to current plural record type.

Once a property is clean up by its model, the resulting config is:

Key "belongs_to": always an array
- Key "type"
- Key "property"
Key "field"
Key "type"
Key "foreign_key": Boolean value set to true

Setting up the "has_many" property