From 1ae09931b2572d9c3067c99f841a60cb3330b3f3 Mon Sep 17 00:00:00 2001
From: wei <>
Date: Thu, 3 May 2007 00:48:04 +0000
Subject: Update active relations docs
---
.../Relations/TActiveRecordBelongsTo.php | 20 ++--
.../Relations/TActiveRecordHasMany.php | 8 +-
.../Relations/TActiveRecordHasManyAssociation.php | 107 ++++++++++++++++++++-
.../ActiveRecord/Relations/TActiveRecordHasOne.php | 14 +--
.../Relations/TActiveRecordRelation.php | 11 +--
.../Relations/TActiveRecordRelationContext.php | 13 ++-
6 files changed, 142 insertions(+), 31 deletions(-)
(limited to 'framework/Data/ActiveRecord/Relations')
diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php b/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php
index c72ba160..1168bf55 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php
@@ -1,6 +1,6 @@
* @link http://www.pradosoft.com/
@@ -16,8 +16,8 @@
Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');
/**
- * Implements the foreign key relationship (TActiveRecord::BELONGS_TO) between
- * the source objects and the related foreign object. Consider the
+ * 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.
*
* +------+ +--------+
@@ -38,17 +38,19 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');
* public $team_name; //foreign key player.team_name <-> team.name
* public $age;
* public $team; //foreign object TeamRecord
- *
- * protected static $RELATIONS = array(
- * 'team' => array(self::BELONGS_TO, 'TeamRecord'));
- *
+ *
+ * protected static $RELATIONS = array
+ * (
+ * 'team' => array(self::BELONGS_TO, 'TeamRecord')
+ * );
+ *
* public static function finder($className=__CLASS__)
* {
* return parent::finder($className);
* }
* }
*
- * The $RELATIONS static property of PlayerRecord defines that the
+ * The static $RELATIONS property of PlayerRecord defines that the
* property $team belongs to (or is a) TeamRecords.
*
* The team object may be fetched as follows.
@@ -58,7 +60,7 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');
* The method with_xxx() (where xxx is the relationship property
* name, in this case, team) fetchs the corresponding TeamRecords using
* a second query (not by using a join). The with_xxx() accepts the same
- * arguments as other finder methods of TActiveRecord, e.g.
+ * arguments as other finder methods of TActiveRecord, e.g.
* with_team('location = ?', 'Madrid').
*
* @author Wei Zhuo
diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php b/framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php
index 795630ab..c5ce616e 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php
@@ -34,8 +34,10 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');
*
* public $players=array(); //list of players
*
- * protected static $RELATIONS=array(
- * 'players' => array(self::HAS_MANY, 'PlayerRecord'));
+ * protected static $RELATIONS=array
+ * (
+ * 'players' => array(self::HAS_MANY, 'PlayerRecord')
+ * );
*
* public static function finder($className=__CLASS__)
* {
@@ -47,7 +49,7 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');
* // see TActiveRecordBelongsTo for detailed definition
* }
*
- * The $RELATIONS static property of TeamRecord defines that the
+ * The static $RELATIONS property of TeamRecord defines that the
* property $players has many PlayerRecords.
*
* The players list may be fetched as follows.
diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php b/framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php
index 456848fe..50558a2b 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php
@@ -1,16 +1,98 @@
+ * @link http://www.pradosoft.com/
+ * @copyright Copyright © 2005-2007 PradoSoft
+ * @license http://www.pradosoft.com/license/
+ * @version $Id$
+ * @package System.Data.ActiveRecord.Relations
+ */
/**
* Loads base active record relations class.
*/
Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');
+/**
+ * Implements the M-N (many to many) relationship via association table.
+ * Consider the entity relationship between Articles and Categories
+ * via the association table Article_Category.
+ *
+ * +---------+ +------------------+ +----------+
+ * | 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.
+ *
+ * protected static $RELATIONS = array
+ * (
+ * 'Categories' => array(self::HAS_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();
+ *
+ * protected static $RELATIONS = array
+ * (
+ * 'Articles' => array(self::HAS_MANY, 'ArticleRecord', 'Article_Category')
+ * );
+ *
+ * public static function finder($className=__CLASS__)
+ * {
+ * return parent::finder($className);
+ * }
+ * }
+ *
+ *
+ * The static $RELATIONS property of ArticleRecord defines that the
+ * property $Categories has many CategoryRecords. Similar, the
+ * static $RELATIONS property of CategoryRecord defines many ArticleRecords.
+ *
+ * The articles with categories list may be fetched as follows.
+ *
+ * $articles = TeamRecord::finder()->withCategories()->findAll();
+ *
+ * The method with_xxx() (where xxx is the relationship property
+ * name, in this case, Categories) fetchs the corresponding CategoryRecords using
+ * a second query (not by using a join). The with_xxx() accepts the same
+ * arguments as other finder methods of TActiveRecord.
+ *
+ * @author Wei Zhuo
+ * @version $Id$
+ * @package System.Data.ActiveRecord.Relations
+ * @since 3.1
+ */
class TActiveRecordHasManyAssociation extends TActiveRecordRelation
{
private $_association;
private $_sourceTable;
private $_foreignTable;
+ /**
+ * Get the foreign key index values from the results and make calls to the
+ * database to find the corresponding foreign objects using association table.
+ * @param array original results.
+ */
protected function collectForeignObjects(&$results)
{
$association = $this->getAssociationTable();
@@ -26,6 +108,9 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation
$this->fetchForeignObjects($results, $foreignKeys,$indexValues,$sourceKeys);
}
+ /**
+ * @return TDbTableInfo association table information.
+ */
protected function getAssociationTable()
{
if($this->_association===null)
@@ -38,6 +123,9 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation
return $this->_association;
}
+ /**
+ * @return TDbTableInfo source table information.
+ */
protected function getSourceTable()
{
if($this->_sourceTable===null)
@@ -48,6 +136,9 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation
return $this->_sourceTable;
}
+ /**
+ * @return TDbTableInfo foreign table information.
+ */
protected function getForeignTable()
{
if($this->_foreignTable===null)
@@ -59,6 +150,9 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation
return $this->_foreignTable;
}
+ /**
+ * @return TDbCommandBuilder
+ */
protected function getCommandBuilder()
{
return $this->getSourceRecord()->getRecordGateway()->getCommand($this->getSourceRecord());
@@ -117,6 +211,10 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation
return $command;
}
+ /**
+ * @param array source table column names.
+ * @return string comma separated source column names.
+ */
protected function getSourceColumns($sourceKeys)
{
$columns=array();
@@ -127,6 +225,13 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation
return implode(', ', $columns);
}
+ /**
+ * SQL inner join for M-N relationship via association table.
+ * @param array foreign table column key names.
+ * @param array source table index values.
+ * @param array source table column names.
+ * @return string inner join condition for M-N relationship via association table.
+ */
protected function getAssociationJoin($foreignKeys,$indexValues,$sourceKeys)
{
$refInfo= $this->getAssociationTable();
@@ -143,9 +248,7 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation
$joins[] = "{$fkTable}.{$fkField} = {$refTable}.{$refField}";
}
$joinCondition = implode(' AND ', $joins);
-
$index = $this->getCommandBuilder()->getIndexKeyCondition($refInfo,array_keys($sourceKeys), $indexValues);
-
return "INNER JOIN {$refTable} ON ({$joinCondition}) AND {$index}";
}
}
diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php b/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php
index 4286254b..6348f16b 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php
@@ -21,7 +21,7 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');
* 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.
+ * 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.
*
@@ -32,7 +32,7 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');
* +-----+ +--------+
*
* 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
+ * 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
@@ -43,8 +43,10 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');
*
* public $engine; //engine foreign object
*
- * protected static $RELATIONS=array(
- * 'engine' => array(self::HAS_ONE, 'EngineRecord'));
+ * protected static $RELATIONS=array
+ * (
+ * 'engine' => array(self::HAS_ONE, 'EngineRecord')
+ * );
*
* public static function finder($className=__CLASS__)
* {
@@ -57,14 +59,14 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');
* public $engine_id;
* public $capacity;
* public $car_id; //foreign key to cars
- *
+ *
* public static function finder($className=__CLASS__)
* {
* return parent::finder($className);
* }
* }
*
- * The $RELATIONS static property of CarRecord defines that the
+ * 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.
diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php b/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php
index 38455309..46609095 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php
@@ -18,8 +18,6 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelationContext');
/**
* Base class for active record relationships.
*
- * description
- *
* @author Wei Zhuo
* @version $Id$
* @package System.Data.ActiveRecord.Relations
@@ -66,7 +64,7 @@ abstract class TActiveRecordRelation
static $stack=array();
$results = call_user_func_array(array($this->getSourceRecord(),$method),$args);
- if(is_array($results) || $results instanceof TActiveRecord)
+ if(is_array($results) || $results instanceof ArrayAccess || $results instanceof TActiveRecord)
{
$this->collectForeignObjects($results);
while($obj = array_pop($stack))
@@ -134,8 +132,9 @@ abstract class TActiveRecordRelation
*/
protected function getIndexValues($keys, $results)
{
- if(!is_array($results))
+ if(!is_array($results) && !$results instanceof ArrayAccess)
$results = array($results);
+ $values=array();
foreach($results as $result)
{
$value = array();
@@ -169,7 +168,7 @@ abstract class TActiveRecordRelation
*/
protected function setResultCollection(&$results, &$collections, $properties)
{
- if(is_array($results))
+ if(is_array($results) || $results instanceof ArrayAccess)
{
for($i=0,$k=count($results);$i<$k;$i++)
$this->setObjectProperty($results[$i], $properties, $collections);
@@ -191,5 +190,5 @@ abstract class TActiveRecordRelation
$source->{$prop} = isset($collections[$hash]) ? $collections[$hash] : array();
}
}
-
+
?>
\ No newline at end of file
diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php b/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php
index 033d7638..167c90a5 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php
@@ -57,11 +57,14 @@ class TActiveRecordRelationContext
if(!isset($statics[self::RELATIONS_CONST]))
throw new TActiveRecordException('ar_relations_undefined',
get_class($this->_sourceRecord), self::RELATIONS_CONST);
- if(isset($statics[self::RELATIONS_CONST][$property]))
- return $statics[self::RELATIONS_CONST][$property];
- else
- throw new TActiveRecordException('ar_undefined_relation_prop',
- $property, get_class($this->_sourceRecord), self::RELATIONS_CONST);
+ $property = strtolower($property);
+ foreach($statics[self::RELATIONS_CONST] as $name => $relation)
+ {
+ if(strtolower($name)===$property)
+ return $relation;
+ }
+ throw new TActiveRecordException('ar_undefined_relation_prop',
+ $property, get_class($this->_sourceRecord), self::RELATIONS_CONST);
}
/**
--
cgit v1.2.3