From 7beffb5a5f493032ccb47dff7909323a6460c520 Mon Sep 17 00:00:00 2001 From: Thomas Rothe Date: Thu, 6 Sep 2012 18:10:30 +0200 Subject: [PATCH 1/2] Several fixes for comments updated @param and @throws annotations --- lib/Doctrine/ORM/UnitOfWork.php | 120 +++++++++++++++++++++++++++----- 1 file changed, 101 insertions(+), 19 deletions(-) diff --git a/lib/Doctrine/ORM/UnitOfWork.php b/lib/Doctrine/ORM/UnitOfWork.php index cf5e4c52c..19ba6cb08 100644 --- a/lib/Doctrine/ORM/UnitOfWork.php +++ b/lib/Doctrine/ORM/UnitOfWork.php @@ -206,7 +206,7 @@ class UnitOfWork implements PropertyChangedListener /** * The EventManager used for dispatching events. * - * @var EventManager + * @var \Doctrine\Common\EventManager */ private $evm; @@ -256,6 +256,9 @@ class UnitOfWork implements PropertyChangedListener * 5) All entity deletions * * @param null|object|array $entity + * + * @throws \Exception + * * @return void */ public function commit($entity = null) @@ -390,6 +393,9 @@ class UnitOfWork implements PropertyChangedListener * 4. Only if entity is properly managed. * * @param object $entity + * + * @throws \InvalidArgumentException + * * @return void */ private function computeSingleEntityChangeSet($entity) @@ -440,6 +446,8 @@ class UnitOfWork implements PropertyChangedListener /** * Gets the changeset for an entity. * + * @param object $entity + * * @return array */ public function getEntityChangeSet($entity) @@ -708,8 +716,13 @@ class UnitOfWork implements PropertyChangedListener /** * Computes the changes of an association. * - * @param AssociationMapping $assoc + * @param array $assoc * @param mixed $value The value of the association. + * + * @throws ORMInvalidArgumentException + * @throws ORMException + * + * @return void */ private function computeAssociationChanges($assoc, $value) { @@ -779,6 +792,10 @@ class UnitOfWork implements PropertyChangedListener } } + /** + * @param ClassMetadata $class + * @param object $entity + */ private function persistNew($class, $entity) { $oid = spl_object_hash($entity); @@ -822,7 +839,8 @@ class UnitOfWork implements PropertyChangedListener * @ignore * @param ClassMetadata $class The class descriptor of the entity. * @param object $entity The entity for which to (re)calculate the change set. - * @throws InvalidArgumentException If the passed entity is not MANAGED. + * + * @throws ORMInvalidArgumentException If the passed entity is not MANAGED. */ public function recomputeSingleEntityChangeSet(ClassMetadata $class, $entity) { @@ -1025,6 +1043,8 @@ class UnitOfWork implements PropertyChangedListener /** * Gets the commit order. * + * @param array $entityChangeSet + * * @return array */ private function getCommitOrder(array $entityChangeSet = null) @@ -1099,6 +1119,9 @@ class UnitOfWork implements PropertyChangedListener * If the entity already has an identifier, it will be added to the identity map. * * @param object $entity The entity to schedule for insertion. + * + * @throws ORMInvalidArgumentException + * @throws \InvalidArgumentException */ public function scheduleForInsert($entity) { @@ -1134,6 +1157,7 @@ class UnitOfWork implements PropertyChangedListener * Checks whether an entity is scheduled for insertion. * * @param object $entity + * * @return boolean */ public function isScheduledForInsert($entity) @@ -1145,6 +1169,8 @@ class UnitOfWork implements PropertyChangedListener * Schedules an entity for being updated. * * @param object $entity The entity to schedule for being updated. + * + * @throws ORMInvalidArgumentException */ public function scheduleForUpdate($entity) { @@ -1194,6 +1220,7 @@ class UnitOfWork implements PropertyChangedListener * at commit time. * * @param object $entity + * * @return boolean */ public function isScheduledForUpdate($entity) @@ -1206,6 +1233,7 @@ class UnitOfWork implements PropertyChangedListener * Checks whether an entity is registered to be checked in the unit of work. * * @param object $entity + * * @return boolean */ public function isScheduledForDirtyCheck($entity) @@ -1256,6 +1284,7 @@ class UnitOfWork implements PropertyChangedListener * of work. * * @param object $entity + * * @return boolean */ public function isScheduledForDelete($entity) @@ -1267,6 +1296,7 @@ class UnitOfWork implements PropertyChangedListener * Checks whether an entity is scheduled for insertion, update or deletion. * * @param $entity + * * @return boolean */ public function isEntityScheduled($entity) @@ -1286,6 +1316,9 @@ class UnitOfWork implements PropertyChangedListener * * @ignore * @param object $entity The entity to register. + * + * @throws ORMInvalidArgumentException + * * @return boolean TRUE if the registration was successful, FALSE if the identity of * the entity in question is already managed. */ @@ -1317,6 +1350,7 @@ class UnitOfWork implements PropertyChangedListener * This parameter can be set to improve performance of entity state detection * by potentially avoiding a database lookup if the distinction between NEW and DETACHED * is either known or does not matter for the caller of the method. + * * @return int The entity state. */ public function getEntityState($entity, $assume = null) @@ -1392,6 +1426,9 @@ class UnitOfWork implements PropertyChangedListener * * @ignore * @param object $entity + * + * @throws ORMInvalidArgumentException + * * @return boolean */ public function removeFromIdentityMap($entity) @@ -1425,6 +1462,7 @@ class UnitOfWork implements PropertyChangedListener * @ignore * @param string $idHash * @param string $rootClassName + * * @return object */ public function getByIdHash($idHash, $rootClassName) @@ -1440,6 +1478,7 @@ class UnitOfWork implements PropertyChangedListener * @ignore * @param string $idHash * @param string $rootClassName + * * @return mixed The found entity or FALSE. */ public function tryGetByIdHash($idHash, $rootClassName) @@ -1455,6 +1494,7 @@ class UnitOfWork implements PropertyChangedListener * Checks whether an entity is registered in the identity map of this UnitOfWork. * * @param object $entity + * * @return boolean */ public function isInIdentityMap($entity) @@ -1482,6 +1522,7 @@ class UnitOfWork implements PropertyChangedListener * @ignore * @param string $idHash * @param string $rootClassName + * * @return boolean */ public function containsIdHash($idHash, $rootClassName) @@ -1509,6 +1550,9 @@ class UnitOfWork implements PropertyChangedListener * * @param object $entity The entity to persist. * @param array $visited The already visited entities. + * + * @throws ORMInvalidArgumentException + * @throws UnexpectedValueException */ private function doPersist($entity, array &$visited) { @@ -1578,7 +1622,9 @@ class UnitOfWork implements PropertyChangedListener * * @param object $entity The entity to delete. * @param array $visited The map of the already visited entities. - * @throws InvalidArgumentException If the instance is a detached entity. + * + * @throws ORMInvalidArgumentException If the instance is a detached entity. + * @throws UnexpectedValueException */ private function doRemove($entity, array &$visited) { @@ -1627,10 +1673,12 @@ class UnitOfWork implements PropertyChangedListener * Merges the state of the given detached entity into this UnitOfWork. * * @param object $entity - * @return object The managed copy of the entity. + * * @throws OptimisticLockException If the entity uses optimistic locking through a version * attribute and the version check against the managed copy fails. * + * @return object The managed copy of the entity. + * * @todo Require active transaction!? OptimisticLockException may result in undefined state!? */ public function merge($entity) @@ -1645,10 +1693,15 @@ class UnitOfWork implements PropertyChangedListener * * @param object $entity * @param array $visited - * @return object The managed copy of the entity. + * @param object $prevManagedCopy + * @param array $assoc + * * @throws OptimisticLockException If the entity uses optimistic locking through a version * attribute and the version check against the managed copy fails. - * @throws InvalidArgumentException If the entity instance is NEW. + * @throws ORMInvalidArgumentException If the entity instance is NEW. + * @throws EntityNotFoundException + * + * @return object The managed copy of the entity. */ private function doMerge($entity, array &$visited, $prevManagedCopy = null, $assoc = null) { @@ -1895,6 +1948,7 @@ class UnitOfWork implements PropertyChangedListener * any local, unpersisted changes. * * @param object $entity The entity to refresh. + * * @throws InvalidArgumentException If the entity is not MANAGED. */ public function refresh($entity) @@ -1909,7 +1963,8 @@ class UnitOfWork implements PropertyChangedListener * * @param object $entity The entity to refresh. * @param array $visited The already visited entities during cascades. - * @throws InvalidArgumentException If the entity is not MANAGED. + * + * @throws ORMInvalidArgumentException If the entity is not MANAGED. */ private function doRefresh($entity, array &$visited) { @@ -2060,7 +2115,8 @@ class UnitOfWork implements PropertyChangedListener * * @param object $entity * @param array $visited - * @param array $insertNow + * + * @return void */ private function cascadePersist($entity, array &$visited) { @@ -2144,6 +2200,12 @@ class UnitOfWork implements PropertyChangedListener * @param object $entity * @param int $lockMode * @param int $lockVersion + * + * @throws ORMInvalidArgumentException + * @throws TransactionRequiredException + * @throws OptimisticLockException + * + * @return void */ public function lock($entity, $lockMode, $lockVersion = null) { @@ -2279,13 +2341,20 @@ class UnitOfWork implements PropertyChangedListener $this->collectionDeletions[$coid] = $coll; } + /** + * @param PersistentCollection $coll + * + * @return bool + */ public function isCollectionScheduledForDeletion(PersistentCollection $coll) { - return isset($this->collectionsDeletions[spl_object_hash($coll)]); + return isset($this->collectionDeletions[spl_object_hash($coll)]); } /** * @param ClassMetadata $class + * + * @return \Doctrine\Common\Persistence\ObjectManagerAware|object */ private function newInstance($class) { @@ -2306,6 +2375,7 @@ class UnitOfWork implements PropertyChangedListener * @param string $className The name of the entity class. * @param array $data The data for the entity. * @param array $hints Any hints to account for during reconstitution/lookup of the entity. + * * @return object The managed entity instance. * @internal Highly performance-sensitive method. * @@ -2578,7 +2648,9 @@ class UnitOfWork implements PropertyChangedListener /** * Initializes (loads) an uninitialized persistent collection of an entity. * - * @param PeristentCollection $collection The collection to initialize. + * @param \Doctrine\ORM\PersistentCollection $collection The collection to initialize. + * + * @return void * @todo Maybe later move to EntityManager#initialize($proxyOrCollection). See DDC-733. */ public function loadCollection(PersistentCollection $collection) @@ -2612,6 +2684,7 @@ class UnitOfWork implements PropertyChangedListener * present at the time the entity was reconstituted from the database. * * @param object $entity + * * @return array */ public function getOriginalEntityData($entity) @@ -2654,6 +2727,7 @@ class UnitOfWork implements PropertyChangedListener * order as the identifier field names as returned by ClassMetadata#getIdentifierFieldNames(). * * @param object $entity + * * @return array The identifier values. */ public function getEntityIdentifier($entity) @@ -2667,6 +2741,7 @@ class UnitOfWork implements PropertyChangedListener * * @param mixed $id The entity identifier to look for. * @param string $rootClassName The name of the root class of the mapped entity hierarchy. + * * @return mixed Returns the entity with the specified identifier if it exists in * this UnitOfWork, FALSE otherwise. */ @@ -2757,9 +2832,9 @@ class UnitOfWork implements PropertyChangedListener /** * Gets a collection persister for a collection-valued association. * - * @param AssociationMapping $association + * @param array $association * - * @return AbstractCollectionPersister + * @return \Doctrine\ORM\Persisters\AbstractCollectionPersister */ public function getCollectionPersister(array $association) { @@ -2901,6 +2976,7 @@ class UnitOfWork implements PropertyChangedListener * Helper method to initialize a lazy loading proxy or persistent collection. * * @param object + * * @return void */ public function initializeObject($obj) @@ -2920,6 +2996,7 @@ class UnitOfWork implements PropertyChangedListener * Helper method to show an object as string. * * @param object $obj + * * @return string */ private static function objToStr($obj) @@ -2931,10 +3008,13 @@ class UnitOfWork implements PropertyChangedListener * Marks an entity as read-only so that it will not be considered for updates during UnitOfWork#commit(). * * This operation cannot be undone as some parts of the UnitOfWork now keep gathering information - * on this object that might be necessary to perform a correct udpate. + * on this object that might be necessary to perform a correct update. + * + * + * @param object $object + * + * @throws ORMInvalidArgumentException * - * @throws \InvalidArgumentException - * @param $object * @return void */ public function markReadOnly($object) @@ -2949,9 +3029,11 @@ class UnitOfWork implements PropertyChangedListener /** * Is this entity read only? * - * @throws \InvalidArgumentException - * @param $object - * @return void + * @param object $object + * + * @throws ORMInvalidArgumentException + * + * @return bool */ public function isReadOnly($object) { From 7acdcd6952ca5407c49d0e7de69babb0f7c668e3 Mon Sep 17 00:00:00 2001 From: Thomas Rothe Date: Thu, 6 Sep 2012 18:13:47 +0200 Subject: [PATCH 2/2] added missing use statement --- lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php b/lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php index 897f71de0..4dc5c7557 100644 --- a/lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php +++ b/lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php @@ -2725,7 +2725,7 @@ class ClassMetadataInfo implements ClassMetadata // Association defined as Id field $joinColumns = $this->associationMappings[$idProperty]['joinColumns']; $assocQuotedColumnNames = array_map( - function ($joinColumn) { + function ($joinColumn) use ($platform) { return isset($joinColumn['quoted']) ? $platform->quoteIdentifier($joinColumn['name']) : $joinColumn['name'];