Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[2.4] Documenting interface methods (based on entity manager) #1191

Merged
merged 3 commits into from
Nov 23, 2014
Merged

[2.4] Documenting interface methods (based on entity manager) #1191

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c4e93cf
Documenting interface methods (based on entity manager)
lcobucci Dec 10, 2013
2b8e03f
Fixing FQCN on docblox
lcobucci Dec 10, 2013
ccbe849
Use docblox from EntityManagerInterface
lcobucci Dec 10, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 27 additions & 158 deletions lib/Doctrine/ORM/EntityManager.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,9 +165,7 @@ protected function __construct(Connection $conn, Configuration $config, EventMan
}

/**
* Gets the database connection object used by the EntityManager.
*
* @return \Doctrine\DBAL\Connection
* {@inheritDoc}
*/
public function getConnection()
{
Expand All @@ -185,18 +183,7 @@ public function getMetadataFactory()
}

/**
* Gets an ExpressionBuilder used for object-oriented construction of query expressions.
*
* Example:
*
* <code>
* $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)));
* </code>
*
* @return \Doctrine\ORM\Query\Expr
* {@inheritDoc}
*/
public function getExpressionBuilder()
{
Expand All @@ -208,28 +195,15 @@ public function getExpressionBuilder()
}

/**
* Starts a transaction on the underlying database connection.
*
* @return void
* {@inheritDoc}
*/
public function beginTransaction()
{
$this->conn->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.
* {@inheritDoc}
*/
public function transactional($func)
{
Expand All @@ -255,19 +229,15 @@ public function transactional($func)
}

/**
* Commits a transaction on the underlying database connection.
*
* @return void
* {@inheritDoc}
*/
public function commit()
{
$this->conn->commit();
}

/**
* Performs a rollback on the underlying database connection.
*
* @return void
* {@inheritDoc}
*/
public function rollback()
{
Expand Down Expand Up @@ -296,11 +266,7 @@ public function getClassMetadata($className)
}

/**
* Creates a new Query object.
*
* @param string $dql The DQL string.
*
* @return \Doctrine\ORM\Query
* {@inheritDoc}
*/
public function createQuery($dql = '')
{
Expand All @@ -314,24 +280,15 @@ public function createQuery($dql = '')
}

/**
* Creates a Query from a named query.
*
* @param string $name
*
* @return \Doctrine\ORM\Query
* {@inheritDoc}
*/
public function createNamedQuery($name)
{
return $this->createQuery($this->config->getNamedQuery($name));
}

/**
* Creates a native SQL query.
*
* @param string $sql
* @param ResultSetMapping $rsm The ResultSetMapping to use.
*
* @return NativeQuery
* {@inheritDoc}
*/
public function createNativeQuery($sql, ResultSetMapping $rsm)
{
Expand All @@ -344,11 +301,7 @@ public function createNativeQuery($sql, ResultSetMapping $rsm)
}

/**
* Creates a NativeQuery from a named native query.
*
* @param string $name
*
* @return \Doctrine\ORM\NativeQuery
* {@inheritDoc}
*/
public function createNamedNativeQuery($name)
{
Expand All @@ -358,9 +311,7 @@ public function createNamedNativeQuery($name)
}

/**
* Create a QueryBuilder instance
*
* @return QueryBuilder
* {@inheritDoc}
*/
public function createQueryBuilder()
{
Expand Down Expand Up @@ -480,15 +431,7 @@ public function find($entityName, $id, $lockMode = LockMode::NONE, $lockVersion
}

/**
* 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)
{
Expand Down Expand Up @@ -529,24 +472,7 @@ 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.
* {@inheritDoc}
*/
public function getPartialReference($entityName, $identifier)
{
Expand Down Expand Up @@ -585,11 +511,7 @@ public function clear($entityName = null)
}

/**
* 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()
{
Expand Down Expand Up @@ -713,14 +635,7 @@ public function merge($entity)
}

/**
* 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!
Expand All @@ -731,16 +646,7 @@ 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
* {@inheritDoc}
*/
public function lock($entity, $lockMode, $lockVersion = null)
{
Expand Down Expand Up @@ -774,19 +680,15 @@ public function contains($entity)
}

/**
* Gets the EventManager used by the EntityManager.
*
* @return \Doctrine\Common\EventManager
* {@inheritDoc}
*/
public function getEventManager()
{
return $this->eventManager;
}

/**
* Gets the Configuration used by the EntityManager.
*
* @return \Doctrine\ORM\Configuration
* {@inheritDoc}
*/
public function getConfiguration()
{
Expand All @@ -808,50 +710,31 @@ private function errorIfClosed()
}

/**
* Check if the Entity manager is open or closed.
*
* @return bool
* {@inheritDoc}
*/
public function isOpen()
{
return (!$this->closed);
}

/**
* Gets the UnitOfWork used by the EntityManager to coordinate operations.
*
* @return \Doctrine\ORM\UnitOfWork
* {@inheritDoc}
*/
public function getUnitOfWork()
{
return $this->unitOfWork;
}

/**
* 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)
{
return $this->newHydrator($hydrationMode);
}

/**
* 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)
{
Expand Down Expand Up @@ -881,23 +764,15 @@ public function newHydrator($hydrationMode)
}

/**
* Gets the proxy factory used by the EntityManager to create entity proxies.
*
* @return ProxyFactory
* {@inheritDoc}
*/
public function getProxyFactory()
{
return $this->proxyFactory;
}

/**
* 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)
{
Expand Down Expand Up @@ -943,9 +818,7 @@ public static function create($conn, Configuration $config, EventManager $eventM
}

/**
* Gets the enabled filters.
*
* @return FilterCollection The active filter collection.
* {@inheritDoc}
*/
public function getFilters()
{
Expand All @@ -957,19 +830,15 @@ public function getFilters()
}

/**
* Checks whether the state of the filter collection is clean.
*
* @return boolean True, if the filter collection is clean.
* {@inheritDoc}
*/
public function isFiltersStateClean()
{
return null === $this->filterCollection || $this->filterCollection->isClean();
}

/**
* Checks whether the Entity Manager has filters.
*
* @return boolean True, if the EM has a filter collection.
* {@inheritDoc}
*/
public function hasFilters()
{
Expand Down
Loading