From 4714a53c323d62c3602136bd4632d6ddcef18a94 Mon Sep 17 00:00:00 2001 From: Benjamin Morel Date: Sun, 2 Dec 2012 19:44:56 +0000 Subject: [PATCH] Fixed documentation for ORM\Internal --- .../ORM/Internal/CommitOrderCalculator.php | 40 ++++++++- .../Internal/Hydration/AbstractHydrator.php | 84 ++++++++++++++----- .../ORM/Internal/Hydration/ArrayHydrator.php | 38 +++++++-- .../Internal/Hydration/HydrationException.php | 36 ++++++-- .../ORM/Internal/Hydration/IterableResult.php | 7 +- .../ORM/Internal/Hydration/ObjectHydrator.php | 18 +++- 6 files changed, 185 insertions(+), 38 deletions(-) diff --git a/lib/Doctrine/ORM/Internal/CommitOrderCalculator.php b/lib/Doctrine/ORM/Internal/CommitOrderCalculator.php index a4ae5f3e0..b5153e6d3 100644 --- a/lib/Doctrine/ORM/Internal/CommitOrderCalculator.php +++ b/lib/Doctrine/ORM/Internal/CommitOrderCalculator.php @@ -33,9 +33,26 @@ class CommitOrderCalculator const IN_PROGRESS = 2; const VISITED = 3; + /** + * @var array + */ private $_nodeStates = array(); - private $_classes = array(); // The nodes to sort + + /** + * The nodes to sort. + * + * @var array + */ + private $_classes = array(); + + /** + * @var array + */ private $_relatedClasses = array(); + + /** + * @var array + */ private $_sorted = array(); /** @@ -85,6 +102,11 @@ class CommitOrderCalculator return $sorted; } + /** + * @param \Doctrine\ORM\Mapping\ClassMetadata $node + * + * @return void + */ private function _visitNode($node) { $this->_nodeStates[$node->name] = self::IN_PROGRESS; @@ -101,16 +123,32 @@ class CommitOrderCalculator $this->_sorted[] = $node; } + /** + * @param \Doctrine\ORM\Mapping\ClassMetadata $fromClass + * @param \Doctrine\ORM\Mapping\ClassMetadata $toClass + * + * @return void + */ public function addDependency($fromClass, $toClass) { $this->_relatedClasses[$fromClass->name][] = $toClass; } + /** + * @param string $className + * + * @return bool + */ public function hasClass($className) { return isset($this->_classes[$className]); } + /** + * @param \Doctrine\ORM\Mapping\ClassMetadata $class + * + * @return void + */ public function addClass($class) { $this->_classes[$class->name] = $class; diff --git a/lib/Doctrine/ORM/Internal/Hydration/AbstractHydrator.php b/lib/Doctrine/ORM/Internal/Hydration/AbstractHydrator.php index b64024e7f..c8d7fdcfd 100644 --- a/lib/Doctrine/ORM/Internal/Hydration/AbstractHydrator.php +++ b/lib/Doctrine/ORM/Internal/Hydration/AbstractHydrator.php @@ -20,7 +20,6 @@ namespace Doctrine\ORM\Internal\Hydration; use PDO; -use Doctrine\DBAL\Connection; use Doctrine\DBAL\Types\Type; use Doctrine\ORM\EntityManager; use Doctrine\ORM\Events; @@ -37,25 +36,53 @@ use Doctrine\ORM\Mapping\ClassMetadata; */ abstract class AbstractHydrator { - /** @var \Doctrine\ORM\Query\ResultSetMapping The ResultSetMapping. */ + /** + * The ResultSetMapping. + * + * @var \Doctrine\ORM\Query\ResultSetMapping + */ protected $_rsm; - /** @var EntityManager The EntityManager instance. */ + /** + * The EntityManager instance. + * + * @var EntityManager + */ protected $_em; - /** @var \Doctrine\DBAL\Platforms\AbstractPlatform The dbms Platform instance */ + /** + * The dbms Platform instance. + * + * @var \Doctrine\DBAL\Platforms\AbstractPlatform + */ protected $_platform; - /** @var \Doctrine\ORM\UnitOfWork The UnitOfWork of the associated EntityManager. */ + /** + * The UnitOfWork of the associated EntityManager. + * + * @var \Doctrine\ORM\UnitOfWork + */ protected $_uow; - /** @var array The cache used during row-by-row hydration. */ + /** + * The cache used during row-by-row hydration. + * + * @var array + */ protected $_cache = array(); - /** @var \Doctrine\DBAL\Driver\Statement The statement that provides the data to hydrate. */ + /** + * The statement that provides the data to hydrate. + * + * @var \Doctrine\DBAL\Driver\Statement + */ protected $_stmt; - /** @var array The query hints. */ + /** + * The query hints. + * + * @var array + */ protected $_hints; /** @@ -75,6 +102,7 @@ abstract class AbstractHydrator * * @param object $stmt * @param object $resultSetMapping + * @param array $hints * * @return IterableResult */ @@ -97,7 +125,8 @@ abstract class AbstractHydrator * * @param object $stmt * @param object $resultSetMapping - * @param array $hints + * @param array $hints + * * @return mixed */ public function hydrateAll($stmt, $resultSetMapping, array $hints = array()) @@ -141,13 +170,18 @@ abstract class AbstractHydrator /** * Excutes one-time preparation tasks, once each time hydration is started * through {@link hydrateAll} or {@link iterate()}. + * + * @return void */ protected function prepare() - {} + { + } /** * Excutes one-time cleanup tasks at the end of a hydration that was initiated * through {@link hydrateAll} or {@link iterate()}. + * + * @return void */ protected function cleanup() { @@ -162,9 +196,13 @@ abstract class AbstractHydrator * * Template method. * - * @param array $data The row data. - * @param array $cache The cache to use. - * @param mixed $result The result to fill. + * @param array $data The row data. + * @param array $cache The cache to use. + * @param array $result The result to fill. + * + * @return void + * + * @throws HydrationException */ protected function hydrateRowData(array $data, array &$cache, array &$result) { @@ -173,6 +211,8 @@ abstract class AbstractHydrator /** * Hydrates all rows from the current statement instance at once. + * + * @return array */ abstract protected function hydrateAllData(); @@ -185,9 +225,9 @@ abstract class AbstractHydrator * field names during this procedure as well as any necessary conversions on * the values applied. Scalar values are kept in a specfic key 'scalars'. * - * @param array $data SQL Result Row - * @param array &$cache Cache for column to field result information - * @param array &$id Dql-Alias => ID-Hash + * @param array $data SQL Result Row. + * @param array &$cache Cache for column to field result information. + * @param array &$id Dql-Alias => ID-Hash. * @param array &$nonemptyComponents Does this DQL-Alias has at least one non NULL value? * * @return array An array with all the fields (name => value) of the data row, @@ -371,9 +411,11 @@ abstract class AbstractHydrator /** * Register entity as managed in UnitOfWork. * - * @param \Doctrine\ORM\Mapping\ClassMetadata $class - * @param object $entity - * @param array $data + * @param ClassMetadata $class + * @param object $entity + * @param array $data + * + * @return void * * @todo The "$id" generation is the same of UnitOfWork#createEntity. Remove this duplication somehow */ @@ -402,6 +444,10 @@ abstract class AbstractHydrator /** * When executed in a hydrate() loop we have to clear internal state to * decrease memory consumption. + * + * @param mixed $eventArgs + * + * @return void */ public function onClear($eventArgs) { diff --git a/lib/Doctrine/ORM/Internal/Hydration/ArrayHydrator.php b/lib/Doctrine/ORM/Internal/Hydration/ArrayHydrator.php index 3f9d8d15b..bb18f32c6 100644 --- a/lib/Doctrine/ORM/Internal/Hydration/ArrayHydrator.php +++ b/lib/Doctrine/ORM/Internal/Hydration/ArrayHydrator.php @@ -20,7 +20,6 @@ namespace Doctrine\ORM\Internal\Hydration; use PDO; -use Doctrine\DBAL\Connection; use Doctrine\ORM\Mapping\ClassMetadata; /** @@ -33,12 +32,39 @@ use Doctrine\ORM\Mapping\ClassMetadata; */ class ArrayHydrator extends AbstractHydrator { + /** + * @var array + */ private $_ce = array(); + + /** + * @var array + */ private $_rootAliases = array(); + + /** + * @var bool + */ private $_isSimpleQuery = false; + + /** + * @var array + */ private $_identifierMap = array(); + + /** + * @var array + */ private $_resultPointers = array(); + + /** + * @var array + */ private $_idTemplate = array(); + + /** + * @var int + */ private $_resultCounter = 0; /** @@ -238,10 +264,12 @@ class ArrayHydrator extends AbstractHydrator * Updates the result pointer for an Entity. The result pointers point to the * last seen instance of each Entity type. This is used for graph construction. * - * @param array $coll The element. - * @param boolean|integer $index Index of the element in the collection. - * @param string $dqlAlias - * @param boolean $oneToOne Whether it is a single-valued association or not. + * @param array $coll The element. + * @param boolean|integer $index Index of the element in the collection. + * @param string $dqlAlias + * @param boolean $oneToOne Whether it is a single-valued association or not. + * + * @return void */ private function updateResultPointer(array &$coll, $index, $dqlAlias, $oneToOne) { diff --git a/lib/Doctrine/ORM/Internal/Hydration/HydrationException.php b/lib/Doctrine/ORM/Internal/Hydration/HydrationException.php index 2d78742b0..496942e94 100644 --- a/lib/Doctrine/ORM/Internal/Hydration/HydrationException.php +++ b/lib/Doctrine/ORM/Internal/Hydration/HydrationException.php @@ -21,17 +21,31 @@ namespace Doctrine\ORM\Internal\Hydration; class HydrationException extends \Doctrine\ORM\ORMException { + /** + * @return HydrationException + */ public static function nonUniqueResult() { return new self("The result returned by the query was not unique."); } + /** + * @param string $alias + * @param string $parentAlias + * + * @return HydrationException + */ public static function parentObjectOfRelationNotFound($alias, $parentAlias) { return new self("The parent object of entity result with alias '$alias' was not found." . " The parent alias is '$parentAlias'."); } + /** + * @param string $dqlAlias + * + * @return HydrationException + */ public static function emptyDiscriminatorValue($dqlAlias) { return new self("The DQL alias '" . $dqlAlias . "' contains an entity ". @@ -43,10 +57,12 @@ class HydrationException extends \Doctrine\ORM\ORMException /** * @since 2.3 - * @param string $entityName - * @param string $discrColumnName - * @param string $dqlAlias - * @return HydrationException + * + * @param string $entityName + * @param string $discrColumnName + * @param string $dqlAlias + * + * @return HydrationException */ public static function missingDiscriminatorColumn($entityName, $discrColumnName, $dqlAlias) { @@ -58,10 +74,12 @@ class HydrationException extends \Doctrine\ORM\ORMException /** * @since 2.3 - * @param string $entityName - * @param string $discrColumnName - * @param string $dqlAlias - * @return HydrationException + * + * @param string $entityName + * @param string $discrColumnName + * @param string $dqlAlias + * + * @return HydrationException */ public static function missingDiscriminatorMetaMappingColumn($entityName, $discrColumnName, $dqlAlias) { @@ -70,4 +88,4 @@ class HydrationException extends \Doctrine\ORM\ORMException $discrColumnName, $entityName, $dqlAlias )); } -} \ No newline at end of file +} diff --git a/lib/Doctrine/ORM/Internal/Hydration/IterableResult.php b/lib/Doctrine/ORM/Internal/Hydration/IterableResult.php index d04fe0e84..3bbf6724d 100644 --- a/lib/Doctrine/ORM/Internal/Hydration/IterableResult.php +++ b/lib/Doctrine/ORM/Internal/Hydration/IterableResult.php @@ -44,7 +44,7 @@ class IterableResult implements \Iterator private $_key = -1; /** - * @var object + * @var object|null */ private $_current = null; @@ -56,6 +56,11 @@ class IterableResult implements \Iterator $this->_hydrator = $hydrator; } + /** + * @return void + * + * @throws HydrationException + */ public function rewind() { if ($this->_rewinded == true) { diff --git a/lib/Doctrine/ORM/Internal/Hydration/ObjectHydrator.php b/lib/Doctrine/ORM/Internal/Hydration/ObjectHydrator.php index 1dd18566e..4824bbc83 100644 --- a/lib/Doctrine/ORM/Internal/Hydration/ObjectHydrator.php +++ b/lib/Doctrine/ORM/Internal/Hydration/ObjectHydrator.php @@ -38,8 +38,11 @@ use Doctrine\ORM\Proxy\Proxy; */ class ObjectHydrator extends AbstractHydrator { - /* Local ClassMetadata cache to avoid going to the EntityManager all the time. + /** + * Local ClassMetadata cache to avoid going to the EntityManager all the time. * This local cache is maintained between hydration runs and not cleared. + * + * @var array */ private $ce = array(); @@ -80,7 +83,6 @@ class ObjectHydrator extends AbstractHydrator */ private $existingCollections = array(); - /** * {@inheritdoc} */ @@ -191,6 +193,8 @@ class ObjectHydrator extends AbstractHydrator * @param ClassMetadata $class * @param string $fieldName The name of the field on the entity that holds the collection. * @param string $parentDqlAlias Alias of the parent fetch joining this collection. + * + * @return \Doctrine\ORM\PersistentCollection */ private function initRelatedCollection($entity, $class, $fieldName, $parentDqlAlias) { @@ -236,7 +240,10 @@ class ObjectHydrator extends AbstractHydrator * * @param array $data The instance data. * @param string $dqlAlias The DQL alias of the entity's class. + * * @return object The entity. + * + * @throws HydrationException */ private function getEntity(array $data, $dqlAlias) { @@ -275,6 +282,7 @@ class ObjectHydrator extends AbstractHydrator /** * @param string $className * @param array $data + * * @return mixed */ private function getEntityFromIdentityMap($className, array $data) @@ -306,6 +314,7 @@ class ObjectHydrator extends AbstractHydrator * local cache. * * @param string $className The name of the class. + * * @return ClassMetadata */ private function getClassMetadata($className) @@ -337,6 +346,8 @@ class ObjectHydrator extends AbstractHydrator * @param array $row The data of the row to process. * @param array $cache The cache to use. * @param array $result The result array to fill. + * + * @return void */ protected function hydrateRowData(array $row, array &$cache, array &$result) { @@ -593,12 +604,13 @@ class ObjectHydrator extends AbstractHydrator $result[$resultKey][$objIndex] = $obj; } } - } /** * When executed in a hydrate() loop we may have to clear internal state to * decrease memory consumption. + * + * @return void */ public function onClear($eventArgs) {