## Class TActiveRecordHasManyAssociation

Description

Implements the M-N (many to many) relationship via association table.

Consider the entity relationship between Articles and Categories via the association table <tt>Article_Category</tt>.

     +---------+            +------------------+            +----------+
     | Article | * -----> * | Article_Category | * <----- * | Category |
     +---------+            +------------------+            +----------+

Where one article may have 0 or more categories and each category may have 0 or more articles. We may model Article-Category object relationship as active record as follows.

     class ArticleRecord
     {
         const TABLE='Article';
         public $article_id;

         public $Categories=array(); //foreign object collection.

         public static $RELATIONS = array
         (
             'Categories' => array(self::MANY_TO_MANY, 'CategoryRecord', 'Article_Category')
         );

         public static function finder($className=__CLASS__)
         {
             return parent::finder($className);
         }
     }
     class CategoryRecord
     {
         const TABLE='Category';
         public $category_id;

         public $Articles=array();

         public static $RELATIONS = array
         (
             'Articles' => array(self::MANY_TO_MANY, 'ArticleRecord', 'Article_Category')
         );

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

The static <tt>$RELATIONS</tt> property of ArticleRecord defines that the property <tt>$Categories</tt> has many <tt>CategoryRecord</tt>s. Similar, the static <tt>$RELATIONS</tt> property of CategoryRecord defines many ArticleRecords.

The articles with categories list may be fetched as follows.

     $articles = TeamRecord::finder()->withCategories()->findAll();

The method <tt>with_xxx()</tt> (where <tt>xxx</tt> is the relationship property name, in this case, <tt>Categories</tt>) fetchs the corresponding CategoryRecords using a second query (not by using a join). The <tt>with_xxx()</tt> accepts the same arguments as other finder methods of TActiveRecord.

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

Located in /Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php (line 85)

    TActiveRecordRelation
       |
       --TActiveRecordHasManyAssociation

Method Summary
void collectForeignObjects (array &$results)
void createCommand (TSqlCriteria $criteria, TTableInfo $foreignKeys, array $indexValues, array $sourceKeys)
TActiveRecord createFkObject (string $type, array $row, array $foreignKeys)
void fetchForeignObjects (array &$results, array $foreignKeys, mixed $indexValues, mixed $sourceKeys)
string getAssociationJoin (array $foreignKeys, array $indexValues, array $sourceKeys)
TDbTableInfo getAssociationTable ()
TDbCommandBuilder getAssociationTableCommandBuilder ()
TDataGatewayCommand getCommandBuilder ()
TDataGatewayCommand getForeignCommandBuilder ()
TDbTableInfo getForeignTable ()
array getRelationForeignKeys ()
string getSourceColumns (array $sourceKeys)
TDbTableInfo getSourceTable ()
boolean updateAssociatedRecords ()
Methods
collectForeignObjects (line 97)

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

- access: protected

void collectForeignObjects (array &$results)

- array &$results: original results.

Redefinition of:

TActiveRecordRelation::collectForeignObjects()

createCommand (line 231)

- access: public

void createCommand (TSqlCriteria $criteria, TTableInfo $foreignKeys, array $indexValues, array $sourceKeys)

- TSqlCriteria $criteria
- TTableInfo $foreignKeys: association table info
- array $indexValues: field names
- array $sourceKeys: field values

createFkObject (line 213)

- access: protected

TActiveRecord createFkObject (string $type, array $row, array $foreignKeys)

- string $type: active record class name.
- array $row: row data
- array $foreignKeys: foreign key column names

fetchForeignObjects (line 188)

Fetches the foreign objects using TActiveRecord::findAllByIndex()

- access: protected

void fetchForeignObjects (array &$results, array $foreignKeys, mixed $indexValues, mixed $sourceKeys)

- array &$results: field names
- array $foreignKeys: foreign key index values.

getAssociationJoin (line 273)

SQL inner join for M-N relationship via association table.

- return: inner join condition for M-N relationship via association table.
- access: protected

string getAssociationJoin (array $foreignKeys, array $indexValues, array $sourceKeys)

- array $foreignKeys: foreign table column key names.
- array $indexValues: source table index values.
- array $sourceKeys: source table column names.

getAssociationTable (line 120)

- return: association table information.
- access: protected

TDbTableInfo getAssociationTable ()
getAssociationTableCommandBuilder (line 321)

- access: protected

TDbCommandBuilder getAssociationTableCommandBuilder ()
getCommandBuilder (line 168)

- access: protected

TDataGatewayCommand getCommandBuilder ()
getForeignCommandBuilder (line 176)

- access: protected

TDataGatewayCommand getForeignCommandBuilder ()
getForeignTable (line 154)

- return: foreign table information.
- access: protected

TDbTableInfo getForeignTable ()
getRelationForeignKeys (line 108)

- return: 2 arrays of source keys and foreign keys from the association table.
- access: public

array getRelationForeignKeys ()

Redefinition of:

TActiveRecordRelation::getRelationForeignKeys()

getSourceColumns (line 255)

- return: comma separated source column names.
- access: protected

string getSourceColumns (array $sourceKeys)

- array $sourceKeys: source table column names.

getSourceTable (line 141)

- return: source table information.
- access: protected

TDbTableInfo getSourceTable ()
updateAssociatedRecords (line 302)

Updates the associated foreign objects.

- 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 Sun, 11 Jan 2009 20:15:54 -0500 by phpDocumentor 1.3.0RC4