EntityManagerInterface.php 8.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287
  1. <?php
  2. /*
  3. * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  4. * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  5. * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  6. * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  7. * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  8. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  9. * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  10. * DATA, OR PROFITS; OR BUSINESS INTERRUPTION); HOWEVER CAUSED AND ON ANY
  11. * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  12. * (INCLUDING NEGLIGENCE OR OTHERWISE); ARISING IN ANY WAY OUT OF THE USE
  13. * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. *
  15. * This software consists of voluntary contributions made by many individuals
  16. * and is licensed under the MIT license. For more information, see
  17. * <http://www.doctrine-project.org>.
  18. */
  19. namespace Doctrine\ORM;
  20. use Doctrine\Common\Persistence\ObjectManager;
  21. use Doctrine\ORM\Query\ResultSetMapping;
  22. /**
  23. * EntityManager interface
  24. *
  25. * @since 2.4
  26. * @author Lars Strojny <lars@strojny.net
  27. */
  28. interface EntityManagerInterface extends ObjectManager
  29. {
  30. /**
  31. * Gets the database connection object used by the EntityManager.
  32. *
  33. * @return \Doctrine\DBAL\Connection
  34. */
  35. public function getConnection();
  36. /**
  37. * Gets an ExpressionBuilder used for object-oriented construction of query expressions.
  38. *
  39. * Example:
  40. *
  41. * <code>
  42. * $qb = $em->createQueryBuilder();
  43. * $expr = $em->getExpressionBuilder();
  44. * $qb->select('u')->from('User', 'u')
  45. * ->where($expr->orX($expr->eq('u.id', 1), $expr->eq('u.id', 2)));
  46. * </code>
  47. *
  48. * @return \Doctrine\ORM\Query\Expr
  49. */
  50. public function getExpressionBuilder();
  51. /**
  52. * Starts a transaction on the underlying database connection.
  53. *
  54. * @return void
  55. */
  56. public function beginTransaction();
  57. /**
  58. * Executes a function in a transaction.
  59. *
  60. * The function gets passed this EntityManager instance as an (optional) parameter.
  61. *
  62. * {@link flush} is invoked prior to transaction commit.
  63. *
  64. * If an exception occurs during execution of the function or flushing or transaction commit,
  65. * the transaction is rolled back, the EntityManager closed and the exception re-thrown.
  66. *
  67. * @param callable $func The function to execute transactionally.
  68. *
  69. * @return mixed The non-empty value returned from the closure or true instead.
  70. */
  71. public function transactional($func);
  72. /**
  73. * Commits a transaction on the underlying database connection.
  74. *
  75. * @return void
  76. */
  77. public function commit();
  78. /**
  79. * Performs a rollback on the underlying database connection.
  80. *
  81. * @return void
  82. */
  83. public function rollback();
  84. /**
  85. * Creates a new Query object.
  86. *
  87. * @param string $dql The DQL string.
  88. *
  89. * @return Query
  90. */
  91. public function createQuery($dql = '');
  92. /**
  93. * Creates a Query from a named query.
  94. *
  95. * @param string $name
  96. *
  97. * @return Query
  98. */
  99. public function createNamedQuery($name);
  100. /**
  101. * Creates a native SQL query.
  102. *
  103. * @param string $sql
  104. * @param ResultSetMapping $rsm The ResultSetMapping to use.
  105. *
  106. * @return NativeQuery
  107. */
  108. public function createNativeQuery($sql, ResultSetMapping $rsm);
  109. /**
  110. * Creates a NativeQuery from a named native query.
  111. *
  112. * @param string $name
  113. *
  114. * @return NativeQuery
  115. */
  116. public function createNamedNativeQuery($name);
  117. /**
  118. * Create a QueryBuilder instance
  119. *
  120. * @return QueryBuilder
  121. */
  122. public function createQueryBuilder();
  123. /**
  124. * Gets a reference to the entity identified by the given type and identifier
  125. * without actually loading it, if the entity is not yet loaded.
  126. *
  127. * @param string $entityName The name of the entity type.
  128. * @param mixed $id The entity identifier.
  129. *
  130. * @return object The entity reference.
  131. *
  132. * @throws ORMException
  133. */
  134. public function getReference($entityName, $id);
  135. /**
  136. * Gets a partial reference to the entity identified by the given type and identifier
  137. * without actually loading it, if the entity is not yet loaded.
  138. *
  139. * The returned reference may be a partial object if the entity is not yet loaded/managed.
  140. * If it is a partial object it will not initialize the rest of the entity state on access.
  141. * Thus you can only ever safely access the identifier of an entity obtained through
  142. * this method.
  143. *
  144. * The use-cases for partial references involve maintaining bidirectional associations
  145. * without loading one side of the association or to update an entity without loading it.
  146. * Note, however, that in the latter case the original (persistent) entity data will
  147. * never be visible to the application (especially not event listeners) as it will
  148. * never be loaded in the first place.
  149. *
  150. * @param string $entityName The name of the entity type.
  151. * @param mixed $identifier The entity identifier.
  152. *
  153. * @return object The (partial) entity reference.
  154. */
  155. public function getPartialReference($entityName, $identifier);
  156. /**
  157. * Closes the EntityManager. All entities that are currently managed
  158. * by this EntityManager become detached. The EntityManager may no longer
  159. * be used after it is closed.
  160. *
  161. * @return void
  162. */
  163. public function close();
  164. /**
  165. * Creates a copy of the given entity. Can create a shallow or a deep copy.
  166. *
  167. * @param object $entity The entity to copy.
  168. * @param boolean $deep FALSE for a shallow copy, TRUE for a deep copy.
  169. *
  170. * @return object The new entity.
  171. *
  172. * @throws \BadMethodCallException
  173. */
  174. public function copy($entity, $deep = false);
  175. /**
  176. * Acquire a lock on the given entity.
  177. *
  178. * @param object $entity
  179. * @param int $lockMode
  180. * @param int|null $lockVersion
  181. *
  182. * @return void
  183. *
  184. * @throws OptimisticLockException
  185. * @throws PessimisticLockException
  186. */
  187. public function lock($entity, $lockMode, $lockVersion = null);
  188. /**
  189. * Gets the EventManager used by the EntityManager.
  190. *
  191. * @return \Doctrine\Common\EventManager
  192. */
  193. public function getEventManager();
  194. /**
  195. * Gets the Configuration used by the EntityManager.
  196. *
  197. * @return Configuration
  198. */
  199. public function getConfiguration();
  200. /**
  201. * Check if the Entity manager is open or closed.
  202. *
  203. * @return bool
  204. */
  205. public function isOpen();
  206. /**
  207. * Gets the UnitOfWork used by the EntityManager to coordinate operations.
  208. *
  209. * @return UnitOfWork
  210. */
  211. public function getUnitOfWork();
  212. /**
  213. * Gets a hydrator for the given hydration mode.
  214. *
  215. * This method caches the hydrator instances which is used for all queries that don't
  216. * selectively iterate over the result.
  217. *
  218. * @deprecated
  219. *
  220. * @param int $hydrationMode
  221. *
  222. * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator
  223. */
  224. public function getHydrator($hydrationMode);
  225. /**
  226. * Create a new instance for the given hydration mode.
  227. *
  228. * @param int $hydrationMode
  229. *
  230. * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator
  231. *
  232. * @throws ORMException
  233. */
  234. public function newHydrator($hydrationMode);
  235. /**
  236. * Gets the proxy factory used by the EntityManager to create entity proxies.
  237. *
  238. * @return \Doctrine\ORM\Proxy\ProxyFactory
  239. */
  240. public function getProxyFactory();
  241. /**
  242. * Gets the enabled filters.
  243. *
  244. * @return \Doctrine\ORM\Query\FilterCollection The active filter collection.
  245. */
  246. public function getFilters();
  247. /**
  248. * Checks whether the state of the filter collection is clean.
  249. *
  250. * @return boolean True, if the filter collection is clean.
  251. */
  252. public function isFiltersStateClean();
  253. /**
  254. * Checks whether the Entity Manager has filters.
  255. *
  256. * @return boolean True, if the EM has a filter collection.
  257. */
  258. public function hasFilters();
  259. }