## Class TActiveRecordBelongsTo

Description

Implements the foreign key relationship (TActiveRecord::BELONGS_TO) between the source objects and the related foreign object. Consider the entity relationship between a Team and a Player.

     +------+            +--------+
     | Team | 1 <----- * | Player |
     +------+            +--------+

Where one team may have 0 or more players and each player belongs to only one team. We may model Team-Player object relationship as active record as follows.

     class TeamRecord extends TActiveRecord
     {
         // see TActiveRecordHasMany for detailed definition.
      }
     class PlayerRecord extends TActiveRecord
     {
         const TABLE='player';
         public $player_id; //primary key
              public $team_name; //foreign key player.team_name <-> team.name
                    public $age;
         public $team; //foreign object TeamRecord

         public static $RELATIONS = array
         (
                'team' => array(self::BELONGS_TO, 'TeamRecord')
         );

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

The static <tt>$RELATIONS</tt> property of PlayerRecord defines that the property <tt>$team</tt> belongs to a <tt>TeamRecord</tt>.

The team object may be fetched as follows.

     $players = PlayerRecord::finder()->with_team()->findAll();

The method <tt>with_xxx()</tt> (where <tt>xxx</tt> is the relationship property name, in this case, <tt>team</tt>) fetchs the corresponding TeamRecords using a second query (not by using a join). The <tt>with_xxx()</tt> accepts the same arguments as other finder methods of TActiveRecord, e.g. <tt>with_team('location = ?', 'Madrid')</tt>.

- since: 3.1
- version: $Id$
- author: Wei Zhuo <weizho[at]gmail[dot]com>

Located in /Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php (line 71)

    TActiveRecordRelation
       |
       --TActiveRecordBelongsTo

Method Summary
void collectForeignObjects (array &$results)
array getRelationForeignKeys ()
void setObjectProperty (TActiveRecord $source, array $properties, mixed &$collections)
boolean updateAssociatedRecords ()
Methods
collectForeignObjects (line 78)

Get the foreign key index values from the results and make calls to the database to find the corresponding foreign objects.

- access: protected

void collectForeignObjects (array &$results)

- array &$results: original results.

Redefinition of:

TActiveRecordRelation::collectForeignObjects()

getRelationForeignKeys (line 93)

- return: foreign key field names as key and object properties as value.
- access: public
- since: 3.1.2

array getRelationForeignKeys ()

Redefinition of:

TActiveRecordRelation::getRelationForeignKeys()

setObjectProperty (line 104)

Sets the foreign objects to the given property on the source object.

- access: protected

void setObjectProperty (TActiveRecord $source, array $properties, mixed &$collections)

- TActiveRecord $source: source object.
- array $properties: foreign objects.

Redefinition of:

TActiveRecordRelation::setObjectProperty()
  Sets the foreign objects to the given property on the source object.

updateAssociatedRecords (line 122)

Updates the source object first.

- return: true if all update are success (including if no update was required), false otherwise .
- access: public

boolean updateAssociatedRecords ()

#### Inherited Methods

Inherited From TActiveRecordRelation

> TActiveRecordRelation::__construct()
> TActiveRecordRelation::collectForeignObjects()
> TActiveRecordRelation::fetchResultsInto()
> TActiveRecordRelation::findForeignKeys()
> TActiveRecordRelation::findForeignObjects()
> TActiveRecordRelation::getContext()
> TActiveRecordRelation::getCriteria()
> TActiveRecordRelation::getIndexValues()
> TActiveRecordRelation::getObjectHash()
> TActiveRecordRelation::getRelationForeignKeys()
> TActiveRecordRelation::getSourceRecord()
> TActiveRecordRelation::populateResult()
> TActiveRecordRelation::setObjectProperty()
> TActiveRecordRelation::setResultCollection()
> TActiveRecordRelation::__call()

Documentation generated on Mon, 22 Feb 2010 12:16:31 +0000 by phpDocumentor 1.3.0RC4