From 877ba9bf17743cb7a1940ec62171eac98fd99045 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Ot=C3=A1vio=20Cobucci=20Oblonczyk?= Date: Tue, 10 Dec 2013 11:18:27 -0200 Subject: [PATCH 1/3] Documenting interface methods (based on entity manager) --- lib/Doctrine/ORM/EntityManagerInterface.php | 228 ++++++++++++++++++++ 1 file changed, 228 insertions(+) diff --git a/lib/Doctrine/ORM/EntityManagerInterface.php b/lib/Doctrine/ORM/EntityManagerInterface.php index d72f7cd0c..8516894db 100644 --- a/lib/Doctrine/ORM/EntityManagerInterface.php +++ b/lib/Doctrine/ORM/EntityManagerInterface.php @@ -31,30 +31,258 @@ use Doctrine\ORM\Query\ResultSetMapping; */ interface EntityManagerInterface extends ObjectManager { + /** + * Gets the database connection object used by the EntityManager. + * + * @return \Doctrine\DBAL\Connection + */ public function getConnection(); + + /** + * Gets an ExpressionBuilder used for object-oriented construction of query expressions. + * + * Example: + * + * + * $qb = $em->createQueryBuilder(); + * $expr = $em->getExpressionBuilder(); + * $qb->select('u')->from('User', 'u') + * ->where($expr->orX($expr->eq('u.id', 1), $expr->eq('u.id', 2))); + * + * + * @return \Doctrine\ORM\Query\Expr + */ public function getExpressionBuilder(); + + /** + * Starts a transaction on the underlying database connection. + * + * @return void + */ public function beginTransaction(); + + /** + * Executes a function in a transaction. + * + * The function gets passed this EntityManager instance as an (optional) parameter. + * + * {@link flush} is invoked prior to transaction commit. + * + * If an exception occurs during execution of the function or flushing or transaction commit, + * the transaction is rolled back, the EntityManager closed and the exception re-thrown. + * + * @param callable $func The function to execute transactionally. + * + * @return mixed The non-empty value returned from the closure or true instead. + */ public function transactional($func); + + /** + * Commits a transaction on the underlying database connection. + * + * @return void + */ public function commit(); + + /** + * Performs a rollback on the underlying database connection. + * + * @return void + */ public function rollback(); + + /** + * Creates a new Query object. + * + * @param string $dql The DQL string. + * + * @return \Doctrine\ORM\Query + */ public function createQuery($dql = ''); + + /** + * Creates a Query from a named query. + * + * @param string $name + * + * @return \Doctrine\ORM\Query + */ public function createNamedQuery($name); + + /** + * Creates a native SQL query. + * + * @param string $sql + * @param ResultSetMapping $rsm The ResultSetMapping to use. + * + * @return NativeQuery + */ public function createNativeQuery($sql, ResultSetMapping $rsm); + + /** + * Creates a NativeQuery from a named native query. + * + * @param string $name + * + * @return \Doctrine\ORM\NativeQuery + */ public function createNamedNativeQuery($name); + + /** + * Create a QueryBuilder instance + * + * @return QueryBuilder + */ public function createQueryBuilder(); + + /** + * Gets a reference to the entity identified by the given type and identifier + * 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. + * + * @return object The entity reference. + * + * @throws ORMException + */ public function getReference($entityName, $id); + + /** + * Gets a partial reference to the entity identified by the given type and identifier + * without actually loading it, if the entity is not yet loaded. + * + * The returned reference may be a partial object if the entity is not yet loaded/managed. + * If it is a partial object it will not initialize the rest of the entity state on access. + * Thus you can only ever safely access the identifier of an entity obtained through + * this method. + * + * The use-cases for partial references involve maintaining bidirectional associations + * without loading one side of the association or to update an entity without loading it. + * Note, however, that in the latter case the original (persistent) entity data will + * never be visible to the application (especially not event listeners) as it will + * never be loaded in the first place. + * + * @param string $entityName The name of the entity type. + * @param mixed $identifier The entity identifier. + * + * @return object The (partial) entity reference. + */ public function getPartialReference($entityName, $identifier); + + /** + * 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(); + + /** + * Creates a copy of the given entity. Can create a shallow or a deep copy. + * + * @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 + */ public function copy($entity, $deep = false); + + /** + * Acquire a lock on the given entity. + * + * @param object $entity + * @param int $lockMode + * @param int|null $lockVersion + * + * @return void + * + * @throws OptimisticLockException + * @throws PessimisticLockException + */ public function lock($entity, $lockMode, $lockVersion = null); + + /** + * Gets the EventManager used by the EntityManager. + * + * @return \Doctrine\Common\EventManager + */ public function getEventManager(); + + /** + * Gets the Configuration used by the EntityManager. + * + * @return \Doctrine\ORM\Configuration + */ public function getConfiguration(); + + /** + * Check if the Entity manager is open or closed. + * + * @return bool + */ public function isOpen(); + + /** + * Gets the UnitOfWork used by the EntityManager to coordinate operations. + * + * @return \Doctrine\ORM\UnitOfWork + */ public function getUnitOfWork(); + + /** + * Gets a hydrator for the given hydration mode. + * + * This method caches the hydrator instances which is used for all queries that don't + * selectively iterate over the result. + * + * @deprecated + * + * @param int $hydrationMode + * + * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator + */ public function getHydrator($hydrationMode); + + /** + * Create a new instance for the given hydration mode. + * + * @param int $hydrationMode + * + * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator + * + * @throws ORMException + */ public function newHydrator($hydrationMode); + + /** + * Gets the proxy factory used by the EntityManager to create entity proxies. + * + * @return ProxyFactory + */ public function getProxyFactory(); + + /** + * Gets the enabled filters. + * + * @return FilterCollection The active filter collection. + */ public function getFilters(); + + /** + * Checks whether the state of the filter collection is clean. + * + * @return boolean True, if the filter collection is clean. + */ public function isFiltersStateClean(); + + /** + * Checks whether the Entity Manager has filters. + * + * @return boolean True, if the EM has a filter collection. + */ public function hasFilters(); } From 67135e5d6f999f6eb9fba0fa20d29cf3bd664cea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Ot=C3=A1vio=20Cobucci=20Oblonczyk?= Date: Tue, 10 Dec 2013 12:08:53 -0200 Subject: [PATCH 2/3] Fixing FQCN on docblox --- lib/Doctrine/ORM/EntityManagerInterface.php | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/lib/Doctrine/ORM/EntityManagerInterface.php b/lib/Doctrine/ORM/EntityManagerInterface.php index 8516894db..68f680c62 100644 --- a/lib/Doctrine/ORM/EntityManagerInterface.php +++ b/lib/Doctrine/ORM/EntityManagerInterface.php @@ -20,7 +20,6 @@ namespace Doctrine\ORM; use Doctrine\Common\Persistence\ObjectManager; -use Doctrine\DBAL\LockMode; use Doctrine\ORM\Query\ResultSetMapping; /** @@ -96,7 +95,7 @@ interface EntityManagerInterface extends ObjectManager * * @param string $dql The DQL string. * - * @return \Doctrine\ORM\Query + * @return Query */ public function createQuery($dql = ''); @@ -105,7 +104,7 @@ interface EntityManagerInterface extends ObjectManager * * @param string $name * - * @return \Doctrine\ORM\Query + * @return Query */ public function createNamedQuery($name); @@ -124,7 +123,7 @@ interface EntityManagerInterface extends ObjectManager * * @param string $name * - * @return \Doctrine\ORM\NativeQuery + * @return NativeQuery */ public function createNamedNativeQuery($name); @@ -215,7 +214,7 @@ interface EntityManagerInterface extends ObjectManager /** * Gets the Configuration used by the EntityManager. * - * @return \Doctrine\ORM\Configuration + * @return Configuration */ public function getConfiguration(); @@ -229,7 +228,7 @@ interface EntityManagerInterface extends ObjectManager /** * Gets the UnitOfWork used by the EntityManager to coordinate operations. * - * @return \Doctrine\ORM\UnitOfWork + * @return UnitOfWork */ public function getUnitOfWork(); @@ -261,14 +260,14 @@ interface EntityManagerInterface extends ObjectManager /** * Gets the proxy factory used by the EntityManager to create entity proxies. * - * @return ProxyFactory + * @return \Doctrine\ORM\Proxy\ProxyFactory */ public function getProxyFactory(); /** * Gets the enabled filters. * - * @return FilterCollection The active filter collection. + * @return \Doctrine\ORM\Query\FilterCollection The active filter collection. */ public function getFilters(); From 6d58824ac52a63928c5d5e9a9d0b9a184cd92c7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Ot=C3=A1vio=20Cobucci=20Oblonczyk?= Date: Tue, 10 Dec 2013 12:09:36 -0200 Subject: [PATCH 3/3] Use docblox from EntityManagerInterface --- lib/Doctrine/ORM/EntityManager.php | 185 +++++------------------------ 1 file changed, 27 insertions(+), 158 deletions(-) diff --git a/lib/Doctrine/ORM/EntityManager.php b/lib/Doctrine/ORM/EntityManager.php index 65ec9336d..a00697eb3 100644 --- a/lib/Doctrine/ORM/EntityManager.php +++ b/lib/Doctrine/ORM/EntityManager.php @@ -162,9 +162,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Gets the database connection object used by the EntityManager. - * - * @return \Doctrine\DBAL\Connection + * {@inheritDoc} */ public function getConnection() { @@ -182,18 +180,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Gets an ExpressionBuilder used for object-oriented construction of query expressions. - * - * Example: - * - * - * $qb = $em->createQueryBuilder(); - * $expr = $em->getExpressionBuilder(); - * $qb->select('u')->from('User', 'u') - * ->where($expr->orX($expr->eq('u.id', 1), $expr->eq('u.id', 2))); - * - * - * @return \Doctrine\ORM\Query\Expr + * {@inheritDoc} */ public function getExpressionBuilder() { @@ -205,9 +192,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Starts a transaction on the underlying database connection. - * - * @return void + * {@inheritDoc} */ public function beginTransaction() { @@ -215,18 +200,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Executes a function in a transaction. - * - * The function gets passed this EntityManager instance as an (optional) parameter. - * - * {@link flush} is invoked prior to transaction commit. - * - * If an exception occurs during execution of the function or flushing or transaction commit, - * the transaction is rolled back, the EntityManager closed and the exception re-thrown. - * - * @param callable $func The function to execute transactionally. - * - * @return mixed The non-empty value returned from the closure or true instead. + * {@inheritDoc} */ public function transactional($func) { @@ -252,9 +226,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Commits a transaction on the underlying database connection. - * - * @return void + * {@inheritDoc} */ public function commit() { @@ -262,9 +234,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Performs a rollback on the underlying database connection. - * - * @return void + * {@inheritDoc} */ public function rollback() { @@ -293,11 +263,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Creates a new Query object. - * - * @param string $dql The DQL string. - * - * @return \Doctrine\ORM\Query + * {@inheritDoc} */ public function createQuery($dql = '') { @@ -311,11 +277,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Creates a Query from a named query. - * - * @param string $name - * - * @return \Doctrine\ORM\Query + * {@inheritDoc} */ public function createNamedQuery($name) { @@ -323,12 +285,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Creates a native SQL query. - * - * @param string $sql - * @param ResultSetMapping $rsm The ResultSetMapping to use. - * - * @return NativeQuery + * {@inheritDoc} */ public function createNativeQuery($sql, ResultSetMapping $rsm) { @@ -341,11 +298,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Creates a NativeQuery from a named native query. - * - * @param string $name - * - * @return \Doctrine\ORM\NativeQuery + * {@inheritDoc} */ public function createNamedNativeQuery($name) { @@ -355,9 +308,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Create a QueryBuilder instance - * - * @return QueryBuilder + * {@inheritDoc} */ public function createQueryBuilder() { @@ -477,15 +428,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Gets a reference to the entity identified by the given type and identifier - * 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. - * - * @return object The entity reference. - * - * @throws ORMException + * {@inheritDoc} */ public function getReference($entityName, $id) { @@ -526,24 +469,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Gets a partial reference to the entity identified by the given type and identifier - * without actually loading it, if the entity is not yet loaded. - * - * The returned reference may be a partial object if the entity is not yet loaded/managed. - * If it is a partial object it will not initialize the rest of the entity state on access. - * Thus you can only ever safely access the identifier of an entity obtained through - * this method. - * - * The use-cases for partial references involve maintaining bidirectional associations - * without loading one side of the association or to update an entity without loading it. - * Note, however, that in the latter case the original (persistent) entity data will - * never be visible to the application (especially not event listeners) as it will - * never be loaded in the first place. - * - * @param string $entityName The name of the entity type. - * @param mixed $identifier The entity identifier. - * - * @return object The (partial) entity reference. + * {@inheritDoc} */ public function getPartialReference($entityName, $identifier) { @@ -582,11 +508,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * 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 + * {@inheritDoc} */ public function close() { @@ -710,14 +632,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Creates a copy of the given entity. Can create a shallow or a deep copy. - * - * @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 + * {@inheritDoc} * * @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! @@ -728,16 +643,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Acquire a lock on the given entity. - * - * @param object $entity - * @param int $lockMode - * @param int|null $lockVersion - * - * @return void - * - * @throws OptimisticLockException - * @throws PessimisticLockException + * {@inheritDoc} */ public function lock($entity, $lockMode, $lockVersion = null) { @@ -771,9 +677,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Gets the EventManager used by the EntityManager. - * - * @return \Doctrine\Common\EventManager + * {@inheritDoc} */ public function getEventManager() { @@ -781,9 +685,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Gets the Configuration used by the EntityManager. - * - * @return \Doctrine\ORM\Configuration + * {@inheritDoc} */ public function getConfiguration() { @@ -805,9 +707,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Check if the Entity manager is open or closed. - * - * @return bool + * {@inheritDoc} */ public function isOpen() { @@ -815,9 +715,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Gets the UnitOfWork used by the EntityManager to coordinate operations. - * - * @return \Doctrine\ORM\UnitOfWork + * {@inheritDoc} */ public function getUnitOfWork() { @@ -825,16 +723,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Gets a hydrator for the given hydration mode. - * - * This method caches the hydrator instances which is used for all queries that don't - * selectively iterate over the result. - * - * @deprecated - * - * @param int $hydrationMode - * - * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator + * {@inheritDoc} */ public function getHydrator($hydrationMode) { @@ -842,13 +731,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Create a new instance for the given hydration mode. - * - * @param int $hydrationMode - * - * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator - * - * @throws ORMException + * {@inheritDoc} */ public function newHydrator($hydrationMode) { @@ -878,9 +761,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Gets the proxy factory used by the EntityManager to create entity proxies. - * - * @return ProxyFactory + * {@inheritDoc} */ public function getProxyFactory() { @@ -888,13 +769,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Helper method to initialize a lazy loading proxy or persistent collection. - * - * This method is a no-op for other objects - * - * @param object $obj - * - * @return void + * {@inheritDoc} */ public function initializeObject($obj) { @@ -940,9 +815,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Gets the enabled filters. - * - * @return FilterCollection The active filter collection. + * {@inheritDoc} */ public function getFilters() { @@ -954,9 +827,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Checks whether the state of the filter collection is clean. - * - * @return boolean True, if the filter collection is clean. + * {@inheritDoc} */ public function isFiltersStateClean() { @@ -964,9 +835,7 @@ use Doctrine\Common\Util\ClassUtils; } /** - * Checks whether the Entity Manager has filters. - * - * @return boolean True, if the EM has a filter collection. + * {@inheritDoc} */ public function hasFilters() {