Class \Prado\Data\ActiveRecord\Relations\TActiveRecordHasOne

TActiveRecordHasOne models the object relationship that a record (the source object) property is an instance of foreign record object having a foreign key related to the source object. The HAS_ONE relation is very similar to the HAS_MANY relationship (in fact, it is equivalent in the entities relationship point of view).

The difference of HAS_ONE from HAS_MANY is that the foreign object is singular. That is, HAS_MANY will return a collection of records while HAS_ONE returns the corresponding record.

Consider the entity relationship between a Car and a Engine.

+-----+            +--------+
| Car | 1 <----- 1 | Engine |
+-----+            +--------+

Where each engine belongs to only one car, that is, the Engine entity has a foreign key to the Car's primary key. We may model Engine-Car object relationship as active record as follows.

class CarRecord extends TActiveRecord
{
    const TABLE='car';
    public $car_id; //primary key
    public $colour;

    public $engine; //engine foreign object

    public static $RELATIONS=array
    (
        'engine' => array(self::HAS_ONE, 'EngineRecord')
    );

   public static function finder($className=__CLASS__)
   {
	   return parent::finder($className);
   }
}
class EngineRecord extends TActiveRecord
{
    const TABLE='engine';
    public $engine_id;
    public $capacity;
    public $car_id; //foreign key to cars

   public static function finder($className=__CLASS__)
   {
	   return parent::finder($className);
   }
}

The static $RELATIONS property of CarRecord defines that the property $engine that will reference an EngineRecord instance.

The car record with engine property list may be fetched as follows.

$cars = CarRecord::finder()->with_engine()->findAll();

The method with_xxx() (where xxx is the relationship property name, in this case, engine) fetchs the corresponding EngineRecords using a second query (not by using a join). The with_xxx() accepts the same arguments as other finder methods of TActiveRecord, e.g. with_engine('capacity < ?', 3.8).

Class hierarchy

\Prado\Data\ActiveRecord\Relations\TActiveRecordHasOne

\Prado\Data\ActiveRecord\Relations\TActiveRecordRelation

Author: Wei Zhuo <weizho[at]gmail[dot]com>
Since: 3.1

Methods summary
`public`	`getRelationForeignKeys() : array<string\|int, mixed>`
`public`	`updateAssociatedRecords() : bool` Updates the associated foreign objects.
`protected`	`collectForeignObjects(array<string\|int, mixed> &$results) : mixed` Get the foreign key index values from the results and make calls to the database to find the corresponding foreign objects.
`protected`	`setObjectProperty(TActiveRecord $source, array<string\|int, mixed> $properties, array<string\|int, mixed> &$collections) : mixed` Sets the foreign objects to the given property on the source object.

Inherited methods
`__call, __construct, fetchResultsInto, getRelationForeignKeys, updateAssociatedRecords, collectForeignObjects, findForeignKeys, findForeignObjects, getContext, getCriteria, getIndexValues, getObjectHash, getSourceRecord, populateResult, setObjectProperty, setResultCollection, getFkFields`