From dacdd6cd898f9226104f51861f8ed4d240b83959 Mon Sep 17 00:00:00 2001 From: Benjamin Morel Date: Sat, 1 Dec 2012 16:28:06 +0000 Subject: [PATCH] Documentation (docblock) fixes. --- lib/Doctrine/ORM/AbstractQuery.php | 69 ++++-- lib/Doctrine/ORM/Configuration.php | 120 ++++++++-- lib/Doctrine/ORM/EntityManager.php | 110 +++++++-- lib/Doctrine/ORM/EntityRepository.php | 40 ++-- lib/Doctrine/ORM/NativeQuery.php | 2 + lib/Doctrine/ORM/ORMException.php | 108 ++++++++- .../ORM/ORMInvalidArgumentException.php | 79 ++++++- lib/Doctrine/ORM/OptimisticLockException.php | 26 ++- lib/Doctrine/ORM/PersistentCollection.php | 51 ++++- lib/Doctrine/ORM/PessimisticLockException.php | 3 + lib/Doctrine/ORM/Query.php | 41 +++- lib/Doctrine/ORM/QueryBuilder.php | 127 +++++++---- .../ORM/TransactionRequiredException.php | 3 + lib/Doctrine/ORM/UnitOfWork.php | 212 ++++++++++++------ lib/Doctrine/ORM/Version.php | 1 + 15 files changed, 779 insertions(+), 213 deletions(-) diff --git a/lib/Doctrine/ORM/AbstractQuery.php b/lib/Doctrine/ORM/AbstractQuery.php index 5d6a91d13..64c90519a 100644 --- a/lib/Doctrine/ORM/AbstractQuery.php +++ b/lib/Doctrine/ORM/AbstractQuery.php @@ -107,7 +107,7 @@ abstract class AbstractQuery /** * Initializes a new instance of a class derived from AbstractQuery. * - * @param \Doctrine\ORM\EntityManager $entityManager + * @param \Doctrine\ORM\EntityManager $em */ public function __construct(EntityManager $em) { @@ -208,11 +208,11 @@ abstract class AbstractQuery /** * Sets a query parameter. * - * @param string|integer $key The parameter position or name. - * @param mixed $value The parameter value. - * @param string $type The parameter type. If specified, the given value will be run through - * the type conversion of this type. This is usually not needed for - * strings and numeric types. + * @param string|int $key The parameter position or name. + * @param mixed $value The parameter value. + * @param string|null $type The parameter type. If specified, the given value will be run through + * the type conversion of this type. This is usually not needed for + * strings and numeric types. * * @return \Doctrine\ORM\AbstractQuery This query instance. */ @@ -241,10 +241,13 @@ abstract class AbstractQuery } /** - * Process an individual parameter value + * Processes an individual parameter value. * * @param mixed $value + * * @return array + * + * @throws ORMInvalidArgumentException */ public function processParameterValue($value) { @@ -272,6 +275,7 @@ abstract class AbstractQuery * Sets the ResultSetMapping that should be used for hydration. * * @param \Doctrine\ORM\Query\ResultSetMapping $rsm + * * @return \Doctrine\ORM\AbstractQuery */ public function setResultSetMapping(Query\ResultSetMapping $rsm) @@ -300,6 +304,7 @@ abstract class AbstractQuery * $query->setHydrationCacheProfile(new QueryCacheProfile($lifetime, $resultKey)); * * @param \Doctrine\DBAL\Cache\QueryCacheProfile $profile + * * @return \Doctrine\ORM\AbstractQuery */ public function setHydrationCacheProfile(QueryCacheProfile $profile = null) @@ -329,6 +334,7 @@ abstract class AbstractQuery * result cache driver is used from the configuration. * * @param \Doctrine\DBAL\Cache\QueryCacheProfile $profile + * * @return \Doctrine\ORM\AbstractQuery */ public function setResultCacheProfile(QueryCacheProfile $profile = null) @@ -346,8 +352,11 @@ abstract class AbstractQuery /** * Defines a cache driver to be used for caching result sets and implictly enables caching. * - * @param \Doctrine\Common\Cache\Cache $driver Cache driver + * @param \Doctrine\Common\Cache\Cache|null $resultCacheDriver Cache driver + * * @return \Doctrine\ORM\AbstractQuery + * + * @throws ORMException */ public function setResultCacheDriver($resultCacheDriver = null) { @@ -366,6 +375,7 @@ abstract class AbstractQuery * Returns the cache driver used for caching result sets. * * @deprecated + * * @return \Doctrine\Common\Cache\Cache Cache driver */ public function getResultCacheDriver() @@ -383,7 +393,8 @@ abstract class AbstractQuery * * @param boolean $bool * @param integer $lifetime - * @param string $resultCacheId + * @param string $resultCacheId + * * @return \Doctrine\ORM\AbstractQuery This query instance. */ public function useResultCache($bool, $lifetime = null, $resultCacheId = null) @@ -404,6 +415,7 @@ abstract class AbstractQuery * Defines how long the result cache will be active before expire. * * @param integer $lifetime How long the cache entry is valid. + * * @return \Doctrine\ORM\AbstractQuery This query instance. */ public function setResultCacheLifetime($lifetime) @@ -421,6 +433,7 @@ abstract class AbstractQuery * Retrieves the lifetime of resultset cache. * * @deprecated + * * @return integer */ public function getResultCacheLifetime() @@ -432,6 +445,7 @@ abstract class AbstractQuery * Defines if the result cache is active or not. * * @param boolean $expire Whether or not to force resultset cache expiration. + * * @return \Doctrine\ORM\AbstractQuery This query instance. */ public function expireResultCache($expire = true) @@ -464,9 +478,10 @@ abstract class AbstractQuery * * $fetchMode can be one of ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY * - * @param string $class - * @param string $assocName - * @param int $fetchMode + * @param string $class + * @param string $assocName + * @param int $fetchMode + * * @return AbstractQuery */ public function setFetchMode($class, $assocName, $fetchMode) @@ -485,6 +500,7 @@ abstract class AbstractQuery * * @param integer $hydrationMode Doctrine processing mode to be used during hydration process. * One of the Query::HYDRATE_* constants. + * * @return \Doctrine\ORM\AbstractQuery This query instance. */ public function setHydrationMode($hydrationMode) @@ -509,6 +525,8 @@ abstract class AbstractQuery * * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT). * + * @param int $hydrationMode + * * @return array */ public function getResult($hydrationMode = self::HYDRATE_OBJECT) @@ -543,9 +561,11 @@ abstract class AbstractQuery /** * Get exactly one result or null. * - * @throws NonUniqueResultException * @param int $hydrationMode + * * @return mixed + * + * @throws NonUniqueResultException */ public function getOneOrNullResult($hydrationMode = null) { @@ -575,9 +595,11 @@ abstract class AbstractQuery * If there is no result, a NoResultException is thrown. * * @param integer $hydrationMode + * * @return mixed + * * @throws NonUniqueResultException If the query result is not unique. - * @throws NoResultException If the query returned no result. + * @throws NoResultException If the query returned no result. */ public function getSingleResult($hydrationMode = null) { @@ -604,6 +626,7 @@ abstract class AbstractQuery * Alias for getSingleResult(HYDRATE_SINGLE_SCALAR). * * @return mixed + * * @throws QueryException If the query result is not unique. */ public function getSingleScalarResult() @@ -614,8 +637,9 @@ abstract class AbstractQuery /** * Sets a query hint. If the hint name is not recognized, it is silently ignored. * - * @param string $name The name of the hint. - * @param mixed $value The value of the hint. + * @param string $name The name of the hint. + * @param mixed $value The value of the hint. + * * @return \Doctrine\ORM\AbstractQuery */ public function setHint($name, $value) @@ -629,6 +653,7 @@ abstract class AbstractQuery * Gets the value of a query hint. If the hint name is not recognized, FALSE is returned. * * @param string $name The name of the hint. + * * @return mixed The value of the hint or FALSE, if the hint name is not recognized. */ public function getHint($name) @@ -650,8 +675,9 @@ abstract class AbstractQuery * Executes the query and returns an IterableResult that can be used to incrementally * iterate over the result. * - * @param \Doctrine\Common\Collections\ArrayCollection|array $parameters The query parameters. - * @param integer $hydrationMode The hydration mode to use. + * @param ArrayCollection|array|null $parameters The query parameters. + * @param integer|null $hydrationMode The hydration mode to use. + * * @return \Doctrine\ORM\Internal\Hydration\IterableResult */ public function iterate($parameters = null, $hydrationMode = null) @@ -674,8 +700,9 @@ abstract class AbstractQuery /** * Executes the query. * - * @param \Doctrine\Common\Collections\ArrayCollection|array $parameters Query parameters. - * @param integer $hydrationMode Processing mode to be used during the hydration process. + * @param ArrayCollection|array|null $parameters Query parameters. + * @param integer|null $hydrationMode Processing mode to be used during the hydration process. + * * @return mixed */ public function execute($parameters = null, $hydrationMode = null) @@ -760,6 +787,7 @@ abstract class AbstractQuery * generated for you. * * @param string $id + * * @return \Doctrine\ORM\AbstractQuery This query instance. */ public function setResultCacheId($id) @@ -775,6 +803,7 @@ abstract class AbstractQuery * Get the result cache id to use to store the result set cache entry if set. * * @deprecated + * * @return string */ public function getResultCacheId() diff --git a/lib/Doctrine/ORM/Configuration.php b/lib/Doctrine/ORM/Configuration.php index 78f0db898..cc1e5de6b 100644 --- a/lib/Doctrine/ORM/Configuration.php +++ b/lib/Doctrine/ORM/Configuration.php @@ -49,6 +49,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Sets the directory where Doctrine generates any necessary proxy class files. * * @param string $dir + * + * @return void */ public function setProxyDir($dir) { @@ -58,7 +60,7 @@ class Configuration extends \Doctrine\DBAL\Configuration /** * Gets the directory where Doctrine generates any necessary proxy class files. * - * @return string + * @return string|null */ public function getProxyDir() { @@ -85,6 +87,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * during each script execution. * * @param boolean $bool + * + * @return void */ public function setAutoGenerateProxyClasses($bool) { @@ -94,7 +98,7 @@ class Configuration extends \Doctrine\DBAL\Configuration /** * Gets the namespace where proxy classes reside. * - * @return string + * @return string|null */ public function getProxyNamespace() { @@ -107,6 +111,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Sets the namespace where proxy classes reside. * * @param string $ns + * + * @return void */ public function setProxyNamespace($ns) { @@ -117,6 +123,9 @@ class Configuration extends \Doctrine\DBAL\Configuration * Sets the cache driver implementation that is used for metadata caching. * * @param MappingDriver $driverImpl + * + * @return void + * * @todo Force parameter to be a Closure to ensure lazy evaluation * (as soon as a metadata cache is in effect, the driver never needs to initialize). */ @@ -130,7 +139,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * is true, the notation `@Entity` will work, otherwise, the notation `@ORM\Entity` will be supported. * * @param array $paths - * @param bool $useSimpleAnnotationReader + * @param bool $useSimpleAnnotationReader + * * @return AnnotationDriver */ public function newDefaultAnnotationDriver($paths = array(), $useSimpleAnnotationReader = true) @@ -157,6 +167,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * * @param string $alias * @param string $namespace + * + * @return void */ public function addEntityNamespace($alias, $namespace) { @@ -167,8 +179,10 @@ class Configuration extends \Doctrine\DBAL\Configuration * Resolves a registered namespace alias to the full namespace. * * @param string $entityNamespaceAlias - * @throws ORMException + * * @return string + * + * @throws ORMException */ public function getEntityNamespace($entityNamespaceAlias) { @@ -180,9 +194,11 @@ class Configuration extends \Doctrine\DBAL\Configuration } /** - * Set the entity alias map + * Sets the entity alias map. * * @param array $entityNamespaces + * + * @return void */ public function setEntityNamespaces(array $entityNamespaces) { @@ -202,8 +218,9 @@ class Configuration extends \Doctrine\DBAL\Configuration /** * Gets the cache driver implementation that is used for the mapping metadata. * + * @return MappingDriver|null + * * @throws ORMException - * @return MappingDriver */ public function getMetadataDriverImpl() { @@ -215,7 +232,7 @@ class Configuration extends \Doctrine\DBAL\Configuration /** * Gets the cache driver implementation that is used for the query cache (SQL cache). * - * @return \Doctrine\Common\Cache\Cache + * @return \Doctrine\Common\Cache\Cache|null */ public function getQueryCacheImpl() { @@ -228,6 +245,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Sets the cache driver implementation that is used for the query cache (SQL cache). * * @param \Doctrine\Common\Cache\Cache $cacheImpl + * + * @return void */ public function setQueryCacheImpl(Cache $cacheImpl) { @@ -237,7 +256,7 @@ class Configuration extends \Doctrine\DBAL\Configuration /** * Gets the cache driver implementation that is used for the hydration cache (SQL cache). * - * @return \Doctrine\Common\Cache\Cache + * @return \Doctrine\Common\Cache\Cache|null */ public function getHydrationCacheImpl() { @@ -250,6 +269,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Sets the cache driver implementation that is used for the hydration cache (SQL cache). * * @param \Doctrine\Common\Cache\Cache $cacheImpl + * + * @return void */ public function setHydrationCacheImpl(Cache $cacheImpl) { @@ -259,7 +280,7 @@ class Configuration extends \Doctrine\DBAL\Configuration /** * Gets the cache driver implementation that is used for metadata caching. * - * @return \Doctrine\Common\Cache\Cache + * @return \Doctrine\Common\Cache\Cache|null */ public function getMetadataCacheImpl() { @@ -272,6 +293,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Sets the cache driver implementation that is used for metadata caching. * * @param \Doctrine\Common\Cache\Cache $cacheImpl + * + * @return void */ public function setMetadataCacheImpl(Cache $cacheImpl) { @@ -282,7 +305,9 @@ class Configuration extends \Doctrine\DBAL\Configuration * Adds a named DQL query to the configuration. * * @param string $name The name of the query. - * @param string $dql The DQL query string. + * @param string $dql The DQL query string. + * + * @return void */ public function addNamedQuery($name, $dql) { @@ -293,8 +318,10 @@ class Configuration extends \Doctrine\DBAL\Configuration * Gets a previously registered named DQL query. * * @param string $name The name of the query. - * @throws ORMException + * * @return string The DQL query. + * + * @throws ORMException */ public function getNamedQuery($name) { @@ -311,6 +338,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * @param string $name The name of the query. * @param string $sql The native SQL query string. * @param Query\ResultSetMapping $rsm The ResultSetMapping used for the results of the SQL query. + * + * @return void */ public function addNamedNativeQuery($name, $sql, Query\ResultSetMapping $rsm) { @@ -320,10 +349,12 @@ class Configuration extends \Doctrine\DBAL\Configuration /** * Gets the components of a previously registered named native query. * - * @param string $name The name of the query. + * @param string $name The name of the query. + * + * @return array A tuple with the first element being the SQL string and the second + * element being the ResultSetMapping. + * * @throws ORMException - * @return array A tuple with the first element being the SQL string and the second - * element being the ResultSetMapping. */ public function getNamedNativeQuery($name) { @@ -338,6 +369,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Ensures that this Configuration instance contains settings that are * suitable for a production environment. * + * @return void + * * @throws ORMException If a configuration setting has a value that is not * suitable for a production environment. */ @@ -365,6 +398,9 @@ class Configuration extends \Doctrine\DBAL\Configuration * * @param string $name * @param string $className + * + * @return void + * * @throws ORMException */ public function addCustomStringFunction($name, $className) @@ -380,7 +416,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Gets the implementation class name of a registered custom string DQL function. * * @param string $name - * @return string + * + * @return string|null */ public function getCustomStringFunction($name) { @@ -400,6 +437,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Any previously added string functions are discarded. * * @param array $functions The map of custom DQL string functions. + * + * @return void */ public function setCustomStringFunctions(array $functions) { @@ -417,6 +456,9 @@ class Configuration extends \Doctrine\DBAL\Configuration * * @param string $name * @param string $className + * + * @return void + * * @throws ORMException */ public function addCustomNumericFunction($name, $className) @@ -432,7 +474,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Gets the implementation class name of a registered custom numeric DQL function. * * @param string $name - * @return string + * + * @return string|null */ public function getCustomNumericFunction($name) { @@ -452,6 +495,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Any previously added numeric functions are discarded. * * @param array $functions The map of custom DQL numeric functions. + * + * @return void */ public function setCustomNumericFunctions(array $functions) { @@ -469,6 +514,9 @@ class Configuration extends \Doctrine\DBAL\Configuration * * @param string $name * @param string $className + * + * @return void + * * @throws ORMException */ public function addCustomDatetimeFunction($name, $className) @@ -484,7 +532,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Gets the implementation class name of a registered custom date/time DQL function. * * @param string $name - * @return string + * + * @return string|null */ public function getCustomDatetimeFunction($name) { @@ -504,6 +553,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Any previously added date/time functions are discarded. * * @param array $functions The map of custom DQL date/time functions. + * + * @return void */ public function setCustomDatetimeFunctions(array $functions) { @@ -515,7 +566,9 @@ class Configuration extends \Doctrine\DBAL\Configuration /** * Set the custom hydrator modes in one pass. * - * @param array An array of ($modeName => $hydrator) + * @param array $modes An array of ($modeName => $hydrator). + * + * @return void */ public function setCustomHydrationModes($modes) { @@ -530,7 +583,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Get the hydrator class for the given hydration mode name. * * @param string $modeName The hydration mode name. - * @return string $hydrator The hydrator class name. + * + * @return string|null The hydrator class name. */ public function getCustomHydrationMode($modeName) { @@ -544,6 +598,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * * @param string $modeName The hydration mode name. * @param string $hydrator The hydrator class name. + * + * @return void */ public function addCustomHydrationMode($modeName, $hydrator) { @@ -554,6 +610,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * Set a class metadata factory. * * @param string $cmfName + * + * @return void */ public function setClassMetadataFactoryName($cmfName) { @@ -575,9 +633,10 @@ class Configuration extends \Doctrine\DBAL\Configuration /** * Add a filter to the list of possible filters. * - * @param string $name The name of the filter. - * @param string|Query\Filter\SQLFilter $filter The filter class name or an - * SQLFilter instance. + * @param string $name The name of the filter. + * @param string|Query\Filter\SQLFilter $filter The filter class name or an SQLFilter instance. + * + * @return void * * @throws \InvalidArgumentException If the filter is an object and it doesn't * extend the Query\Filter\SQLFilter class. @@ -599,8 +658,8 @@ class Configuration extends \Doctrine\DBAL\Configuration * * @param string $name The name of the filter. * - * @return string|Query\Filter\SQLFilter The class name of the filter, an - * SQLFilter instance or null of it is not defined. + * @return null|string|Query\Filter\SQLFilter The class name of the filter, an + * SQLFilter instance or null of it is not defined. */ public function getFilter($name) { @@ -613,7 +672,11 @@ class Configuration extends \Doctrine\DBAL\Configuration * Set default repository class. * * @since 2.2 + * * @param string $className + * + * @return void + * * @throws ORMException If not is a \Doctrine\Common\Persistence\ObjectRepository */ public function setDefaultRepositoryClassName($className) @@ -631,6 +694,7 @@ class Configuration extends \Doctrine\DBAL\Configuration * Get default repository class. * * @since 2.2 + * * @return string */ public function getDefaultRepositoryClassName() @@ -644,7 +708,10 @@ class Configuration extends \Doctrine\DBAL\Configuration * Set naming strategy. * * @since 2.3 + * * @param NamingStrategy $namingStrategy + * + * @return void */ public function setNamingStrategy(NamingStrategy $namingStrategy) { @@ -655,6 +722,7 @@ class Configuration extends \Doctrine\DBAL\Configuration * Get naming strategy.. * * @since 2.3 + * * @return NamingStrategy */ public function getNamingStrategy() @@ -670,7 +738,10 @@ class Configuration extends \Doctrine\DBAL\Configuration * Set quote strategy. * * @since 2.3 + * * @param \Doctrine\ORM\Mapping\QuoteStrategy $quoteStrategy + * + * @return void */ public function setQuoteStrategy(QuoteStrategy $quoteStrategy) { @@ -681,6 +752,7 @@ class Configuration extends \Doctrine\DBAL\Configuration * Get quote strategy. * * @since 2.3 + * * @return \Doctrine\ORM\Mapping\QuoteStrategy */ public function getQuoteStrategy() diff --git a/lib/Doctrine/ORM/EntityManager.php b/lib/Doctrine/ORM/EntityManager.php index 9a6974424..61f3368f4 100644 --- a/lib/Doctrine/ORM/EntityManager.php +++ b/lib/Doctrine/ORM/EntityManager.php @@ -123,8 +123,8 @@ class EntityManager implements ObjectManager * Creates a new EntityManager that operates on the given database connection * and uses the given Configuration and EventManager implementations. * - * @param \Doctrine\DBAL\Connection $conn - * @param \Doctrine\ORM\Configuration $config + * @param \Doctrine\DBAL\Connection $conn + * @param \Doctrine\ORM\Configuration $config * @param \Doctrine\Common\EventManager $eventManager */ protected function __construct(Connection $conn, Configuration $config, EventManager $eventManager) @@ -193,6 +193,8 @@ class EntityManager implements ObjectManager /** * Starts a transaction on the underlying database connection. + * + * @return void */ public function beginTransaction() { @@ -210,7 +212,8 @@ class EntityManager implements ObjectManager * the transaction is rolled back, the EntityManager closed and the exception re-thrown. * * @param callable $func The function to execute transactionally. - * @return mixed Returns the non-empty value returned from the closure or true instead + * + * @return mixed The non-empty value returned from the closure or true instead. */ public function transactional($func) { @@ -237,6 +240,8 @@ class EntityManager implements ObjectManager /** * Commits a transaction on the underlying database connection. + * + * @return void */ public function commit() { @@ -245,6 +250,8 @@ class EntityManager implements ObjectManager /** * Performs a rollback on the underlying database connection. + * + * @return void */ public function rollback() { @@ -262,6 +269,7 @@ class EntityManager implements ObjectManager * sales:PriceRequest * * @return \Doctrine\ORM\Mapping\ClassMetadata + * * @internal Performance-sensitive method. */ public function getClassMetadata($className) @@ -273,6 +281,7 @@ class EntityManager implements ObjectManager * Creates a new Query object. * * @param string $dql The DQL string. + * * @return \Doctrine\ORM\Query */ public function createQuery($dql = "") @@ -290,6 +299,7 @@ class EntityManager implements ObjectManager * Creates a Query from a named query. * * @param string $name + * * @return \Doctrine\ORM\Query */ public function createNamedQuery($name) @@ -300,8 +310,9 @@ class EntityManager implements ObjectManager /** * Creates a native SQL query. * - * @param string $sql + * @param string $sql * @param ResultSetMapping $rsm The ResultSetMapping to use. + * * @return NativeQuery */ public function createNativeQuery($sql, ResultSetMapping $rsm) @@ -318,6 +329,7 @@ class EntityManager implements ObjectManager * Creates a NativeQuery from a named native query. * * @param string $name + * * @return \Doctrine\ORM\NativeQuery */ public function createNamedNativeQuery($name) @@ -330,7 +342,7 @@ class EntityManager implements ObjectManager /** * Create a QueryBuilder instance * - * @return QueryBuilder $qb + * @return QueryBuilder */ public function createQueryBuilder() { @@ -346,6 +358,7 @@ class EntityManager implements ObjectManager * the cascade-persist semantics + scheduled inserts/removals are synchronized. * * @param object $entity + * * @throws \Doctrine\ORM\OptimisticLockException If a version check on an entity that * makes use of optimistic locking fails. */ @@ -359,12 +372,17 @@ class EntityManager implements ObjectManager /** * Finds an Entity by its identifier. * - * @param string $entityName - * @param mixed $id + * @param string $entityName + * @param mixed $id * @param integer $lockMode * @param integer $lockVersion * * @return object + * + * @throws OptimisticLockException + * @throws ORMInvalidArgumentException + * @throws TransactionRequiredException + * @throws ORMException */ public function find($entityName, $id, $lockMode = LockMode::NONE, $lockVersion = null) { @@ -446,8 +464,11 @@ class EntityManager implements ObjectManager * without actually loading it, if the entity is not yet loaded. * * @param string $entityName The name of the entity type. - * @param mixed $id The entity identifier. + * @param mixed $id The entity identifier. + * * @return object The entity reference. + * + * @throws ORMException */ public function getReference($entityName, $id) { @@ -503,7 +524,8 @@ class EntityManager implements ObjectManager * never be loaded in the first place. * * @param string $entityName The name of the entity type. - * @param mixed $identifier The entity identifier. + * @param mixed $identifier The entity identifier. + * * @return object The (partial) entity reference. */ public function getPartialReference($entityName, $identifier) @@ -533,7 +555,9 @@ class EntityManager implements ObjectManager * Clears the EntityManager. All entities that are currently managed * by this EntityManager become detached. * - * @param string $entityName if given, only entities of this type will get detached + * @param string|null $entityName if given, only entities of this type will get detached + * + * @return void */ public function clear($entityName = null) { @@ -544,6 +568,8 @@ class EntityManager implements ObjectManager * Closes the EntityManager. All entities that are currently managed * by this EntityManager become detached. The EntityManager may no longer * be used after it is closed. + * + * @return void */ public function close() { @@ -561,7 +587,11 @@ class EntityManager implements ObjectManager * NOTE: The persist operation always considers entities that are not yet known to * this EntityManager as NEW. Do not pass detached entities to the persist operation. * - * @param object $object The instance to make managed and persistent. + * @param object $entity The instance to make managed and persistent. + * + * @return void + * + * @throws ORMInvalidArgumentException */ public function persist($entity) { @@ -581,6 +611,10 @@ class EntityManager implements ObjectManager * or as a result of the flush operation. * * @param object $entity The entity instance to remove. + * + * @return void + * + * @throws ORMInvalidArgumentException */ public function remove($entity) { @@ -598,6 +632,10 @@ class EntityManager implements ObjectManager * overriding any local changes that have not yet been persisted. * * @param object $entity The entity to refresh. + * + * @return void + * + * @throws ORMInvalidArgumentException */ public function refresh($entity) { @@ -618,6 +656,10 @@ class EntityManager implements ObjectManager * reference it. * * @param object $entity The entity to detach. + * + * @return void + * + * @throws ORMInvalidArgumentException */ public function detach($entity) { @@ -634,7 +676,10 @@ class EntityManager implements ObjectManager * The entity passed to merge will not become associated/managed with this EntityManager. * * @param object $entity The detached entity to merge into the persistence context. + * * @return object The managed copy of the entity. + * + * @throws ORMInvalidArgumentException */ public function merge($entity) { @@ -650,8 +695,13 @@ class EntityManager implements ObjectManager /** * Creates a copy of the given entity. Can create a shallow or a deep copy. * - * @param object $entity The entity to copy. - * @return object The new entity. + * @param object $entity The entity to copy. + * @param boolean $deep FALSE for a shallow copy, TRUE for a deep copy. + * + * @return object The new entity. + * + * @throws \BadMethodCallException + * * @todo Implementation need. This is necessary since $e2 = clone $e1; throws an E_FATAL when access anything on $e: * Fatal error: Maximum function nesting level of '100' reached, aborting! */ @@ -663,9 +713,12 @@ class EntityManager implements ObjectManager /** * Acquire a lock on the given entity. * - * @param object $entity - * @param int $lockMode - * @param int $lockVersion + * @param object $entity + * @param int $lockMode + * @param int|null $lockVersion + * + * @return void + * * @throws OptimisticLockException * @throws PessimisticLockException */ @@ -678,6 +731,7 @@ class EntityManager implements ObjectManager * Gets the repository for an entity class. * * @param string $entityName The name of the entity. + * * @return EntityRepository The repository class. */ public function getRepository($entityName) @@ -706,6 +760,7 @@ class EntityManager implements ObjectManager * Determines whether an entity instance is managed in this EntityManager. * * @param object $entity + * * @return boolean TRUE if this EntityManager currently manages the given entity, FALSE otherwise. */ public function contains($entity) @@ -738,6 +793,8 @@ class EntityManager implements ObjectManager /** * Throws an exception if the EntityManager is closed or currently not active. * + * @return void + * * @throws ORMException If the EntityManager is closed. */ private function errorIfClosed() @@ -774,6 +831,7 @@ class EntityManager implements ObjectManager * selectively iterate over the result. * * @param int $hydrationMode + * * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator */ public function getHydrator($hydrationMode) @@ -788,8 +846,11 @@ class EntityManager implements ObjectManager /** * Create a new instance for the given hydration mode. * - * @param int $hydrationMode + * @param int $hydrationMode + * * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator + * + * @throws ORMException */ public function newHydrator($hydrationMode) { @@ -834,6 +895,8 @@ class EntityManager implements ObjectManager * This method is a no-op for other objects * * @param object $obj + * + * @return void */ public function initializeObject($obj) { @@ -843,11 +906,14 @@ class EntityManager implements ObjectManager /** * Factory method to create EntityManager instances. * - * @param mixed $conn An array with the connection parameters or an existing - * Connection instance. - * @param Configuration $config The Configuration instance to use. - * @param EventManager $eventManager The EventManager instance to use. + * @param mixed $conn An array with the connection parameters or an existing Connection instance. + * @param Configuration $config The Configuration instance to use. + * @param EventManager $eventManager The EventManager instance to use. + * * @return EntityManager The created EntityManager. + * + * @throws \InvalidArgumentException + * @throws ORMException */ public static function create($conn, Configuration $config, EventManager $eventManager = null) { @@ -902,7 +968,7 @@ class EntityManager implements ObjectManager /** * Checks whether the Entity Manager has filters. * - * @return True, if the EM has a filter collection. + * @return boolean True, if the EM has a filter collection. */ public function hasFilters() { diff --git a/lib/Doctrine/ORM/EntityRepository.php b/lib/Doctrine/ORM/EntityRepository.php index c3d548bb6..8520208c9 100644 --- a/lib/Doctrine/ORM/EntityRepository.php +++ b/lib/Doctrine/ORM/EntityRepository.php @@ -61,8 +61,8 @@ class EntityRepository implements ObjectRepository, Selectable /** * Initializes a new EntityRepository. * - * @param EntityManager $em The EntityManager to use. - * @param Mapping\ClassMetadata $classMetadata The class descriptor. + * @param EntityManager $em The EntityManager to use. + * @param Mapping\ClassMetadata $class The class descriptor. */ public function __construct($em, Mapping\ClassMetadata $class) { @@ -72,10 +72,11 @@ class EntityRepository implements ObjectRepository, Selectable } /** - * Create a new QueryBuilder instance that is prepopulated for this entity name + * Creates a new QueryBuilder instance that is prepopulated for this entity name. * * @param string $alias - * @return QueryBuilder $qb + * + * @return QueryBuilder */ public function createQueryBuilder($alias) { @@ -85,11 +86,12 @@ class EntityRepository implements ObjectRepository, Selectable } /** - * Create a new result set mapping builder for this entity. + * Creates a new result set mapping builder for this entity. * * The column naming strategy is "INCREMENT". * * @param string $alias + * * @return ResultSetMappingBuilder */ public function createResultSetMappingBuilder($alias) @@ -101,9 +103,10 @@ class EntityRepository implements ObjectRepository, Selectable } /** - * Create a new Query instance based on a predefined metadata named query. + * Creates a new Query instance based on a predefined metadata named query. * * @param string $queryName + * * @return Query */ public function createNamedQuery($queryName) @@ -115,6 +118,7 @@ class EntityRepository implements ObjectRepository, Selectable * Creates a native SQL query. * * @param string $queryName + * * @return NativeQuery */ public function createNativeNamedQuery($queryName) @@ -128,6 +132,8 @@ class EntityRepository implements ObjectRepository, Selectable /** * Clears the repository, causing all managed entities to become detached. + * + * @return void */ public function clear() { @@ -137,9 +143,9 @@ class EntityRepository implements ObjectRepository, Selectable /** * Finds an entity by its primary key / identifier. * - * @param mixed $id The identifier. - * @param integer $lockMode - * @param integer $lockVersion + * @param mixed $id The identifier. + * @param int $lockMode The lock mode. + * @param int|null $lockVersion The lock version. * * @return object The entity. */ @@ -161,10 +167,11 @@ class EntityRepository implements ObjectRepository, Selectable /** * Finds entities by a set of criteria. * - * @param array $criteria + * @param array $criteria * @param array|null $orderBy - * @param int|null $limit - * @param int|null $offset + * @param int|null $limit + * @param int|null $offset + * * @return array The objects. */ public function findBy(array $criteria, array $orderBy = null, $limit = null, $offset = null) @@ -179,6 +186,7 @@ class EntityRepository implements ObjectRepository, Selectable * * @param array $criteria * @param array|null $orderBy + * * @return object */ public function findOneBy(array $criteria, array $orderBy = null) @@ -191,8 +199,13 @@ class EntityRepository implements ObjectRepository, Selectable /** * Adds support for magic finders. * + * @param string $method + * @param array $arguments + * * @return array|object The found entity/entities. - * @throws BadMethodCallException If the method called is an invalid find* method + * + * @throws ORMException + * @throws \BadMethodCallException If the method called is an invalid find* method * or no find* method at all and therefore an invalid * method call. */ @@ -291,4 +304,3 @@ class EntityRepository implements ObjectRepository, Selectable return new ArrayCollection($persister->loadCriteria($criteria)); } } - diff --git a/lib/Doctrine/ORM/NativeQuery.php b/lib/Doctrine/ORM/NativeQuery.php index 1b9b02229..86dacf490 100644 --- a/lib/Doctrine/ORM/NativeQuery.php +++ b/lib/Doctrine/ORM/NativeQuery.php @@ -33,6 +33,7 @@ final class NativeQuery extends AbstractQuery * Sets the SQL of the query. * * @param string $sql + * * @return NativeQuery This query instance. */ public function setSQL($sql) @@ -46,6 +47,7 @@ final class NativeQuery extends AbstractQuery * Gets the SQL query. * * @return mixed The built SQL query or an array of all SQL queries. + * * @override */ public function getSQL() diff --git a/lib/Doctrine/ORM/ORMException.php b/lib/Doctrine/ORM/ORMException.php index 2776753c5..99333f034 100644 --- a/lib/Doctrine/ORM/ORMException.php +++ b/lib/Doctrine/ORM/ORMException.php @@ -29,22 +29,41 @@ use Exception; */ class ORMException extends Exception { + /** + * @return ORMException + */ public static function missingMappingDriverImpl() { return new self("It's a requirement to specify a Metadata Driver and pass it ". "to Doctrine\\ORM\\Configuration::setMetadataDriverImpl()."); } + /** + * @param string $queryName + * + * @return ORMException + */ public static function namedQueryNotFound($queryName) { return new self('Could not find a named query by the name "' . $queryName . '"'); } + /** + * @param string $nativeQueryName + * + * @return ORMException + */ public static function namedNativeQueryNotFound($nativeQueryName) { return new self('Could not find a named native query by the name "' . $nativeQueryName . '"'); } + /** + * @param object $entity + * @param object $relatedEntity + * + * @return ORMException + */ public static function entityMissingForeignAssignedId($entity, $relatedEntity) { return new self( @@ -56,6 +75,12 @@ class ORMException extends Exception ); } + /** + * @param object $entity + * @param string $field + * + * @return ORMException + */ public static function entityMissingAssignedIdForField($entity, $field) { return new self("Entity of type " . get_class($entity) . " is missing an assigned ID for field '" . $field . "'. " . @@ -65,6 +90,11 @@ class ORMException extends Exception ); } + /** + * @param string $field + * + * @return ORMException + */ public static function unrecognizedField($field) { return new self("Unrecognized field: $field"); @@ -73,37 +103,67 @@ class ORMException extends Exception /** * @param string $className * @param string $field + * + * @return ORMException */ public static function invalidOrientation($className, $field) { return new self("Invalid order by orientation specified for " . $className . "#" . $field); } + /** + * @param string $mode + * + * @return ORMException + */ public static function invalidFlushMode($mode) { return new self("'$mode' is an invalid flush mode."); } + /** + * @return ORMException + */ public static function entityManagerClosed() { return new self("The EntityManager is closed."); } + /** + * @param string $mode + * + * @return ORMException + */ public static function invalidHydrationMode($mode) { return new self("'$mode' is an invalid hydration mode."); } + /** + * @return ORMException + */ public static function mismatchedEventManager() { return new self("Cannot use different EventManager instances for EntityManager and Connection."); } + /** + * @param string $methodName + * + * @return ORMException + */ public static function findByRequiresParameter($methodName) { return new self("You need to pass a parameter to '".$methodName."'"); } + /** + * @param string $entityName + * @param string $fieldName + * @param string $method + * + * @return ORMException + */ public static function invalidFindByCall($entityName, $fieldName, $method) { return new self( @@ -112,6 +172,12 @@ class ORMException extends Exception ); } + /** + * @param string $entityName + * @param string $associationFieldName + * + * @return ORMException + */ public static function invalidFindByInverseAssociation($entityName, $associationFieldName) { return new self( @@ -120,29 +186,51 @@ class ORMException extends Exception ); } - public static function invalidResultCacheDriver() { + /** + * @return ORMException + */ + public static function invalidResultCacheDriver() + { return new self("Invalid result cache driver; it must implement Doctrine\\Common\\Cache\\Cache."); } - public static function notSupported() { + /** + * @return ORMException + */ + public static function notSupported() + { return new self("This behaviour is (currently) not supported by Doctrine 2"); } + /** + * @return ORMException + */ public static function queryCacheNotConfigured() { return new self('Query Cache is not configured.'); } + /** + * @return ORMException + */ public static function metadataCacheNotConfigured() { return new self('Class Metadata Cache is not configured.'); } + /** + * @return ORMException + */ public static function proxyClassesAlwaysRegenerating() { return new self('Proxy Classes are always regenerating.'); } + /** + * @param string $entityNamespaceAlias + * + * @return ORMException + */ public static function unknownEntityNamespace($entityNamespaceAlias) { return new self( @@ -150,16 +238,32 @@ class ORMException extends Exception ); } + /** + * @param string $className + * + * @return ORMException + */ public static function invalidEntityRepository($className) { return new self("Invalid repository class '".$className."'. It must be a Doctrine\Common\Persistence\ObjectRepository."); } + /** + * @param string $className + * @param string $fieldName + * + * @return ORMException + */ public static function missingIdentifierField($className, $fieldName) { return new self("The identifier $fieldName is missing for a query of " . $className); } + /** + * @param string $functionName + * + * @return ORMException + */ public static function overwriteInternalDQLFunctionNotAllowed($functionName) { return new self("It is not allowed to overwrite internal function '$functionName' in the DQL parser through user-defined functions."); diff --git a/lib/Doctrine/ORM/ORMInvalidArgumentException.php b/lib/Doctrine/ORM/ORMInvalidArgumentException.php index c5df4d2fa..1773df291 100644 --- a/lib/Doctrine/ORM/ORMInvalidArgumentException.php +++ b/lib/Doctrine/ORM/ORMInvalidArgumentException.php @@ -26,21 +26,42 @@ namespace Doctrine\ORM; */ class ORMInvalidArgumentException extends \InvalidArgumentException { + /** + * @param object $entity + * + * @return ORMInvalidArgumentException + */ static public function scheduleInsertForManagedEntity($entity) { return new self("A managed+dirty entity " . self::objToStr($entity) . " can not be scheduled for insertion."); } + /** + * @param object $entity + * + * @return ORMInvalidArgumentException + */ static public function scheduleInsertForRemovedEntity($entity) { return new self("Removed entity " . self::objToStr($entity) . " can not be scheduled for insertion."); } + /** + * @param object $entity + * + * @return ORMInvalidArgumentException + */ static public function scheduleInsertTwice($entity) { return new self("Entity " . self::objToStr($entity) . " can not be scheduled for insertion twice."); } + /** + * @param string $className + * @param object $entity + * + * @return ORMInvalidArgumentException + */ static public function entityWithoutIdentity($className, $entity) { return new self( @@ -49,11 +70,22 @@ class ORMInvalidArgumentException extends \InvalidArgumentException ); } + /** + * @param object $entity + * + * @return ORMInvalidArgumentException + */ static public function readOnlyRequiresManagedEntity($entity) { return new self("Only managed entities can be marked or checked as read only. But " . self::objToStr($entity) . " is not"); } + /** + * @param array $assoc + * @param object $entry + * + * @return ORMInvalidArgumentException + */ static public function newEntityFoundThroughRelationship(array $assoc, $entry) { return new self("A new entity was found through the relationship '" @@ -68,6 +100,12 @@ class ORMInvalidArgumentException extends \InvalidArgumentException ." implement '" . $assoc['targetEntity'] . "#__toString()' to get a clue.")); } + /** + * @param array $assoc + * @param object $entry + * + * @return ORMInvalidArgumentException + */ static public function detachedEntityFoundThroughRelationship(array $assoc, $entry) { return new self("A detached entity of type " . $assoc['targetEntity'] . " (" . self::objToStr($entry) . ") " @@ -75,39 +113,75 @@ class ORMInvalidArgumentException extends \InvalidArgumentException . "during cascading a persist operation."); } + /** + * @param object $entity + * + * @return ORMInvalidArgumentException + */ static public function entityNotManaged($entity) { return new self("Entity " . self::objToStr($entity) . " is not managed. An entity is managed if its fetched " . "from the database or registered as new through EntityManager#persist"); } + /** + * @param object $entity + * @param string $operation + * + * @return ORMInvalidArgumentException + */ static public function entityHasNoIdentity($entity, $operation) { return new self("Entity has no identity, therefore " . $operation ." cannot be performed. " . self::objToStr($entity)); } + /** + * @param object $entity + * @param string $operation + * + * @return ORMInvalidArgumentException + */ static public function entityIsRemoved($entity, $operation) { return new self("Entity is removed, therefore " . $operation ." cannot be performed. " . self::objToStr($entity)); } + /** + * @param object $entity + * @param string $operation + * + * @return ORMInvalidArgumentException + */ static public function detachedEntityCannot($entity, $operation) { return new self("A detached entity was found during " . $operation . " " . self::objToStr($entity)); } + /** + * @param string $context + * @param mixed $given + * @param int $parameterIndex + * + * @return ORMInvalidArgumentException + */ public static function invalidObject($context, $given, $parameterIndex = 1) { - return new self($context .' expects parameter ' . $parameterIndex . + return new self($context . ' expects parameter ' . $parameterIndex . ' to be an entity object, '. gettype($given) . ' given.'); } + /** + * @return ORMInvalidArgumentException + */ public static function invalidCompositeIdentifier() { return new self("Binding an entity with a composite primary key to a query is not supported. " . "You should split the parameter into the explicit fields and bind them seperately."); } + /** + * @return ORMInvalidArgumentException + */ public static function invalidIdentifierBindingEntity() { return new self("Binding entities to query parameters only allowed for entities that have an identifier."); @@ -116,7 +190,8 @@ class ORMInvalidArgumentException extends \InvalidArgumentException /** * Helper method to show an object as string. * - * @param object $obj + * @param object $obj + * * @return string */ private static function objToStr($obj) diff --git a/lib/Doctrine/ORM/OptimisticLockException.php b/lib/Doctrine/ORM/OptimisticLockException.php index b425ac39e..6f1a57631 100644 --- a/lib/Doctrine/ORM/OptimisticLockException.php +++ b/lib/Doctrine/ORM/OptimisticLockException.php @@ -29,8 +29,15 @@ namespace Doctrine\ORM; */ class OptimisticLockException extends ORMException { + /** + * @var object|null + */ private $entity; + /** + * @param string $msg + * @param object $entity + */ public function __construct($msg, $entity) { parent::__construct($msg); @@ -40,23 +47,40 @@ class OptimisticLockException extends ORMException /** * Gets the entity that caused the exception. * - * @return object + * @return object|null */ public function getEntity() { return $this->entity; } + /** + * @param object $entity + * + * @return OptimisticLockException + */ public static function lockFailed($entity) { return new self("The optimistic lock on an entity failed.", $entity); } + /** + * @param object $entity + * @param int $expectedLockVersion + * @param int $actualLockVersion + * + * @return OptimisticLockException + */ public static function lockFailedVersionMissmatch($entity, $expectedLockVersion, $actualLockVersion) { return new self("The optimistic lock failed, version " . $expectedLockVersion . " was expected, but is actually ".$actualLockVersion, $entity); } + /** + * @param string $entityName + * + * @return OptimisticLockException + */ public static function notVersioned($entityName) { return new self("Cannot obtain optimistic lock on unversioned entity " . $entityName, null); diff --git a/lib/Doctrine/ORM/PersistentCollection.php b/lib/Doctrine/ORM/PersistentCollection.php index 8c306f4ab..5580f361b 100644 --- a/lib/Doctrine/ORM/PersistentCollection.php +++ b/lib/Doctrine/ORM/PersistentCollection.php @@ -25,7 +25,6 @@ use Doctrine\Common\Collections\Collection; use Doctrine\Common\Collections\ArrayCollection; use Doctrine\Common\Collections\Selectable; use Doctrine\Common\Collections\Criteria; -use Doctrine\Common\Collections\ExpressionBuilder; use Closure; @@ -87,6 +86,8 @@ final class PersistentCollection implements Collection, Selectable /** * The class descriptor of the collection's entity type. + * + * @var ClassMetadata */ private $typeClass; @@ -115,9 +116,9 @@ final class PersistentCollection implements Collection, Selectable /** * Creates a new persistent collection. * - * @param EntityManager $em The EntityManager the collection will be associated with. + * @param EntityManager $em The EntityManager the collection will be associated with. * @param ClassMetadata $class The class descriptor of the entity type of this collection. - * @param array The collection elements. + * @param array $coll The collection elements. */ public function __construct(EntityManager $em, $class, $coll) { @@ -132,7 +133,9 @@ final class PersistentCollection implements Collection, Selectable * describes the association between the owner and the elements of the collection. * * @param object $entity - * @param AssociationMapping $assoc + * @param array $assoc + * + * @return void */ public function setOwner($entity, array $assoc) { @@ -152,6 +155,9 @@ final class PersistentCollection implements Collection, Selectable return $this->owner; } + /** + * @return Mapping\ClassMetadata + */ public function getTypeClass() { return $this->typeClass; @@ -163,6 +169,8 @@ final class PersistentCollection implements Collection, Selectable * complete bidirectional associations in the case of a one-to-many association. * * @param mixed $element The element to add. + * + * @return void */ public function hydrateAdd($element) { @@ -186,8 +194,10 @@ final class PersistentCollection implements Collection, Selectable * INTERNAL: * Sets a keyed element in the collection during hydration. * - * @param mixed $key The key to set. - * $param mixed $value The element to set. + * @param mixed $key The key to set. + * @param mixed $element The element to set. + * + * @return void */ public function hydrateSet($key, $element) { @@ -206,6 +216,8 @@ final class PersistentCollection implements Collection, Selectable /** * Initializes the collection by loading its contents from the database * if the collection is not yet initialized. + * + * @return void */ public function initialize() { @@ -239,6 +251,8 @@ final class PersistentCollection implements Collection, Selectable /** * INTERNAL: * Tells this collection to take a snapshot of its current state. + * + * @return void */ public function takeSnapshot() { @@ -299,6 +313,8 @@ final class PersistentCollection implements Collection, Selectable /** * Marks this collection as changed/dirty. + * + * @return void */ private function changed() { @@ -332,6 +348,8 @@ final class PersistentCollection implements Collection, Selectable * Sets a boolean flag, indicating whether this collection is dirty. * * @param boolean $dirty Whether the collection should be marked dirty or not. + * + * @return void */ public function setDirty($dirty) { @@ -342,6 +360,8 @@ final class PersistentCollection implements Collection, Selectable * Sets the initialized flag of the collection, forcing it into that state. * * @param boolean $bool + * + * @return void */ public function setInitialized($bool) { @@ -358,7 +378,9 @@ final class PersistentCollection implements Collection, Selectable return $this->initialized; } - /** {@inheritdoc} */ + /** + * {@inheritdoc} + */ public function first() { $this->initialize(); @@ -366,7 +388,9 @@ final class PersistentCollection implements Collection, Selectable return $this->coll->first(); } - /** {@inheritdoc} */ + /** + * {@inheritdoc} + */ public function last() { $this->initialize(); @@ -668,6 +692,8 @@ final class PersistentCollection implements Collection, Selectable * Called by PHP when this collection is serialized. Ensures that only the * elements are properly serialized. * + * @return array + * * @internal Tried to implement Serializable first but that did not work well * with circular references. This solution seems simpler and works well. */ @@ -753,8 +779,8 @@ final class PersistentCollection implements Collection, Selectable * Keys have to be preserved by this method. Calling this method will only return the * selected slice and NOT change the elements contained in the collection slice is called on. * - * @param int $offset - * @param int $length + * @param int $offset + * @param int|null $length * * @return array */ @@ -781,6 +807,8 @@ final class PersistentCollection implements Collection, Selectable * 3. Snapshot leads to invalid diffs being generated. * 4. Lazy loading grabs entities from old owner object. * 5. New collection is connected to old owner and leads to duplicate keys. + * + * @return void */ public function __clone() { @@ -801,7 +829,10 @@ final class PersistentCollection implements Collection, Selectable * return a new collection containing these elements. * * @param \Doctrine\Common\Collections\Criteria $criteria + * * @return Collection + * + * @throws \RuntimeException */ public function matching(Criteria $criteria) { diff --git a/lib/Doctrine/ORM/PessimisticLockException.php b/lib/Doctrine/ORM/PessimisticLockException.php index 5939e282f..2bc93bffe 100644 --- a/lib/Doctrine/ORM/PessimisticLockException.php +++ b/lib/Doctrine/ORM/PessimisticLockException.php @@ -30,6 +30,9 @@ namespace Doctrine\ORM; */ class PessimisticLockException extends ORMException { + /** + * @return PessimisticLockException + */ public static function lockFailed() { return new self("The pessimistic lock failed."); diff --git a/lib/Doctrine/ORM/Query.php b/lib/Doctrine/ORM/Query.php index 2e1b8178b..d64ef3771 100644 --- a/lib/Doctrine/ORM/Query.php +++ b/lib/Doctrine/ORM/Query.php @@ -41,6 +41,7 @@ final class Query extends AbstractQuery * A query object is in CLEAN state when it has NO unparsed/unprocessed DQL parts. */ const STATE_CLEAN = 1; + /** * A query object is in state DIRTY when it has DQL parts that have not yet been * parsed/processed. This is automatically defined as DIRTY when addDqlQueryPart @@ -57,7 +58,6 @@ final class Query extends AbstractQuery */ const HINT_REFRESH = 'doctrine.refresh'; - /** * Internal hint: is set to the proxy entity that is currently triggered for loading * @@ -73,6 +73,7 @@ final class Query extends AbstractQuery * @todo Rename: HINT_OPTIMIZE */ const HINT_FORCE_PARTIAL_LOAD = 'doctrine.forcePartialLoad'; + /** * The includeMetaColumns query hint causes meta columns like foreign keys and * discriminator columns to be selected and returned as part of the query result. @@ -111,7 +112,6 @@ final class Query extends AbstractQuery */ const HINT_LOCK_MODE = 'doctrine.lockMode'; - /** * @var integer $_state The current state of this query. */ @@ -171,6 +171,7 @@ final class Query extends AbstractQuery * Gets the SQL query/queries that correspond to this DQL query. * * @return mixed The built sql query or an array of all sql queries. + * * @override */ public function getSQL() @@ -265,10 +266,13 @@ final class Query extends AbstractQuery } /** - * Processes query parameter mappings + * Processes query parameter mappings. * * @param array $paramMappings + * * @return array + * + * @throws Query\QueryException */ private function processParameterMappings($paramMappings) { @@ -321,7 +325,8 @@ final class Query extends AbstractQuery /** * Defines a cache driver to be used for caching queries. * - * @param Doctrine_Cache_Interface|null $driver Cache driver + * @param Doctrine_Cache_Interface|null $queryCache Cache driver. + * * @return Query This query instance. */ public function setQueryCacheDriver($queryCache) @@ -335,7 +340,8 @@ final class Query extends AbstractQuery * Defines whether the query should make use of a query cache, if available. * * @param boolean $bool - * @return @return Query This query instance. + * + * @return Query This query instance. */ public function useQueryCache($bool) { @@ -362,7 +368,8 @@ final class Query extends AbstractQuery /** * Defines how long the query cache will be active before expire. * - * @param integer $timeToLive How long the cache entry is valid + * @param integer $timeToLive How long the cache entry is valid. + * * @return Query This query instance. */ public function setQueryCacheLifetime($timeToLive) @@ -390,6 +397,7 @@ final class Query extends AbstractQuery * Defines if the query cache is active or not. * * @param boolean $expire Whether or not to force query cache expiration. + * * @return Query This query instance. */ public function expireQueryCache($expire = true) @@ -423,7 +431,8 @@ final class Query extends AbstractQuery /** * Sets a DQL query string. * - * @param string $dqlQuery DQL Query + * @param string $dqlQuery DQL Query. + * * @return \Doctrine\ORM\AbstractQuery */ public function setDQL($dqlQuery) @@ -439,7 +448,7 @@ final class Query extends AbstractQuery /** * Returns the DQL query that is represented by this query object. * - * @return string DQL query + * @return string DQL query. */ public function getDQL() { @@ -454,7 +463,7 @@ final class Query extends AbstractQuery * @see AbstractQuery::STATE_CLEAN * @see AbstractQuery::STATE_DIRTY * - * @return integer Return the query state + * @return integer The query state. */ public function getState() { @@ -464,7 +473,8 @@ final class Query extends AbstractQuery /** * Method to check if an arbitrary piece of DQL exists * - * @param string $dql Arbitrary piece of DQL to check for + * @param string $dql Arbitrary piece of DQL to check for. + * * @return boolean */ public function contains($dql) @@ -476,6 +486,7 @@ final class Query extends AbstractQuery * Sets the position of the first result to retrieve (the "offset"). * * @param integer $firstResult The first result to return. + * * @return Query This query object. */ public function setFirstResult($firstResult) @@ -501,6 +512,7 @@ final class Query extends AbstractQuery * Sets the maximum number of results to retrieve (the "limit"). * * @param integer $maxResults + * * @return Query This query object. */ public function setMaxResults($maxResults) @@ -526,8 +538,9 @@ final class Query extends AbstractQuery * Executes the query and returns an IterableResult that can be used to incrementally * iterated over the result. * - * @param \Doctrine\Common\Collections\ArrayCollection|array $parameters The query parameters. - * @param integer $hydrationMode The hydration mode to use. + * @param ArrayCollection|array|null $parameters The query parameters. + * @param integer $hydrationMode The hydration mode to use. + * * @return \Doctrine\ORM\Internal\Hydration\IterableResult */ public function iterate($parameters = null, $hydrationMode = self::HYDRATE_OBJECT) @@ -561,8 +574,12 @@ final class Query extends AbstractQuery * Set the lock mode for this Query. * * @see \Doctrine\DBAL\LockMode + * * @param int $lockMode + * * @return Query + * + * @throws TransactionRequiredException */ public function setLockMode($lockMode) { diff --git a/lib/Doctrine/ORM/QueryBuilder.php b/lib/Doctrine/ORM/QueryBuilder.php index aa7281028..b4a381689 100644 --- a/lib/Doctrine/ORM/QueryBuilder.php +++ b/lib/Doctrine/ORM/QueryBuilder.php @@ -229,8 +229,9 @@ class QueryBuilder /** * Finds the root entity alias of the joined entity. * - * @param string $alias The alias of the new join entity + * @param string $alias The alias of the new join entity * @param string $parentAlias The parent entity alias of the join relationship + * * @return string */ private function findRootAlias($alias, $parentAlias) @@ -265,7 +266,8 @@ class QueryBuilder * * * @deprecated Please use $qb->getRootAliases() instead. - * @return string $rootAlias + * + * @return string */ public function getRootAlias() { @@ -285,7 +287,7 @@ class QueryBuilder * $qb->getRootAliases(); // array('u') * * - * @return array $rootAliases + * @return array */ public function getRootAliases() { @@ -318,7 +320,7 @@ class QueryBuilder * $qb->getRootEntities(); // array('User') * * - * @return array $rootEntities + * @return array */ public function getRootEntities() { @@ -350,9 +352,10 @@ class QueryBuilder * ->setParameter('user_id', 1); * * - * @param string|integer $key The parameter position or name. - * @param mixed $value The parameter value. - * @param string|null $type PDO::PARAM_* or \Doctrine\DBAL\Types\Type::* constant + * @param string|integer $key The parameter position or name. + * @param mixed $value The parameter value. + * @param string|null $type PDO::PARAM_* or \Doctrine\DBAL\Types\Type::* constant + * * @return QueryBuilder This QueryBuilder instance. */ public function setParameter($key, $value, $type = null) @@ -393,7 +396,8 @@ class QueryBuilder * ))); * * - * @param \Doctrine\Common\Collections\ArrayCollection|array $params The query parameters to set. + * @param \Doctrine\Common\Collections\ArrayCollection|array $parameters The query parameters to set. + * * @return QueryBuilder This QueryBuilder instance. */ public function setParameters($parameters) @@ -450,6 +454,7 @@ class QueryBuilder * Sets the position of the first result to retrieve (the "offset"). * * @param integer $firstResult The first result to return. + * * @return QueryBuilder This QueryBuilder instance. */ public function setFirstResult($firstResult) @@ -474,6 +479,7 @@ class QueryBuilder * Sets the maximum number of results to retrieve (the "limit"). * * @param integer $maxResults The maximum number of results to retrieve. + * * @return QueryBuilder This QueryBuilder instance. */ public function setMaxResults($maxResults) @@ -500,9 +506,10 @@ class QueryBuilder * The available parts are: 'select', 'from', 'join', 'set', 'where', * 'groupBy', 'having' and 'orderBy'. * - * @param string $dqlPartName - * @param string $dqlPart - * @param string $append + * @param string $dqlPartName + * @param Expr\Base $dqlPart + * @param bool $append + * * @return QueryBuilder This QueryBuilder instance. */ public function add($dqlPartName, $dqlPart, $append = false) @@ -552,6 +559,7 @@ class QueryBuilder * * * @param mixed $select The selection expressions. + * * @return QueryBuilder This QueryBuilder instance. */ public function select($select = null) @@ -577,7 +585,8 @@ class QueryBuilder * ->from('User', 'u'); * * - * @param bool + * @param bool $flag + * * @return QueryBuilder */ public function distinct($flag = true) @@ -599,6 +608,7 @@ class QueryBuilder * * * @param mixed $select The selection expression. + * * @return QueryBuilder This QueryBuilder instance. */ public function addSelect($select = null) @@ -626,7 +636,8 @@ class QueryBuilder * * * @param string $delete The class/type whose instances are subject to the deletion. - * @param string $alias The class/type alias used in the constructed query. + * @param string $alias The class/type alias used in the constructed query. + * * @return QueryBuilder This QueryBuilder instance. */ public function delete($delete = null, $alias = null) @@ -652,7 +663,8 @@ class QueryBuilder * * * @param string $update The class/type whose instances are subject to the update. - * @param string $alias The class/type alias used in the constructed query. + * @param string $alias The class/type alias used in the constructed query. + * * @return QueryBuilder This QueryBuilder instance. */ public function update($update = null, $alias = null) @@ -676,9 +688,10 @@ class QueryBuilder * ->from('User', 'u') * * - * @param string $from The class name. - * @param string $alias The alias of the class. + * @param string $from The class name. + * @param string $alias The alias of the class. * @param string $indexBy The index for the from. + * * @return QueryBuilder This QueryBuilder instance. */ public function from($from, $alias, $indexBy = null) @@ -700,11 +713,12 @@ class QueryBuilder * ->join('u.Phonenumbers', 'p', Expr\Join::WITH, 'p.is_primary = 1'); * * - * @param string $join The relationship to join - * @param string $alias The alias of the join - * @param string $conditionType The condition type constant. Either ON or WITH. - * @param string $condition The condition for the join - * @param string $indexBy The index for the join + * @param string $join The relationship to join. + * @param string $alias The alias of the join. + * @param string|null $conditionType The condition type constant. Either ON or WITH. + * @param string|null $condition The condition for the join. + * @param string|null $indexBy The index for the join. + * * @return QueryBuilder This QueryBuilder instance. */ public function join($join, $alias, $conditionType = null, $condition = null, $indexBy = null) @@ -725,11 +739,12 @@ class QueryBuilder * ->from('User', 'u') * ->innerJoin('u.Phonenumbers', 'p', Expr\Join::WITH, 'p.is_primary = 1'); * - * @param string $join The relationship to join - * @param string $alias The alias of the join - * @param string $conditionType The condition type constant. Either ON or WITH. - * @param string $condition The condition for the join - * @param string $indexBy The index for the join + * @param string $join The relationship to join. + * @param string $alias The alias of the join. + * @param string|null $conditionType The condition type constant. Either ON or WITH. + * @param string|null $condition The condition for the join. + * @param string|null $indexBy The index for the join. + * * @return QueryBuilder This QueryBuilder instance. */ public function innerJoin($join, $alias, $conditionType = null, $condition = null, $indexBy = null) @@ -759,11 +774,12 @@ class QueryBuilder * ->leftJoin('u.Phonenumbers', 'p', Expr\Join::WITH, 'p.is_primary = 1'); * * - * @param string $join The relationship to join - * @param string $alias The alias of the join - * @param string $conditionType The condition type constant. Either ON or WITH. - * @param string $condition The condition for the join - * @param string $indexBy The index for the join + * @param string $join The relationship to join. + * @param string $alias The alias of the join. + * @param string|null $conditionType The condition type constant. Either ON or WITH. + * @param string|null $condition The condition for the join. + * @param string|null $indexBy The index for the join. + * * @return QueryBuilder This QueryBuilder instance. */ public function leftJoin($join, $alias, $conditionType = null, $condition = null, $indexBy = null) @@ -789,8 +805,9 @@ class QueryBuilder * ->where('u.id = ?'); * * - * @param string $key The key/field to set. + * @param string $key The key/field to set. * @param string $value The value, expression, placeholder, etc. + * * @return QueryBuilder This QueryBuilder instance. */ public function set($key, $value) @@ -821,6 +838,7 @@ class QueryBuilder * * * @param mixed $predicates The restriction predicates. + * * @return QueryBuilder This QueryBuilder instance. */ public function where($predicates) @@ -845,7 +863,9 @@ class QueryBuilder * * * @param mixed $where The query restrictions. + * * @return QueryBuilder This QueryBuilder instance. + * * @see where() */ public function andWhere($where) @@ -875,8 +895,10 @@ class QueryBuilder * ->orWhere('u.id = 2'); * * - * @param mixed $where The WHERE statement - * @return QueryBuilder $qb + * @param mixed $where The WHERE statement. + * + * @return QueryBuilder + * * @see where() */ public function orWhere($where) @@ -906,6 +928,7 @@ class QueryBuilder * * * @param string $groupBy The grouping expression. + * * @return QueryBuilder This QueryBuilder instance. */ public function groupBy($groupBy) @@ -913,7 +936,6 @@ class QueryBuilder return $this->add('groupBy', new Expr\GroupBy(func_get_args())); } - /** * Adds a grouping expression to the query. * @@ -926,6 +948,7 @@ class QueryBuilder * * * @param string $groupBy The grouping expression. + * * @return QueryBuilder This QueryBuilder instance. */ public function addGroupBy($groupBy) @@ -938,6 +961,7 @@ class QueryBuilder * Replaces any previous having restrictions, if any. * * @param mixed $having The restriction over the groups. + * * @return QueryBuilder This QueryBuilder instance. */ public function having($having) @@ -954,6 +978,7 @@ class QueryBuilder * conjunction with any existing having restrictions. * * @param mixed $having The restriction to append. + * * @return QueryBuilder This QueryBuilder instance. */ public function andHaving($having) @@ -976,6 +1001,7 @@ class QueryBuilder * disjunction with any existing having restrictions. * * @param mixed $having The restriction to add. + * * @return QueryBuilder This QueryBuilder instance. */ public function orHaving($having) @@ -997,8 +1023,9 @@ class QueryBuilder * Specifies an ordering for the query results. * Replaces any previously specified orderings, if any. * - * @param string $sort The ordering expression. + * @param string $sort The ordering expression. * @param string $order The ordering direction. + * * @return QueryBuilder This QueryBuilder instance. */ public function orderBy($sort, $order = null) @@ -1011,8 +1038,9 @@ class QueryBuilder /** * Adds an ordering to the query results. * - * @param string $sort The ordering expression. + * @param string $sort The ordering expression. * @param string $order The ordering direction. + * * @return QueryBuilder This QueryBuilder instance. */ public function addOrderBy($sort, $order = null) @@ -1027,6 +1055,7 @@ class QueryBuilder * Override firstResult and maxResults if they set. * * @param Criteria $criteria + * * @return QueryBuilder */ public function addCriteria(Criteria $criteria) @@ -1061,7 +1090,9 @@ class QueryBuilder * Get a query part by its name. * * @param string $queryPartName + * * @return mixed $queryPart + * * @todo Rename: getQueryPart (or remove?) */ public function getDQLPart($queryPartName) @@ -1073,6 +1104,7 @@ class QueryBuilder * Get all query parts. * * @return array $dqlParts + * * @todo Rename: getQueryParts (or remove?) */ public function getDQLParts() @@ -1080,6 +1112,9 @@ class QueryBuilder return $this->_dqlParts; } + /** + * @return string + */ private function _getDQLForDelete() { return 'DELETE' @@ -1088,6 +1123,9 @@ class QueryBuilder . $this->_getReducedDQLQueryPart('orderBy', array('pre' => ' ORDER BY ', 'separator' => ', ')); } + /** + * @return string + */ private function _getDQLForUpdate() { return 'UPDATE' @@ -1097,6 +1135,9 @@ class QueryBuilder . $this->_getReducedDQLQueryPart('orderBy', array('pre' => ' ORDER BY ', 'separator' => ', ')); } + /** + * @return string + */ private function _getDQLForSelect() { $dql = 'SELECT' @@ -1133,6 +1174,12 @@ class QueryBuilder return $dql; } + /** + * @param string $queryPartName + * @param array $options + * + * @return string + */ private function _getReducedDQLQueryPart($queryPartName, $options = array()) { $queryPart = $this->getDQLPart($queryPartName); @@ -1149,7 +1196,8 @@ class QueryBuilder /** * Reset DQL parts * - * @param array $parts + * @param array|null $parts + * * @return QueryBuilder */ public function resetDQLParts($parts = null) @@ -1169,7 +1217,8 @@ class QueryBuilder * Reset single DQL part * * @param string $part - * @return QueryBuilder; + * + * @return QueryBuilder */ public function resetDQLPart($part) { diff --git a/lib/Doctrine/ORM/TransactionRequiredException.php b/lib/Doctrine/ORM/TransactionRequiredException.php index 3e04224fc..2242e60fb 100644 --- a/lib/Doctrine/ORM/TransactionRequiredException.php +++ b/lib/Doctrine/ORM/TransactionRequiredException.php @@ -30,6 +30,9 @@ namespace Doctrine\ORM; */ class TransactionRequiredException extends ORMException { + /** + * @return TransactionRequiredException + */ static public function transactionRequired() { return new self('An open transaction is required for this operation.'); diff --git a/lib/Doctrine/ORM/UnitOfWork.php b/lib/Doctrine/ORM/UnitOfWork.php index 75e7a3501..9bb7a94ab 100644 --- a/lib/Doctrine/ORM/UnitOfWork.php +++ b/lib/Doctrine/ORM/UnitOfWork.php @@ -259,9 +259,9 @@ class UnitOfWork implements PropertyChangedListener * * @param null|object|array $entity * - * @throws \Exception - * * @return void + * + * @throws \Exception */ public function commit($entity = null) { @@ -396,9 +396,9 @@ class UnitOfWork implements PropertyChangedListener * * @param object $entity * - * @throws \InvalidArgumentException - * * @return void + * + * @throws \InvalidArgumentException */ private function computeSingleEntityChangeSet($entity) { @@ -489,9 +489,13 @@ class UnitOfWork implements PropertyChangedListener * then this collection is marked for deletion. * * @ignore + * * @internal Don't call from the outside. + * * @param ClassMetadata $class The class descriptor of the entity. * @param object $entity The entity for which to compute the changes. + * + * @return void */ public function computeChangeSet(ClassMetadata $class, $entity) { @@ -668,6 +672,8 @@ class UnitOfWork implements PropertyChangedListener * Computes all the changes that have been done to entities and collections * since the last commit and stores these changes in the _entityChangeSet map * temporarily for access by the persisters, until the UoW commit is finished. + * + * @return void */ public function computeChangeSets() { @@ -796,7 +802,9 @@ class UnitOfWork implements PropertyChangedListener /** * @param ClassMetadata $class - * @param object $entity + * @param object $entity + * + * @return void */ private function persistNew($class, $entity) { @@ -839,8 +847,9 @@ class UnitOfWork implements PropertyChangedListener * whereby changes detected in this method prevail. * * @ignore - * @param ClassMetadata $class The class descriptor of the entity. - * @param object $entity The entity for which to (re)calculate the change set. + * + * @param ClassMetadata $class The class descriptor of the entity. + * @param object $entity The entity for which to (re)calculate the change set. * * @throws ORMInvalidArgumentException If the passed entity is not MANAGED. */ @@ -895,6 +904,8 @@ class UnitOfWork implements PropertyChangedListener * Executes all entity insertions for entities of the specified type. * * @param \Doctrine\ORM\Mapping\ClassMetadata $class + * + * @return void */ private function executeInserts($class) { @@ -952,6 +963,8 @@ class UnitOfWork implements PropertyChangedListener * Executes all entity updates for entities of the specified type. * * @param \Doctrine\ORM\Mapping\ClassMetadata $class + * + * @return void */ private function executeUpdates($class) { @@ -1002,6 +1015,8 @@ class UnitOfWork implements PropertyChangedListener * Executes all entity deletions for entities of the specified type. * * @param \Doctrine\ORM\Mapping\ClassMetadata $class + * + * @return void */ private function executeDeletions($class) { @@ -1045,7 +1060,7 @@ class UnitOfWork implements PropertyChangedListener /** * Gets the commit order. * - * @param array $entityChangeSet + * @param array|null $entityChangeSet * * @return array */ @@ -1122,6 +1137,8 @@ class UnitOfWork implements PropertyChangedListener * * @param object $entity The entity to schedule for insertion. * + * @return void + * * @throws ORMInvalidArgumentException * @throws \InvalidArgumentException */ @@ -1172,6 +1189,8 @@ class UnitOfWork implements PropertyChangedListener * * @param object $entity The entity to schedule for being updated. * + * @return void + * * @throws ORMInvalidArgumentException */ public function scheduleForUpdate($entity) @@ -1199,8 +1218,11 @@ class UnitOfWork implements PropertyChangedListener * Extra updates for entities are stored as (entity, changeset) tuples. * * @ignore - * @param object $entity The entity for which to schedule an extra update. - * @param array $changeset The changeset of the entity (what to update). + * + * @param object $entity The entity for which to schedule an extra update. + * @param array $changeset The changeset of the entity (what to update). + * + * @return void */ public function scheduleExtraUpdate($entity, array $changeset) { @@ -1230,7 +1252,6 @@ class UnitOfWork implements PropertyChangedListener return isset($this->entityUpdates[spl_object_hash($entity)]); } - /** * Checks whether an entity is registered to be checked in the unit of work. * @@ -1250,6 +1271,8 @@ class UnitOfWork implements PropertyChangedListener * Schedules an entity for deletion. * * @param object $entity + * + * @return void */ public function scheduleForDelete($entity) { @@ -1297,7 +1320,7 @@ class UnitOfWork implements PropertyChangedListener /** * Checks whether an entity is scheduled for insertion, update or deletion. * - * @param $entity + * @param object $entity * * @return boolean */ @@ -1317,12 +1340,13 @@ class UnitOfWork implements PropertyChangedListener * the root entity. * * @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. * - * @return boolean TRUE if the registration was successful, FALSE if the identity of - * the entity in question is already managed. + * @throws ORMInvalidArgumentException */ public function addToIdentityMap($entity) { @@ -1347,11 +1371,11 @@ class UnitOfWork implements PropertyChangedListener /** * Gets the state of an entity with regard to the current unit of work. * - * @param object $entity - * @param integer $assume The state to assume if the state is not yet known (not MANAGED or REMOVED). - * 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. + * @param object $entity + * @param int|null $assume The state to assume if the state is not yet known (not MANAGED or REMOVED). + * 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. */ @@ -1427,11 +1451,12 @@ class UnitOfWork implements PropertyChangedListener * entity from the persistence management of Doctrine. * * @ignore + * * @param object $entity * - * @throws ORMInvalidArgumentException - * * @return boolean + * + * @throws ORMInvalidArgumentException */ public function removeFromIdentityMap($entity) { @@ -1462,6 +1487,7 @@ class UnitOfWork implements PropertyChangedListener * Gets an entity in the identity map by its identifier hash. * * @ignore + * * @param string $idHash * @param string $rootClassName * @@ -1478,10 +1504,11 @@ class UnitOfWork implements PropertyChangedListener * the given hash, FALSE is returned. * * @ignore + * * @param string $idHash * @param string $rootClassName * - * @return mixed The found entity or FALSE. + * @return object|bool The found entity or FALSE. */ public function tryGetByIdHash($idHash, $rootClassName) { @@ -1522,6 +1549,7 @@ class UnitOfWork implements PropertyChangedListener * Checks whether an identifier hash exists in the identity map. * * @ignore + * * @param string $idHash * @param string $rootClassName * @@ -1536,6 +1564,8 @@ class UnitOfWork implements PropertyChangedListener * Persists an entity as part of the current unit of work. * * @param object $entity The entity to persist. + * + * @return void */ public function persist($entity) { @@ -1550,8 +1580,10 @@ class UnitOfWork implements PropertyChangedListener * This method is internally called during persist() cascades as it tracks * the already visited entities to prevent infinite recursions. * - * @param object $entity The entity to persist. - * @param array $visited The already visited entities. + * @param object $entity The entity to persist. + * @param array $visited The already visited entities. + * + * @return void * * @throws ORMInvalidArgumentException * @throws UnexpectedValueException @@ -1608,6 +1640,8 @@ class UnitOfWork implements PropertyChangedListener * Deletes an entity as part of the current unit of work. * * @param object $entity The entity to remove. + * + * @return void */ public function remove($entity) { @@ -1622,8 +1656,10 @@ class UnitOfWork implements PropertyChangedListener * This method is internally called during delete() cascades as it tracks * the already visited entities to prevent infinite recursions. * - * @param object $entity The entity to delete. - * @param array $visited The map of the already visited entities. + * @param object $entity The entity to delete. + * @param array $visited The map of the already visited entities. + * + * @return void * * @throws ORMInvalidArgumentException If the instance is a detached entity. * @throws UnexpectedValueException @@ -1676,11 +1712,11 @@ class UnitOfWork implements PropertyChangedListener * * @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) @@ -1693,17 +1729,17 @@ class UnitOfWork implements PropertyChangedListener /** * Executes a merge operation on an entity. * - * @param object $entity - * @param array $visited - * @param object $prevManagedCopy - * @param array $assoc + * @param object $entity + * @param array $visited + * @param object|null $prevManagedCopy + * @param array|null $assoc + * + * @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. * @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 +1931,8 @@ class UnitOfWork implements PropertyChangedListener * no longer be managed by Doctrine. * * @param object $entity The entity to detach. + * + * @return void */ public function detach($entity) { @@ -1906,9 +1944,11 @@ class UnitOfWork implements PropertyChangedListener /** * Executes a detach operation on the given entity. * - * @param object $entity - * @param array $visited - * @param boolean $noCascade if true, don't cascade detach operation + * @param object $entity + * @param array $visited + * @param boolean $noCascade if true, don't cascade detach operation. + * + * @return void */ private function doDetach($entity, array &$visited, $noCascade = false) { @@ -1951,6 +1991,8 @@ class UnitOfWork implements PropertyChangedListener * * @param object $entity The entity to refresh. * + * @return void + * * @throws InvalidArgumentException If the entity is not MANAGED. */ public function refresh($entity) @@ -1963,8 +2005,10 @@ class UnitOfWork implements PropertyChangedListener /** * Executes a refresh operation on an entity. * - * @param object $entity The entity to refresh. - * @param array $visited The already visited entities during cascades. + * @param object $entity The entity to refresh. + * @param array $visited The already visited entities during cascades. + * + * @return void * * @throws ORMInvalidArgumentException If the entity is not MANAGED. */ @@ -1996,7 +2040,9 @@ class UnitOfWork implements PropertyChangedListener * Cascades a refresh operation to associated entities. * * @param object $entity - * @param array $visited + * @param array $visited + * + * @return void */ private function cascadeRefresh($entity, array &$visited) { @@ -2037,7 +2083,9 @@ class UnitOfWork implements PropertyChangedListener * Cascades a detach operation to associated entities. * * @param object $entity - * @param array $visited + * @param array $visited + * + * @return void */ private function cascadeDetach($entity, array &$visited) { @@ -2079,7 +2127,9 @@ class UnitOfWork implements PropertyChangedListener * * @param object $entity * @param object $managedCopy - * @param array $visited + * @param array $visited + * + * @return void */ private function cascadeMerge($entity, $managedCopy, array &$visited) { @@ -2116,7 +2166,7 @@ class UnitOfWork implements PropertyChangedListener * Cascades the save operation to associated entities. * * @param object $entity - * @param array $visited + * @param array $visited * * @return void */ @@ -2159,7 +2209,9 @@ class UnitOfWork implements PropertyChangedListener * Cascades the delete operation to associated entities. * * @param object $entity - * @param array $visited + * @param array $visited + * + * @return void */ private function cascadeRemove($entity, array &$visited) { @@ -2200,14 +2252,14 @@ class UnitOfWork implements PropertyChangedListener * Acquire a lock on the given entity. * * @param object $entity - * @param int $lockMode - * @param int $lockVersion + * @param int $lockMode + * @param int $lockVersion + * + * @return void * * @throws ORMInvalidArgumentException * @throws TransactionRequiredException * @throws OptimisticLockException - * - * @return void */ public function lock($entity, $lockMode, $lockVersion = null) { @@ -2271,7 +2323,9 @@ class UnitOfWork implements PropertyChangedListener /** * Clears the UnitOfWork. * - * @param string $entityName if given, only entities of this type will get detached + * @param string|null $entityName if given, only entities of this type will get detached. + * + * @return void */ public function clear($entityName = null) { @@ -2317,7 +2371,10 @@ class UnitOfWork implements PropertyChangedListener * UnitOfWork. * * @ignore + * * @param object $entity + * + * @return void */ public function scheduleOrphanRemoval($entity) { @@ -2329,6 +2386,8 @@ class UnitOfWork implements PropertyChangedListener * Schedules a complete collection for removal when this UnitOfWork commits. * * @param PersistentCollection $coll + * + * @return void */ public function scheduleCollectionDeletion(PersistentCollection $coll) { @@ -2374,11 +2433,13 @@ class UnitOfWork implements PropertyChangedListener * Creates an entity. Used for reconstitution of persistent entities. * * @ignore + * * @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. + * @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. * * @todo Rename: getOrCreateEntity @@ -2653,6 +2714,7 @@ class UnitOfWork implements PropertyChangedListener * @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) @@ -2702,6 +2764,11 @@ class UnitOfWork implements PropertyChangedListener /** * @ignore + * + * @param object $entity + * @param array $data + * + * @return void */ public function setOriginalEntityData($entity, array $data) { @@ -2713,9 +2780,12 @@ class UnitOfWork implements PropertyChangedListener * Sets a property value of the original data array of an entity. * * @ignore + * * @param string $oid * @param string $property - * @param mixed $value + * @param mixed $value + * + * @return void */ public function setOriginalEntityProperty($oid, $property, $value) { @@ -2765,7 +2835,7 @@ class UnitOfWork implements PropertyChangedListener * Tries to find an entity with the given identifier in the identity map of * this UnitOfWork. * - * @param mixed $id The entity identifier to look for. + * @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 @@ -2786,6 +2856,9 @@ class UnitOfWork implements PropertyChangedListener * Schedules an entity for dirty-checking at commit-time. * * @param object $entity The entity to schedule for dirty-checking. + * + * @return void + * * @todo Rename: scheduleForSynchronization */ public function scheduleForDirtyCheck($entity) @@ -2821,7 +2894,7 @@ class UnitOfWork implements PropertyChangedListener /** * Gets the EntityPersister for an Entity. * - * @param string $entityName The name of the Entity. + * @param string $entityName The name of the Entity. * * @return \Doctrine\ORM\Persisters\BasicEntityPersister */ @@ -2890,8 +2963,10 @@ class UnitOfWork implements PropertyChangedListener * Registers an entity as managed. * * @param object $entity The entity. - * @param array $id The identifier values. - * @param array $data The original entity data. + * @param array $id The identifier values. + * @param array $data The original entity data. + * + * @return void */ public function registerManaged($entity, array $id, array $data) { @@ -2913,6 +2988,8 @@ class UnitOfWork implements PropertyChangedListener * Clears the property changeset of the entity with the given OID. * * @param string $oid The entity's OID. + * + * @return void */ public function clearEntityChangeSet($oid) { @@ -2924,10 +3001,12 @@ class UnitOfWork implements PropertyChangedListener /** * Notifies this UnitOfWork of a property change in an entity. * - * @param object $entity The entity that owns the property. + * @param object $entity The entity that owns the property. * @param string $propertyName The name of the property that changed. - * @param mixed $oldValue The old value of the property. - * @param mixed $newValue The new value of the property. + * @param mixed $oldValue The old value of the property. + * @param mixed $newValue The new value of the property. + * + * @return void */ public function propertyChanged($entity, $propertyName, $oldValue, $newValue) { @@ -3001,7 +3080,7 @@ class UnitOfWork implements PropertyChangedListener /** * Helper method to initialize a lazy loading proxy or persistent collection. * - * @param object + * @param object $obj * * @return void */ @@ -3021,7 +3100,7 @@ class UnitOfWork implements PropertyChangedListener /** * Helper method to show an object as string. * - * @param object $obj + * @param object $obj * * @return string */ @@ -3036,12 +3115,11 @@ class UnitOfWork implements PropertyChangedListener * 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 update. * - * * @param object $object * - * @throws ORMInvalidArgumentException - * * @return void + * + * @throws ORMInvalidArgumentException */ public function markReadOnly($object) { @@ -3057,9 +3135,9 @@ class UnitOfWork implements PropertyChangedListener * * @param object $object * - * @throws ORMInvalidArgumentException - * * @return bool + * + * @throws ORMInvalidArgumentException */ public function isReadOnly($object) { diff --git a/lib/Doctrine/ORM/Version.php b/lib/Doctrine/ORM/Version.php index c2bd13d6f..4dba7902f 100644 --- a/lib/Doctrine/ORM/Version.php +++ b/lib/Doctrine/ORM/Version.php @@ -42,6 +42,7 @@ class Version * Compares a Doctrine version with the current one. * * @param string $version Doctrine version to compare. + * * @return int Returns -1 if older, 0 if it is the same, 1 if version * passed as argument is newer. */