vendor/doctrine/orm/src/AbstractQuery.php line 953

Open in your IDE?
  1. <?php
  3. declare(strict_types=1);
  5. namespace Doctrine\ORM;
  7. use BackedEnum;
  8. use Countable;
  9. use Doctrine\Common\Cache\Psr6\CacheAdapter;
  10. use Doctrine\Common\Cache\Psr6\DoctrineProvider;
  11. use Doctrine\Common\Collections\ArrayCollection;
  12. use Doctrine\Common\Collections\Collection;
  13. use Doctrine\DBAL\Cache\QueryCacheProfile;
  14. use Doctrine\DBAL\Result;
  15. use Doctrine\Deprecations\Deprecation;
  16. use Doctrine\ORM\Cache\Exception\InvalidResultCacheDriver;
  17. use Doctrine\ORM\Cache\Logging\CacheLogger;
  18. use Doctrine\ORM\Cache\QueryCacheKey;
  19. use Doctrine\ORM\Cache\TimestampCacheKey;
  20. use Doctrine\ORM\Internal\Hydration\IterableResult;
  21. use Doctrine\ORM\Mapping\MappingException as ORMMappingException;
  22. use Doctrine\ORM\Proxy\DefaultProxyClassNameResolver;
  23. use Doctrine\ORM\Query\Parameter;
  24. use Doctrine\ORM\Query\QueryException;
  25. use Doctrine\ORM\Query\ResultSetMapping;
  26. use Doctrine\Persistence\Mapping\MappingException;
  27. use LogicException;
  28. use Psr\Cache\CacheItemPoolInterface;
  29. use Traversable;
  31. use function array_map;
  32. use function array_shift;
  33. use function assert;
  34. use function count;
  35. use function func_num_args;
  36. use function in_array;
  37. use function is_array;
  38. use function is_numeric;
  39. use function is_object;
  40. use function is_scalar;
  41. use function is_string;
  42. use function iterator_count;
  43. use function iterator_to_array;
  44. use function ksort;
  45. use function method_exists;
  46. use function reset;
  47. use function serialize;
  48. use function sha1;
  50. /**
  51. * Base contract for ORM queries. Base class for Query and NativeQuery.
  52. *
  53. * @link www.doctrine-project.org
  54. */
  55. abstract class AbstractQuery
  56. {
  57. /* Hydration mode constants */
  59. /**
  60. * Hydrates an object graph. This is the default behavior.
  61. */
  62. public const HYDRATE_OBJECT = 1;
  64. /**
  65. * Hydrates an array graph.
  66. */
  67. public const HYDRATE_ARRAY = 2;
  69. /**
  70. * Hydrates a flat, rectangular result set with scalar values.
  71. */
  72. public const HYDRATE_SCALAR = 3;
  74. /**
  75. * Hydrates a single scalar value.
  76. */
  77. public const HYDRATE_SINGLE_SCALAR = 4;
  79. /**
  80. * Very simple object hydrator (optimized for performance).
  81. */
  82. public const HYDRATE_SIMPLEOBJECT = 5;
  84. /**
  85. * Hydrates scalar column value.
  86. */
  87. public const HYDRATE_SCALAR_COLUMN = 6;
  89. /**
  90. * The parameter map of this query.
  91. *
  92. * @var ArrayCollection|Parameter[]
  93. * @psalm-var ArrayCollection<int, Parameter>
  94. */
  95. protected $parameters;
  97. /**
  98. * The user-specified ResultSetMapping to use.
  99. *
  100. * @var ResultSetMapping|null
  101. */
  102. protected $_resultSetMapping;
  104. /**
  105. * The entity manager used by this query object.
  106. *
  107. * @var EntityManagerInterface
  108. */
  109. protected $_em;
  111. /**
  112. * The map of query hints.
  113. *
  114. * @psalm-var array<string, mixed>
  115. */
  116. protected $_hints = [];
  118. /**
  119. * The hydration mode.
  120. *
  121. * @var string|int
  122. * @psalm-var string|AbstractQuery::HYDRATE_*
  123. */
  124. protected $_hydrationMode = self::HYDRATE_OBJECT;
  126. /** @var QueryCacheProfile|null */
  127. protected $_queryCacheProfile;
  129. /**
  130. * Whether or not expire the result cache.
  131. *
  132. * @var bool
  133. */
  134. protected $_expireResultCache = false;
  136. /** @var QueryCacheProfile|null */
  137. protected $_hydrationCacheProfile;
  139. /**
  140. * Whether to use second level cache, if available.
  141. *
  142. * @var bool
  143. */
  144. protected $cacheable = false;
  146. /** @var bool */
  147. protected $hasCache = false;
  149. /**
  150. * Second level cache region name.
  151. *
  152. * @var string|null
  153. */
  154. protected $cacheRegion;
  156. /**
  157. * Second level query cache mode.
  158. *
  159. * @var int|null
  160. * @psalm-var Cache::MODE_*|null
  161. */
  162. protected $cacheMode;
  164. /** @var CacheLogger|null */
  165. protected $cacheLogger;
  167. /** @var int */
  168. protected $lifetime = 0;
  170. /**
  171. * Initializes a new instance of a class derived from <tt>AbstractQuery</tt>.
  172. */
  173. public function __construct(EntityManagerInterface $em)
  174. {
  175. $this->_em = $em;
  176. $this->parameters = new ArrayCollection();
  177. $this->_hints = $em->getConfiguration()->getDefaultQueryHints();
  178. $this->hasCache = $this->_em->getConfiguration()->isSecondLevelCacheEnabled();
  180. if ($this->hasCache) {
  181. $this->cacheLogger = $em->getConfiguration()
  182. ->getSecondLevelCacheConfiguration()
  183. ->getCacheLogger();
  184. }
  185. }
  187. /**
  188. * Enable/disable second level query (result) caching for this query.
  189. *
  190. * @param bool $cacheable
  191. *
  192. * @return $this
  193. */
  194. public function setCacheable($cacheable)
  195. {
  196. $this->cacheable = (bool) $cacheable;
  198. return $this;
  199. }
  201. /** @return bool TRUE if the query results are enabled for second level cache, FALSE otherwise. */
  202. public function isCacheable()
  203. {
  204. return $this->cacheable;
  205. }
  207. /**
  208. * @param string $cacheRegion
  209. *
  210. * @return $this
  211. */
  212. public function setCacheRegion($cacheRegion)
  213. {
  214. $this->cacheRegion = (string) $cacheRegion;
  216. return $this;
  217. }
  219. /**
  220. * Obtain the name of the second level query cache region in which query results will be stored
  221. *
  222. * @return string|null The cache region name; NULL indicates the default region.
  223. */
  224. public function getCacheRegion()
  225. {
  226. return $this->cacheRegion;
  227. }
  229. /** @return bool TRUE if the query cache and second level cache are enabled, FALSE otherwise. */
  230. protected function isCacheEnabled()
  231. {
  232. return $this->cacheable && $this->hasCache;
  233. }
  235. /** @return int */
  236. public function getLifetime()
  237. {
  238. return $this->lifetime;
  239. }
  241. /**
  242. * Sets the life-time for this query into second level cache.
  243. *
  244. * @param int $lifetime
  245. *
  246. * @return $this
  247. */
  248. public function setLifetime($lifetime)
  249. {
  250. $this->lifetime = (int) $lifetime;
  252. return $this;
  253. }
  255. /**
  256. * @return int|null
  257. * @psalm-return Cache::MODE_*|null
  258. */
  259. public function getCacheMode()
  260. {
  261. return $this->cacheMode;
  262. }
  264. /**
  265. * @param int $cacheMode
  266. * @psalm-param Cache::MODE_* $cacheMode
  267. *
  268. * @return $this
  269. */
  270. public function setCacheMode($cacheMode)
  271. {
  272. $this->cacheMode = (int) $cacheMode;
  274. return $this;
  275. }
  277. /**
  278. * Gets the SQL query that corresponds to this query object.
  279. * The returned SQL syntax depends on the connection driver that is used
  280. * by this query object at the time of this method call.
  281. *
  282. * @return list<string>|string SQL query
  283. */
  284. abstract public function getSQL();
  286. /**
  287. * Retrieves the associated EntityManager of this Query instance.
  288. *
  289. * @return EntityManagerInterface
  290. */
  291. public function getEntityManager()
  292. {
  293. return $this->_em;
  294. }
  296. /**
  297. * Frees the resources used by the query object.
  298. *
  299. * Resets Parameters, Parameter Types and Query Hints.
  300. *
  301. * @return void
  302. */
  303. public function free()
  304. {
  305. $this->parameters = new ArrayCollection();
  307. $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  308. }
  310. /**
  311. * Get all defined parameters.
  312. *
  313. * @return ArrayCollection The defined query parameters.
  314. * @psalm-return ArrayCollection<int, Parameter>
  315. */
  316. public function getParameters()
  317. {
  318. return $this->parameters;
  319. }
  321. /**
  322. * Gets a query parameter.
  323. *
  324. * @param int|string $key The key (index or name) of the bound parameter.
  325. *
  326. * @return Parameter|null The value of the bound parameter, or NULL if not available.
  327. */
  328. public function getParameter($key)
  329. {
  330. $key = Query\Parameter::normalizeName($key);
  332. $filteredParameters = $this->parameters->filter(
  333. static function (Query\Parameter $parameter) use ($key): bool {
  334. $parameterName = $parameter->getName();
  336. return $key === $parameterName;
  337. }
  338. );
  340. return ! $filteredParameters->isEmpty() ? $filteredParameters->first() : null;
  341. }
  343. /**
  344. * Sets a collection of query parameters.
  345. *
  346. * @param ArrayCollection|mixed[] $parameters
  347. * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
  348. *
  349. * @return $this
  350. */
  351. public function setParameters($parameters)
  352. {
  353. if (is_array($parameters)) {
  354. /** @psalm-var ArrayCollection<int, Parameter> $parameterCollection */
  355. $parameterCollection = new ArrayCollection();
  357. foreach ($parameters as $key => $value) {
  358. $parameterCollection->add(new Parameter($key, $value));
  359. }
  361. $parameters = $parameterCollection;
  362. }
  364. $this->parameters = $parameters;
  366. return $this;
  367. }
  369. /**
  370. * Sets a query parameter.
  371. *
  372. * @param string|int $key The parameter position or name.
  373. * @param mixed $value The parameter value.
  374. * @param string|int|null $type The parameter type. If specified, the given value will be run through
  375. * the type conversion of this type. This is usually not needed for
  376. * strings and numeric types.
  377. *
  378. * @return $this
  379. */
  380. public function setParameter($key, $value, $type = null)
  381. {
  382. $existingParameter = $this->getParameter($key);
  384. if ($existingParameter !== null) {
  385. $existingParameter->setValue($value, $type);
  387. return $this;
  388. }
  390. $this->parameters->add(new Parameter($key, $value, $type));
  392. return $this;
  393. }
  395. /**
  396. * Processes an individual parameter value.
  397. *
  398. * @param mixed $value
  399. *
  400. * @return mixed
  401. *
  402. * @throws ORMInvalidArgumentException
  403. */
  404. public function processParameterValue($value)
  405. {
  406. if (is_scalar($value)) {
  407. return $value;
  408. }
  410. if ($value instanceof Collection) {
  411. $value = iterator_to_array($value);
  412. }
  414. if (is_array($value)) {
  415. $value = $this->processArrayParameterValue($value);
  417. return $value;
  418. }
  420. if ($value instanceof Mapping\ClassMetadata) {
  421. return $value->name;
  422. }
  424. if ($value instanceof BackedEnum) {
  425. return $value->value;
  426. }
  428. if (! is_object($value)) {
  429. return $value;
  430. }
  432. try {
  433. $class = DefaultProxyClassNameResolver::getClass($value);
  434. $value = $this->_em->getUnitOfWork()->getSingleIdentifierValue($value);
  436. if ($value === null) {
  437. throw ORMInvalidArgumentException::invalidIdentifierBindingEntity($class);
  438. }
  439. } catch (MappingException | ORMMappingException $e) {
  440. /* Silence any mapping exceptions. These can occur if the object in
  441. question is not a mapped entity, in which case we just don't do
  442. any preparation on the value.
  443. Depending on MappingDriver, either MappingException or
  444. ORMMappingException is thrown. */
  446. $value = $this->potentiallyProcessIterable($value);
  447. }
  449. return $value;
  450. }
  452. /**
  453. * If no mapping is detected, trying to resolve the value as a Traversable
  454. *
  455. * @param mixed $value
  456. *
  457. * @return mixed
  458. */
  459. private function potentiallyProcessIterable($value)
  460. {
  461. if ($value instanceof Traversable) {
  462. $value = iterator_to_array($value);
  463. $value = $this->processArrayParameterValue($value);
  464. }
  466. return $value;
  467. }
  469. /**
  470. * Process a parameter value which was previously identified as an array
  471. *
  472. * @param mixed[] $value
  473. *
  474. * @return mixed[]
  475. */
  476. private function processArrayParameterValue(array $value): array
  477. {
  478. foreach ($value as $key => $paramValue) {
  479. $paramValue = $this->processParameterValue($paramValue);
  480. $value[$key] = is_array($paramValue) ? reset($paramValue) : $paramValue;
  481. }
  483. return $value;
  484. }
  486. /**
  487. * Sets the ResultSetMapping that should be used for hydration.
  488. *
  489. * @return $this
  490. */
  491. public function setResultSetMapping(Query\ResultSetMapping $rsm)
  492. {
  493. $this->translateNamespaces($rsm);
  494. $this->_resultSetMapping = $rsm;
  496. return $this;
  497. }
  499. /**
  500. * Gets the ResultSetMapping used for hydration.
  501. *
  502. * @return ResultSetMapping|null
  503. */
  504. protected function getResultSetMapping()
  505. {
  506. return $this->_resultSetMapping;
  507. }
  509. /**
  510. * Allows to translate entity namespaces to full qualified names.
  511. */
  512. private function translateNamespaces(Query\ResultSetMapping $rsm): void
  513. {
  514. $translate = function ($alias): string {
  515. return $this->_em->getClassMetadata($alias)->getName();
  516. };
  518. $rsm->aliasMap = array_map($translate, $rsm->aliasMap);
  519. $rsm->declaringClasses = array_map($translate, $rsm->declaringClasses);
  520. }
  522. /**
  523. * Set a cache profile for hydration caching.
  524. *
  525. * If no result cache driver is set in the QueryCacheProfile, the default
  526. * result cache driver is used from the configuration.
  527. *
  528. * Important: Hydration caching does NOT register entities in the
  529. * UnitOfWork when retrieved from the cache. Never use result cached
  530. * entities for requests that also flush the EntityManager. If you want
  531. * some form of caching with UnitOfWork registration you should use
  532. * {@see AbstractQuery::setResultCacheProfile()}.
  533. *
  534. * @return $this
  535. *
  536. * @example
  537. * $lifetime = 100;
  538. * $resultKey = "abc";
  539. * $query->setHydrationCacheProfile(new QueryCacheProfile());
  540. * $query->setHydrationCacheProfile(new QueryCacheProfile($lifetime, $resultKey));
  541. */
  542. public function setHydrationCacheProfile(?QueryCacheProfile $profile = null)
  543. {
  544. if ($profile === null) {
  545. if (func_num_args() < 1) {
  546. Deprecation::trigger(
  547. 'doctrine/orm',
  548. 'https://github.com/doctrine/orm/pull/9791',
  549. 'Calling %s without arguments is deprecated, pass null instead.',
  550. __METHOD__
  551. );
  552. }
  554. $this->_hydrationCacheProfile = null;
  556. return $this;
  557. }
  559. // DBAL 2
  560. if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  561. if (! $profile->getResultCacheDriver()) {
  562. $defaultHydrationCacheImpl = $this->_em->getConfiguration()->getHydrationCache();
  563. if ($defaultHydrationCacheImpl) {
  564. $profile = $profile->setResultCacheDriver(DoctrineProvider::wrap($defaultHydrationCacheImpl));
  565. }
  566. }
  567. } elseif (! $profile->getResultCache()) {
  568. $defaultHydrationCacheImpl = $this->_em->getConfiguration()->getHydrationCache();
  569. if ($defaultHydrationCacheImpl) {
  570. $profile = $profile->setResultCache($defaultHydrationCacheImpl);
  571. }
  572. }
  574. $this->_hydrationCacheProfile = $profile;
  576. return $this;
  577. }
  579. /** @return QueryCacheProfile|null */
  580. public function getHydrationCacheProfile()
  581. {
  582. return $this->_hydrationCacheProfile;
  583. }
  585. /**
  586. * Set a cache profile for the result cache.
  587. *
  588. * If no result cache driver is set in the QueryCacheProfile, the default
  589. * result cache driver is used from the configuration.
  590. *
  591. * @return $this
  592. */
  593. public function setResultCacheProfile(?QueryCacheProfile $profile = null)
  594. {
  595. if ($profile === null) {
  596. if (func_num_args() < 1) {
  597. Deprecation::trigger(
  598. 'doctrine/orm',
  599. 'https://github.com/doctrine/orm/pull/9791',
  600. 'Calling %s without arguments is deprecated, pass null instead.',
  601. __METHOD__
  602. );
  603. }
  605. $this->_queryCacheProfile = null;
  607. return $this;
  608. }
  610. // DBAL 2
  611. if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  612. if (! $profile->getResultCacheDriver()) {
  613. $defaultResultCacheDriver = $this->_em->getConfiguration()->getResultCache();
  614. if ($defaultResultCacheDriver) {
  615. $profile = $profile->setResultCacheDriver(DoctrineProvider::wrap($defaultResultCacheDriver));
  616. }
  617. }
  618. } elseif (! $profile->getResultCache()) {
  619. $defaultResultCache = $this->_em->getConfiguration()->getResultCache();
  620. if ($defaultResultCache) {
  621. $profile = $profile->setResultCache($defaultResultCache);
  622. }
  623. }
  625. $this->_queryCacheProfile = $profile;
  627. return $this;
  628. }
  630. /**
  631. * Defines a cache driver to be used for caching result sets and implicitly enables caching.
  632. *
  633. * @deprecated Use {@see setResultCache()} instead.
  634. *
  635. * @param \Doctrine\Common\Cache\Cache|null $resultCacheDriver Cache driver
  636. *
  637. * @return $this
  638. *
  639. * @throws InvalidResultCacheDriver
  640. */
  641. public function setResultCacheDriver($resultCacheDriver = null)
  642. {
  643. /** @phpstan-ignore-next-line */
  644. if ($resultCacheDriver !== null && ! ($resultCacheDriver instanceof \Doctrine\Common\Cache\Cache)) {
  645. throw InvalidResultCacheDriver::create();
  646. }
  648. return $this->setResultCache($resultCacheDriver ? CacheAdapter::wrap($resultCacheDriver) : null);
  649. }
  651. /**
  652. * Defines a cache driver to be used for caching result sets and implicitly enables caching.
  653. *
  654. * @return $this
  655. */
  656. public function setResultCache(?CacheItemPoolInterface $resultCache = null)
  657. {
  658. if ($resultCache === null) {
  659. if (func_num_args() < 1) {
  660. Deprecation::trigger(
  661. 'doctrine/orm',
  662. 'https://github.com/doctrine/orm/pull/9791',
  663. 'Calling %s without arguments is deprecated, pass null instead.',
  664. __METHOD__
  665. );
  666. }
  668. if ($this->_queryCacheProfile) {
  669. $this->_queryCacheProfile = new QueryCacheProfile($this->_queryCacheProfile->getLifetime(), $this->_queryCacheProfile->getCacheKey());
  670. }
  672. return $this;
  673. }
  675. // DBAL 2
  676. if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  677. $resultCacheDriver = DoctrineProvider::wrap($resultCache);
  679. $this->_queryCacheProfile = $this->_queryCacheProfile
  680. ? $this->_queryCacheProfile->setResultCacheDriver($resultCacheDriver)
  681. : new QueryCacheProfile(0, null, $resultCacheDriver);
  683. return $this;
  684. }
  686. $this->_queryCacheProfile = $this->_queryCacheProfile
  687. ? $this->_queryCacheProfile->setResultCache($resultCache)
  688. : new QueryCacheProfile(0, null, $resultCache);
  690. return $this;
  691. }
  693. /**
  694. * Returns the cache driver used for caching result sets.
  695. *
  696. * @deprecated
  697. *
  698. * @return \Doctrine\Common\Cache\Cache Cache driver
  699. */
  700. public function getResultCacheDriver()
  701. {
  702. if ($this->_queryCacheProfile && $this->_queryCacheProfile->getResultCacheDriver()) {
  703. return $this->_queryCacheProfile->getResultCacheDriver();
  704. }
  706. return $this->_em->getConfiguration()->getResultCacheImpl();
  707. }
  709. /**
  710. * Set whether or not to cache the results of this query and if so, for
  711. * how long and which ID to use for the cache entry.
  712. *
  713. * @deprecated 2.7 Use {@see enableResultCache} and {@see disableResultCache} instead.
  714. *
  715. * @param bool $useCache Whether or not to cache the results of this query.
  716. * @param int $lifetime How long the cache entry is valid, in seconds.
  717. * @param string $resultCacheId ID to use for the cache entry.
  718. *
  719. * @return $this
  720. */
  721. public function useResultCache($useCache, $lifetime = null, $resultCacheId = null)
  722. {
  723. return $useCache
  724. ? $this->enableResultCache($lifetime, $resultCacheId)
  725. : $this->disableResultCache();
  726. }
  728. /**
  729. * Enables caching of the results of this query, for given or default amount of seconds
  730. * and optionally specifies which ID to use for the cache entry.
  731. *
  732. * @param int|null $lifetime How long the cache entry is valid, in seconds.
  733. * @param string|null $resultCacheId ID to use for the cache entry.
  734. *
  735. * @return $this
  736. */
  737. public function enableResultCache(?int $lifetime = null, ?string $resultCacheId = null): self
  738. {
  739. $this->setResultCacheLifetime($lifetime);
  740. $this->setResultCacheId($resultCacheId);
  742. return $this;
  743. }
  745. /**
  746. * Disables caching of the results of this query.
  747. *
  748. * @return $this
  749. */
  750. public function disableResultCache(): self
  751. {
  752. $this->_queryCacheProfile = null;
  754. return $this;
  755. }
  757. /**
  758. * Defines how long the result cache will be active before expire.
  759. *
  760. * @param int|null $lifetime How long the cache entry is valid, in seconds.
  761. *
  762. * @return $this
  763. */
  764. public function setResultCacheLifetime($lifetime)
  765. {
  766. $lifetime = (int) $lifetime;
  768. if ($this->_queryCacheProfile) {
  769. $this->_queryCacheProfile = $this->_queryCacheProfile->setLifetime($lifetime);
  771. return $this;
  772. }
  774. $this->_queryCacheProfile = new QueryCacheProfile($lifetime);
  776. $cache = $this->_em->getConfiguration()->getResultCache();
  777. if (! $cache) {
  778. return $this;
  779. }
  781. // Compatibility for DBAL 2
  782. if (! method_exists($this->_queryCacheProfile, 'setResultCache')) {
  783. $this->_queryCacheProfile = $this->_queryCacheProfile->setResultCacheDriver(DoctrineProvider::wrap($cache));
  785. return $this;
  786. }
  788. $this->_queryCacheProfile = $this->_queryCacheProfile->setResultCache($cache);
  790. return $this;
  791. }
  793. /**
  794. * Retrieves the lifetime of resultset cache.
  795. *
  796. * @deprecated
  797. *
  798. * @return int
  799. */
  800. public function getResultCacheLifetime()
  801. {
  802. return $this->_queryCacheProfile ? $this->_queryCacheProfile->getLifetime() : 0;
  803. }
  805. /**
  806. * Defines if the result cache is active or not.
  807. *
  808. * @param bool $expire Whether or not to force resultset cache expiration.
  809. *
  810. * @return $this
  811. */
  812. public function expireResultCache($expire = true)
  813. {
  814. $this->_expireResultCache = $expire;
  816. return $this;
  817. }
  819. /**
  820. * Retrieves if the resultset cache is active or not.
  821. *
  822. * @return bool
  823. */
  824. public function getExpireResultCache()
  825. {
  826. return $this->_expireResultCache;
  827. }
  829. /** @return QueryCacheProfile|null */
  830. public function getQueryCacheProfile()
  831. {
  832. return $this->_queryCacheProfile;
  833. }
  835. /**
  836. * Change the default fetch mode of an association for this query.
  837. *
  838. * @param class-string $class
  839. * @param string $assocName
  840. * @param int $fetchMode
  841. * @psalm-param Mapping\ClassMetadata::FETCH_EAGER|Mapping\ClassMetadata::FETCH_LAZY $fetchMode
  842. *
  843. * @return $this
  844. */
  845. public function setFetchMode($class, $assocName, $fetchMode)
  846. {
  847. if (! in_array($fetchMode, [Mapping\ClassMetadata::FETCH_EAGER, Mapping\ClassMetadata::FETCH_LAZY], true)) {
  848. Deprecation::trigger(
  849. 'doctrine/orm',
  850. 'https://github.com/doctrine/orm/pull/9777',
  851. 'Calling %s() with something else than ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY is deprecated.',
  852. __METHOD__
  853. );
  854. $fetchMode = Mapping\ClassMetadata::FETCH_LAZY;
  855. }
  857. $this->_hints['fetchMode'][$class][$assocName] = $fetchMode;
  859. return $this;
  860. }
  862. /**
  863. * Defines the processing mode to be used during hydration / result set transformation.
  864. *
  865. * @param string|int $hydrationMode Doctrine processing mode to be used during hydration process.
  866. * One of the Query::HYDRATE_* constants.
  867. * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
  868. *
  869. * @return $this
  870. */
  871. public function setHydrationMode($hydrationMode)
  872. {
  873. $this->_hydrationMode = $hydrationMode;
  875. return $this;
  876. }
  878. /**
  879. * Gets the hydration mode currently used by the query.
  880. *
  881. * @return string|int
  882. * @psalm-return string|AbstractQuery::HYDRATE_*
  883. */
  884. public function getHydrationMode()
  885. {
  886. return $this->_hydrationMode;
  887. }
  889. /**
  890. * Gets the list of results for the query.
  891. *
  892. * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).
  893. *
  894. * @param string|int $hydrationMode
  895. * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
  896. *
  897. * @return mixed
  898. */
  899. public function getResult($hydrationMode = self::HYDRATE_OBJECT)
  900. {
  901. return $this->execute(null, $hydrationMode);
  902. }
  904. /**
  905. * Gets the array of results for the query.
  906. *
  907. * Alias for execute(null, HYDRATE_ARRAY).
  908. *
  909. * @return mixed[]
  910. */
  911. public function getArrayResult()
  912. {
  913. return $this->execute(null, self::HYDRATE_ARRAY);
  914. }
  916. /**
  917. * Gets one-dimensional array of results for the query.
  918. *
  919. * Alias for execute(null, HYDRATE_SCALAR_COLUMN).
  920. *
  921. * @return mixed[]
  922. */
  923. public function getSingleColumnResult()
  924. {
  925. return $this->execute(null, self::HYDRATE_SCALAR_COLUMN);
  926. }
  928. /**
  929. * Gets the scalar results for the query.
  930. *
  931. * Alias for execute(null, HYDRATE_SCALAR).
  932. *
  933. * @return mixed[]
  934. */
  935. public function getScalarResult()
  936. {
  937. return $this->execute(null, self::HYDRATE_SCALAR);
  938. }
  940. /**
  941. * Get exactly one result or null.
  942. *
  943. * @param string|int|null $hydrationMode
  944. * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  945. *
  946. * @return mixed
  947. *
  948. * @throws NonUniqueResultException
  949. */
  950. public function getOneOrNullResult($hydrationMode = null)
  951. {
  952. try {
  953. $result = $this->execute(null, $hydrationMode);
  954. } catch (NoResultException $e) {
  955. return null;
  956. }
  958. if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  959. return null;
  960. }
  962. if (! is_array($result)) {
  963. return $result;
  964. }
  966. if (count($result) > 1) {
  967. throw new NonUniqueResultException();
  968. }
  970. return array_shift($result);
  971. }
  973. /**
  974. * Gets the single result of the query.
  975. *
  976. * Enforces the presence as well as the uniqueness of the result.
  977. *
  978. * If the result is not unique, a NonUniqueResultException is thrown.
  979. * If there is no result, a NoResultException is thrown.
  980. *
  981. * @param string|int|null $hydrationMode
  982. * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  983. *
  984. * @return mixed
  985. *
  986. * @throws NonUniqueResultException If the query result is not unique.
  987. * @throws NoResultException If the query returned no result.
  988. */
  989. public function getSingleResult($hydrationMode = null)
  990. {
  991. $result = $this->execute(null, $hydrationMode);
  993. if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  994. throw new NoResultException();
  995. }
  997. if (! is_array($result)) {
  998. return $result;
  999. }
  1001. if (count($result) > 1) {
  1002. throw new NonUniqueResultException();
  1003. }
  1005. return array_shift($result);
  1006. }
  1008. /**
  1009. * Gets the single scalar result of the query.
  1010. *
  1011. * Alias for getSingleResult(HYDRATE_SINGLE_SCALAR).
  1012. *
  1013. * @return bool|float|int|string|null The scalar result.
  1014. *
  1015. * @throws NoResultException If the query returned no result.
  1016. * @throws NonUniqueResultException If the query result is not unique.
  1017. */
  1018. public function getSingleScalarResult()
  1019. {
  1020. return $this->getSingleResult(self::HYDRATE_SINGLE_SCALAR);
  1021. }
  1023. /**
  1024. * Sets a query hint. If the hint name is not recognized, it is silently ignored.
  1025. *
  1026. * @param string $name The name of the hint.
  1027. * @param mixed $value The value of the hint.
  1028. *
  1029. * @return $this
  1030. */
  1031. public function setHint($name, $value)
  1032. {
  1033. $this->_hints[$name] = $value;
  1035. return $this;
  1036. }
  1038. /**
  1039. * Gets the value of a query hint. If the hint name is not recognized, FALSE is returned.
  1040. *
  1041. * @param string $name The name of the hint.
  1042. *
  1043. * @return mixed The value of the hint or FALSE, if the hint name is not recognized.
  1044. */
  1045. public function getHint($name)
  1046. {
  1047. return $this->_hints[$name] ?? false;
  1048. }
  1050. /**
  1051. * Check if the query has a hint
  1052. *
  1053. * @param string $name The name of the hint
  1054. *
  1055. * @return bool False if the query does not have any hint
  1056. */
  1057. public function hasHint($name)
  1058. {
  1059. return isset($this->_hints[$name]);
  1060. }
  1062. /**
  1063. * Return the key value map of query hints that are currently set.
  1064. *
  1065. * @return array<string,mixed>
  1066. */
  1067. public function getHints()
  1068. {
  1069. return $this->_hints;
  1070. }
  1072. /**
  1073. * Executes the query and returns an IterableResult that can be used to incrementally
  1074. * iterate over the result.
  1075. *
  1076. * @deprecated 2.8 Use {@see toIterable} instead. See https://github.com/doctrine/orm/issues/8463
  1077. *
  1078. * @param ArrayCollection|mixed[]|null $parameters The query parameters.
  1079. * @param string|int|null $hydrationMode The hydration mode to use.
  1080. * @psalm-param ArrayCollection<int, Parameter>|array<string, mixed>|null $parameters
  1081. * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode The hydration mode to use.
  1082. *
  1083. * @return IterableResult
  1084. */
  1085. public function iterate($parameters = null, $hydrationMode = null)
  1086. {
  1087. Deprecation::trigger(
  1088. 'doctrine/orm',
  1089. 'https://github.com/doctrine/orm/issues/8463',
  1090. 'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use toIterable() instead.',
  1091. __METHOD__
  1092. );
  1094. if ($hydrationMode !== null) {
  1095. $this->setHydrationMode($hydrationMode);
  1096. }
  1098. if (! empty($parameters)) {
  1099. $this->setParameters($parameters);
  1100. }
  1102. $rsm = $this->getResultSetMapping();
  1103. if ($rsm === null) {
  1104. throw new LogicException('Uninitialized result set mapping.');
  1105. }
  1107. $stmt = $this->_doExecute();
  1109. return $this->_em->newHydrator($this->_hydrationMode)->iterate($stmt, $rsm, $this->_hints);
  1110. }
  1112. /**
  1113. * Executes the query and returns an iterable that can be used to incrementally
  1114. * iterate over the result.
  1115. *
  1116. * @param ArrayCollection|array|mixed[] $parameters The query parameters.
  1117. * @param string|int|null $hydrationMode The hydration mode to use.
  1118. * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
  1119. * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  1120. *
  1121. * @return iterable<mixed>
  1122. */
  1123. public function toIterable(iterable $parameters = [], $hydrationMode = null): iterable
  1124. {
  1125. if ($hydrationMode !== null) {
  1126. $this->setHydrationMode($hydrationMode);
  1127. }
  1129. if (
  1130. ($this->isCountable($parameters) && count($parameters) !== 0)
  1131. || ($parameters instanceof Traversable && iterator_count($parameters) !== 0)
  1132. ) {
  1133. $this->setParameters($parameters);
  1134. }
  1136. $rsm = $this->getResultSetMapping();
  1137. if ($rsm === null) {
  1138. throw new LogicException('Uninitialized result set mapping.');
  1139. }
  1141. if ($rsm->isMixed && count($rsm->scalarMappings) > 0) {
  1142. throw QueryException::iterateWithMixedResultNotAllowed();
  1143. }
  1145. $stmt = $this->_doExecute();
  1147. return $this->_em->newHydrator($this->_hydrationMode)->toIterable($stmt, $rsm, $this->_hints);
  1148. }
  1150. /**
  1151. * Executes the query.
  1152. *
  1153. * @param ArrayCollection|mixed[]|null $parameters Query parameters.
  1154. * @param string|int|null $hydrationMode Processing mode to be used during the hydration process.
  1155. * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1156. * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  1157. *
  1158. * @return mixed
  1159. */
  1160. public function execute($parameters = null, $hydrationMode = null)
  1161. {
  1162. if ($this->cacheable && $this->isCacheEnabled()) {
  1163. return $this->executeUsingQueryCache($parameters, $hydrationMode);
  1164. }
  1166. return $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1167. }
  1169. /**
  1170. * Execute query ignoring second level cache.
  1171. *
  1172. * @param ArrayCollection|mixed[]|null $parameters
  1173. * @param string|int|null $hydrationMode
  1174. * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1175. * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  1176. *
  1177. * @return mixed
  1178. */
  1179. private function executeIgnoreQueryCache($parameters = null, $hydrationMode = null)
  1180. {
  1181. if ($hydrationMode !== null) {
  1182. $this->setHydrationMode($hydrationMode);
  1183. }
  1185. if (! empty($parameters)) {
  1186. $this->setParameters($parameters);
  1187. }
  1189. $setCacheEntry = static function ($data): void {
  1190. };
  1192. if ($this->_hydrationCacheProfile !== null) {
  1193. [$cacheKey, $realCacheKey] = $this->getHydrationCacheId();
  1195. $cache = $this->getHydrationCache();
  1196. $cacheItem = $cache->getItem($cacheKey);
  1197. $result = $cacheItem->isHit() ? $cacheItem->get() : [];
  1199. if (isset($result[$realCacheKey])) {
  1200. return $result[$realCacheKey];
  1201. }
  1203. if (! $result) {
  1204. $result = [];
  1205. }
  1207. $setCacheEntry = static function ($data) use ($cache, $result, $cacheItem, $realCacheKey): void {
  1208. $cache->save($cacheItem->set($result + [$realCacheKey => $data]));
  1209. };
  1210. }
  1212. $stmt = $this->_doExecute();
  1214. if (is_numeric($stmt)) {
  1215. $setCacheEntry($stmt);
  1217. return $stmt;
  1218. }
  1220. $rsm = $this->getResultSetMapping();
  1221. if ($rsm === null) {
  1222. throw new LogicException('Uninitialized result set mapping.');
  1223. }
  1225. $data = $this->_em->newHydrator($this->_hydrationMode)->hydrateAll($stmt, $rsm, $this->_hints);
  1227. $setCacheEntry($data);
  1229. return $data;
  1230. }
  1232. private function getHydrationCache(): CacheItemPoolInterface
  1233. {
  1234. assert($this->_hydrationCacheProfile !== null);
  1236. // Support for DBAL 2
  1237. if (! method_exists($this->_hydrationCacheProfile, 'getResultCache')) {
  1238. $cacheDriver = $this->_hydrationCacheProfile->getResultCacheDriver();
  1239. assert($cacheDriver !== null);
  1241. return CacheAdapter::wrap($cacheDriver);
  1242. }
  1244. $cache = $this->_hydrationCacheProfile->getResultCache();
  1245. assert($cache !== null);
  1247. return $cache;
  1248. }
  1250. /**
  1251. * Load from second level cache or executes the query and put into cache.
  1252. *
  1253. * @param ArrayCollection|mixed[]|null $parameters
  1254. * @param string|int|null $hydrationMode
  1255. * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1256. * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  1257. *
  1258. * @return mixed
  1259. */
  1260. private function executeUsingQueryCache($parameters = null, $hydrationMode = null)
  1261. {
  1262. $rsm = $this->getResultSetMapping();
  1263. if ($rsm === null) {
  1264. throw new LogicException('Uninitialized result set mapping.');
  1265. }
  1267. $queryCache = $this->_em->getCache()->getQueryCache($this->cacheRegion);
  1268. $queryKey = new QueryCacheKey(
  1269. $this->getHash(),
  1270. $this->lifetime,
  1271. $this->cacheMode ?: Cache::MODE_NORMAL,
  1272. $this->getTimestampKey()
  1273. );
  1275. $result = $queryCache->get($queryKey, $rsm, $this->_hints);
  1277. if ($result !== null) {
  1278. if ($this->cacheLogger) {
  1279. $this->cacheLogger->queryCacheHit($queryCache->getRegion()->getName(), $queryKey);
  1280. }
  1282. return $result;
  1283. }
  1285. $result = $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1286. $cached = $queryCache->put($queryKey, $rsm, $result, $this->_hints);
  1288. if ($this->cacheLogger) {
  1289. $this->cacheLogger->queryCacheMiss($queryCache->getRegion()->getName(), $queryKey);
  1291. if ($cached) {
  1292. $this->cacheLogger->queryCachePut($queryCache->getRegion()->getName(), $queryKey);
  1293. }
  1294. }
  1296. return $result;
  1297. }
  1299. private function getTimestampKey(): ?TimestampCacheKey
  1300. {
  1301. assert($this->_resultSetMapping !== null);
  1302. $entityName = reset($this->_resultSetMapping->aliasMap);
  1304. if (empty($entityName)) {
  1305. return null;
  1306. }
  1308. $metadata = $this->_em->getClassMetadata($entityName);
  1310. return new Cache\TimestampCacheKey($metadata->rootEntityName);
  1311. }
  1313. /**
  1314. * Get the result cache id to use to store the result set cache entry.
  1315. * Will return the configured id if it exists otherwise a hash will be
  1316. * automatically generated for you.
  1317. *
  1318. * @return string[] ($key, $hash)
  1319. * @psalm-return array{string, string} ($key, $hash)
  1320. */
  1321. protected function getHydrationCacheId()
  1322. {
  1323. $parameters = [];
  1324. $types = [];
  1326. foreach ($this->getParameters() as $parameter) {
  1327. $parameters[$parameter->getName()] = $this->processParameterValue($parameter->getValue());
  1328. $types[$parameter->getName()] = $parameter->getType();
  1329. }
  1331. $sql = $this->getSQL();
  1332. assert(is_string($sql));
  1333. $queryCacheProfile = $this->getHydrationCacheProfile();
  1334. $hints = $this->getHints();
  1335. $hints['hydrationMode'] = $this->getHydrationMode();
  1337. ksort($hints);
  1338. assert($queryCacheProfile !== null);
  1340. return $queryCacheProfile->generateCacheKeys($sql, $parameters, $types, $hints);
  1341. }
  1343. /**
  1344. * Set the result cache id to use to store the result set cache entry.
  1345. * If this is not explicitly set by the developer then a hash is automatically
  1346. * generated for you.
  1347. *
  1348. * @param string|null $id
  1349. *
  1350. * @return $this
  1351. */
  1352. public function setResultCacheId($id)
  1353. {
  1354. if (! $this->_queryCacheProfile) {
  1355. return $this->setResultCacheProfile(new QueryCacheProfile(0, $id));
  1356. }
  1358. $this->_queryCacheProfile = $this->_queryCacheProfile->setCacheKey($id);
  1360. return $this;
  1361. }
  1363. /**
  1364. * Get the result cache id to use to store the result set cache entry if set.
  1365. *
  1366. * @deprecated
  1367. *
  1368. * @return string|null
  1369. */
  1370. public function getResultCacheId()
  1371. {
  1372. return $this->_queryCacheProfile ? $this->_queryCacheProfile->getCacheKey() : null;
  1373. }
  1375. /**
  1376. * Executes the query and returns a the resulting Statement object.
  1377. *
  1378. * @return Result|int The executed database statement that holds
  1379. * the results, or an integer indicating how
  1380. * many rows were affected.
  1381. */
  1382. abstract protected function _doExecute();
  1384. /**
  1385. * Cleanup Query resource when clone is called.
  1386. *
  1387. * @return void
  1388. */
  1389. public function __clone()
  1390. {
  1391. $this->parameters = new ArrayCollection();
  1393. $this->_hints = [];
  1394. $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  1395. }
  1397. /**
  1398. * Generates a string of currently query to use for the cache second level cache.
  1399. *
  1400. * @return string
  1401. */
  1402. protected function getHash()
  1403. {
  1404. $query = $this->getSQL();
  1405. assert(is_string($query));
  1406. $hints = $this->getHints();
  1407. $params = array_map(function (Parameter $parameter) {
  1408. $value = $parameter->getValue();
  1410. // Small optimization
  1411. // Does not invoke processParameterValue for scalar value
  1412. if (is_scalar($value)) {
  1413. return $value;
  1414. }
  1416. return $this->processParameterValue($value);
  1417. }, $this->parameters->getValues());
  1419. ksort($hints);
  1421. return sha1($query . '-' . serialize($params) . '-' . serialize($hints));
  1422. }
  1424. /** @param iterable<mixed> $subject */
  1425. private function isCountable(iterable $subject): bool
  1426. {
  1427. return $subject instanceof Countable || is_array($subject);
  1428. }
  1429. }