From ea0601cdd4a732fc15b83104a47788989bb004b3 Mon Sep 17 00:00:00 2001 From: wei <> Date: Mon, 30 Apr 2007 03:44:49 +0000 Subject: Reverted TActiveRecord::populateObject to protected --- .../Relations/TActiveRecordBelongsTo.php | 68 +++++++++++++++++++++- .../Relations/TActiveRecordHasMany.php | 16 ++--- .../ActiveRecord/Relations/TActiveRecordHasOne.php | 31 +++++++++- .../Relations/TActiveRecordRelation.php | 47 +++++++++++---- .../Relations/TActiveRecordRelationContext.php | 60 +++++++++++++++++++ 5 files changed, 194 insertions(+), 28 deletions(-) (limited to 'framework/Data/ActiveRecord/Relations') diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php b/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php index 3bb1a74b..c72ba160 100644 --- a/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php +++ b/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php @@ -1,7 +1,71 @@ - + * @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 relationship class. + */ 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 + * 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 + * + * 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 + * property $team belongs to (or is a) TeamRecords. + * + * The team object may be fetched as follows. + * + * $players = PlayerRecord::finder()->with_team()->findAll(); + * + * 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. + * with_team('location = ?', 'Madrid'). + * + * @author Wei Zhuo + * @version $Id$ + * @package System.Data.ActiveRecord.Relations + * @since 3.1 + */ class TActiveRecordBelongsTo extends TActiveRecordRelation { /** @@ -39,5 +103,5 @@ class TActiveRecordBelongsTo extends TActiveRecordRelation } } } - + ?> \ No newline at end of file diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php b/framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php index 27ffd194..795630ab 100644 --- a/framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php +++ b/framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php @@ -17,14 +17,14 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation'); /** * Implements TActiveRecord::HAS_MANY relationship between the source object having zero or - * more foreign objects. Consider the relationship between a Team and a Player. + * more foreign objects. Consider the entity relationship between a Team and a Player. * * +------+ +--------+ - * | Team | 1 -----> * | 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 relationship as active record as follows. + * one team. We may model Team-Player object relationship as active record as follows. * * class TeamRecord extends TActiveRecord * { @@ -44,15 +44,7 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation'); * } * 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 static function finder($className=__CLASS__) - * { - * return parent::finder($className); - * } + * // see TActiveRecordBelongsTo for detailed definition * } * * The $RELATIONS static property of TeamRecord defines that the diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php b/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php index 048f776b..e8c2ccee 100644 --- a/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php +++ b/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php @@ -1,6 +1,33 @@ - + * @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 relationship class. + */ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation'); +/** + * 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. + * + * + * + * + * @author Wei Zhuo + * @version $Id$ + * @package System.Data.ActiveRecord.Relations + * @since 3.1 + */ class TActiveRecordHasOne extends TActiveRecordRelation { /** @@ -38,5 +65,5 @@ class TActiveRecordHasOne extends TActiveRecordRelation } } } - + ?> \ No newline at end of file diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php b/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php index f1e8fa60..38455309 100644 --- a/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php +++ b/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php @@ -1,6 +1,30 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005-2007 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Id$ + * @package System.Data.ActiveRecord.Relations + */ + +/** + * Load active record relationship context. + */ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelationContext'); +/** + * Base class for active record relationships. + * + * description + * + * @author Wei Zhuo + * @version $Id$ + * @package System.Data.ActiveRecord.Relations + * @since 3.1 + */ abstract class TActiveRecordRelation { private $_context; @@ -28,11 +52,10 @@ abstract class TActiveRecordRelation /** * Dispatch the method calls to the source record finder object. When - * the results are returned as array or is an instance of TActiveRecord we - * will fetch the corresponding foreign objects with an sql query and populate - * the results obtained earlier. + * an instance of TActiveRecord or an array of TActiveRecord is returned + * the corresponding foreign objects are also fetched and assigned. * - * Allows chaining multiple relation handlers. + * Multiple relationship calls can be chain together. * * @param string method name called * @param array method arguments @@ -106,7 +129,7 @@ abstract class TActiveRecordRelation /** * Obtain the foreign key index values from the results. * @param array property names - * @param array|TActiveRecord TActiveRecord results + * @param array TActiveRecord results * @return array foreign key index values. */ protected function getIndexValues($keys, $results) @@ -134,14 +157,16 @@ abstract class TActiveRecordRelation { $collections=array(); foreach($fkObjects as $fkObject) - { - $hash = $this->getObjectHash($fkObject, $fields); - $collections[$hash][]=$fkObject; - } - + $collections[$this->getObjectHash($fkObject, $fields)][]=$fkObject; $this->setResultCollection($results, $collections, $properties); } + /** + * Populates the result array with foreign objects (matched using foreign key hashed property values). + * @param array $results + * @param array $collections + * @param array property names + */ protected function setResultCollection(&$results, &$collections, $properties) { if(is_array($results)) @@ -150,9 +175,7 @@ abstract class TActiveRecordRelation $this->setObjectProperty($results[$i], $properties, $collections); } else - { $this->setObjectProperty($results, $properties, $collections); - } } /** diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php b/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php index 03dc4cd5..a33e105e 100644 --- a/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php +++ b/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php @@ -1,7 +1,33 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005-2007 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Id$ + * @package System.Data.ActiveRecord.Relations + */ +/** + * TActiveRecordRelationContext holds information regarding record relationships + * such as record relation property name, query criteria and foreign object record + * class names. + * + * This class is use internally by passing a context to the TActiveRecordRelation + * constructor. + * + * @author Wei Zhuo + * @version $Id$ + * @package System.Data.ActiveRecord.Relations + * @since 3.1 + */ class TActiveRecordRelationContext { + /** + * static property name in TActiveRecord that defines the record relationships. + */ const RELATIONS_CONST = 'RELATIONS'; private $_property; @@ -16,9 +42,13 @@ class TActiveRecordRelationContext $this->_criteria=$criteria; $this->_relation = $this->getSourceRecordRelation($property); } + /** + * Uses ReflectionClass to obtain the relation details array of a given + * property from the $RELATIONS static property in TActiveRecord. * @param string relation property name * @return array relation definition. + * @throws TActiveRecordException if property is not defined or missing. */ protected function getSourceRecordRelation($property) { @@ -34,46 +64,76 @@ class TActiveRecordRelationContext $property, get_class($this->_sourceRecord), self::RELATIONS_CONST); } + /** + * @return string name of the record property that the relationship results will be assigned to. + */ public function getProperty() { return $this->_property; } + /** + * @return TActiveRecordCriteria sql query criteria for fetching the related record. + */ public function getCriteria() { return $this->_criteria; } + /** + * @return TActiveRecord the active record instance that queried for its related records. + */ public function getSourceRecord() { return $this->_sourceRecord; } + /** + * @return string foreign record class name. + */ public function getForeignRecordClass() { return $this->_relation[1]; } + /** + * @return string HAS_MANY, HAS_ONE, or BELONGS_TO + */ public function getRelationType() { return $this->_relation[0]; } + /** + * @return string the M-N relationship association table name. + */ public function getAssociationTable() { return $this->_relation[2]; } + /** + * @return boolean true if the relationship is HAS_MANY and requires an association table. + */ public function hasAssociationTable() { return isset($this->_relation[2]); } + /** + * @return TActiveRecord corresponding relationship foreign object finder instance. + */ public function getForeignRecordFinder() { return TActiveRecord::finder($this->getForeignRecordClass()); } + /** + * Creates and return the TActiveRecordRelation handler for specific relationships. + * An instance of TActiveRecordHasOne, TActiveRecordBelongsTo, TActiveRecordHasMany, + * or TActiveRecordHasManyAssocation will be returned. + * @return TActiveRecordRelation record relationship handler instnace. + */ public function getRelationHandler() { switch($this->getRelationType()) -- cgit v1.2.3