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

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\ResultSetMapping;
  25. use Doctrine\Persistence\Mapping\MappingException;
  26. use LogicException;
  27. use Psr\Cache\CacheItemPoolInterface;
  28. use Traversable;
  30. use function array_map;
  31. use function array_shift;
  32. use function assert;
  33. use function count;
  34. use function func_num_args;
  35. use function in_array;
  36. use function is_array;
  37. use function is_numeric;
  38. use function is_object;
  39. use function is_scalar;
  40. use function is_string;
  41. use function iterator_count;
  42. use function iterator_to_array;
  43. use function ksort;
  44. use function method_exists;
  45. use function reset;
  46. use function serialize;
  47. use function sha1;
  49. /**
  50. * Base contract for ORM queries. Base class for Query and NativeQuery.
  51. *
  52. * @link www.doctrine-project.org
  53. */
  54. abstract class AbstractQuery
  55. {
  56. /* Hydration mode constants */
  58. /**
  59. * Hydrates an object graph. This is the default behavior.
  60. */
  61. public const HYDRATE_OBJECT = 1;
  63. /**
  64. * Hydrates an array graph.
  65. */
  66. public const HYDRATE_ARRAY = 2;
  68. /**
  69. * Hydrates a flat, rectangular result set with scalar values.
  70. */
  71. public const HYDRATE_SCALAR = 3;
  73. /**
  74. * Hydrates a single scalar value.
  75. */
  76. public const HYDRATE_SINGLE_SCALAR = 4;
  78. /**
  79. * Very simple object hydrator (optimized for performance).
  80. */
  81. public const HYDRATE_SIMPLEOBJECT = 5;
  83. /**
  84. * Hydrates scalar column value.
  85. */
  86. public const HYDRATE_SCALAR_COLUMN = 6;
  88. /**
  89. * The parameter map of this query.
  90. *
  91. * @var ArrayCollection|Parameter[]
  92. * @phpstan-var ArrayCollection<int, Parameter>
  93. */
  94. protected $parameters;
  96. /**
  97. * The user-specified ResultSetMapping to use.
  98. *
  99. * @var ResultSetMapping|null
  100. */
  101. protected $_resultSetMapping;
  103. /**
  104. * The entity manager used by this query object.
  105. *
  106. * @var EntityManagerInterface
  107. */
  108. protected $_em;
  110. /**
  111. * The map of query hints.
  112. *
  113. * @phpstan-var array<string, mixed>
  114. */
  115. protected $_hints = [];
  117. /**
  118. * The hydration mode.
  119. *
  120. * @var string|int
  121. * @phpstan-var string|AbstractQuery::HYDRATE_*
  122. */
  123. protected $_hydrationMode = self::HYDRATE_OBJECT;
  125. /** @var QueryCacheProfile|null */
  126. protected $_queryCacheProfile;
  128. /**
  129. * Whether or not expire the result cache.
  130. *
  131. * @var bool
  132. */
  133. protected $_expireResultCache = false;
  135. /** @var QueryCacheProfile|null */
  136. protected $_hydrationCacheProfile;
  138. /**
  139. * Whether to use second level cache, if available.
  140. *
  141. * @var bool
  142. */
  143. protected $cacheable = false;
  145. /** @var bool */
  146. protected $hasCache = false;
  148. /**
  149. * Second level cache region name.
  150. *
  151. * @var string|null
  152. */
  153. protected $cacheRegion;
  155. /**
  156. * Second level query cache mode.
  157. *
  158. * @var int|null
  159. * @phpstan-var Cache::MODE_*|null
  160. */
  161. protected $cacheMode;
  163. /** @var CacheLogger|null */
  164. protected $cacheLogger;
  166. /** @var int */
  167. protected $lifetime = 0;
  169. /**
  170. * Initializes a new instance of a class derived from <tt>AbstractQuery</tt>.
  171. */
  172. public function __construct(EntityManagerInterface $em)
  173. {
  174. $this->_em = $em;
  175. $this->parameters = new ArrayCollection();
  176. $this->_hints = $em->getConfiguration()->getDefaultQueryHints();
  177. $this->hasCache = $this->_em->getConfiguration()->isSecondLevelCacheEnabled();
  179. if ($this->hasCache) {
  180. $this->cacheLogger = $em->getConfiguration()
  181. ->getSecondLevelCacheConfiguration()
  182. ->getCacheLogger();
  183. }
  184. }
  186. /**
  187. * Enable/disable second level query (result) caching for this query.
  188. *
  189. * @param bool $cacheable
  190. *
  191. * @return $this
  192. */
  193. public function setCacheable($cacheable)
  194. {
  195. $this->cacheable = (bool) $cacheable;
  197. return $this;
  198. }
  200. /** @return bool TRUE if the query results are enabled for second level cache, FALSE otherwise. */
  201. public function isCacheable()
  202. {
  203. return $this->cacheable;
  204. }
  206. /**
  207. * @param string $cacheRegion
  208. *
  209. * @return $this
  210. */
  211. public function setCacheRegion($cacheRegion)
  212. {
  213. $this->cacheRegion = (string) $cacheRegion;
  215. return $this;
  216. }
  218. /**
  219. * Obtain the name of the second level query cache region in which query results will be stored
  220. *
  221. * @return string|null The cache region name; NULL indicates the default region.
  222. */
  223. public function getCacheRegion()
  224. {
  225. return $this->cacheRegion;
  226. }
  228. /** @return bool TRUE if the query cache and second level cache are enabled, FALSE otherwise. */
  229. protected function isCacheEnabled()
  230. {
  231. return $this->cacheable && $this->hasCache;
  232. }
  234. /** @return int */
  235. public function getLifetime()
  236. {
  237. return $this->lifetime;
  238. }
  240. /**
  241. * Sets the life-time for this query into second level cache.
  242. *
  243. * @param int $lifetime
  244. *
  245. * @return $this
  246. */
  247. public function setLifetime($lifetime)
  248. {
  249. $this->lifetime = (int) $lifetime;
  251. return $this;
  252. }
  254. /**
  255. * @return int|null
  256. * @phpstan-return Cache::MODE_*|null
  257. */
  258. public function getCacheMode()
  259. {
  260. return $this->cacheMode;
  261. }
  263. /**
  264. * @param int $cacheMode
  265. * @phpstan-param Cache::MODE_* $cacheMode
  266. *
  267. * @return $this
  268. */
  269. public function setCacheMode($cacheMode)
  270. {
  271. $this->cacheMode = (int) $cacheMode;
  273. return $this;
  274. }
  276. /**
  277. * Gets the SQL query that corresponds to this query object.
  278. * The returned SQL syntax depends on the connection driver that is used
  279. * by this query object at the time of this method call.
  280. *
  281. * @return list<string>|string SQL query
  282. */
  283. abstract public function getSQL();
  285. /**
  286. * Retrieves the associated EntityManager of this Query instance.
  287. *
  288. * @return EntityManagerInterface
  289. */
  290. public function getEntityManager()
  291. {
  292. return $this->_em;
  293. }
  295. /**
  296. * Frees the resources used by the query object.
  297. *
  298. * Resets Parameters, Parameter Types and Query Hints.
  299. *
  300. * @return void
  301. */
  302. public function free()
  303. {
  304. $this->parameters = new ArrayCollection();
  306. $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  307. }
  309. /**
  310. * Get all defined parameters.
  311. *
  312. * @return ArrayCollection The defined query parameters.
  313. * @phpstan-return ArrayCollection<int, Parameter>
  314. */
  315. public function getParameters()
  316. {
  317. return $this->parameters;
  318. }
  320. /**
  321. * Gets a query parameter.
  322. *
  323. * @param int|string $key The key (index or name) of the bound parameter.
  324. *
  325. * @return Parameter|null The value of the bound parameter, or NULL if not available.
  326. */
  327. public function getParameter($key)
  328. {
  329. $key = Query\Parameter::normalizeName($key);
  331. $filteredParameters = $this->parameters->filter(
  332. static function (Query\Parameter $parameter) use ($key): bool {
  333. $parameterName = $parameter->getName();
  335. return $key === $parameterName;
  336. }
  337. );
  339. return ! $filteredParameters->isEmpty() ? $filteredParameters->first() : null;
  340. }
  342. /**
  343. * Sets a collection of query parameters.
  344. *
  345. * @param ArrayCollection|mixed[] $parameters
  346. * @phpstan-param ArrayCollection<int, Parameter>|mixed[] $parameters
  347. *
  348. * @return $this
  349. */
  350. public function setParameters($parameters)
  351. {
  352. if (is_array($parameters)) {
  353. /** @phpstan-var ArrayCollection<int, Parameter> $parameterCollection */
  354. $parameterCollection = new ArrayCollection();
  356. foreach ($parameters as $key => $value) {
  357. $parameterCollection->add(new Parameter($key, $value));
  358. }
  360. $parameters = $parameterCollection;
  361. }
  363. $this->parameters = $parameters;
  365. return $this;
  366. }
  368. /**
  369. * Sets a query parameter.
  370. *
  371. * @param string|int $key The parameter position or name.
  372. * @param mixed $value The parameter value.
  373. * @param string|int|null $type The parameter type. If specified, the given value will be run through
  374. * the type conversion of this type. This is usually not needed for
  375. * strings and numeric types.
  376. *
  377. * @return $this
  378. */
  379. public function setParameter($key, $value, $type = null)
  380. {
  381. $existingParameter = $this->getParameter($key);
  383. if ($existingParameter !== null) {
  384. $existingParameter->setValue($value, $type);
  386. return $this;
  387. }
  389. $this->parameters->add(new Parameter($key, $value, $type));
  391. return $this;
  392. }
  394. /**
  395. * Processes an individual parameter value.
  396. *
  397. * @param mixed $value
  398. *
  399. * @return mixed
  400. *
  401. * @throws ORMInvalidArgumentException
  402. */
  403. public function processParameterValue($value)
  404. {
  405. if (is_scalar($value)) {
  406. return $value;
  407. }
  409. if ($value instanceof Collection) {
  410. $value = iterator_to_array($value);
  411. }
  413. if (is_array($value)) {
  414. $value = $this->processArrayParameterValue($value);
  416. return $value;
  417. }
  419. if ($value instanceof Mapping\ClassMetadata) {
  420. return $value->name;
  421. }
  423. if ($value instanceof BackedEnum) {
  424. return $value->value;
  425. }
  427. if (! is_object($value)) {
  428. return $value;
  429. }
  431. try {
  432. $class = DefaultProxyClassNameResolver::getClass($value);
  433. $value = $this->_em->getUnitOfWork()->getSingleIdentifierValue($value);
  435. if ($value === null) {
  436. throw ORMInvalidArgumentException::invalidIdentifierBindingEntity($class);
  437. }
  438. } catch (MappingException | ORMMappingException $e) {
  439. /* Silence any mapping exceptions. These can occur if the object in
  440. question is not a mapped entity, in which case we just don't do
  441. any preparation on the value.
  442. Depending on MappingDriver, either MappingException or
  443. ORMMappingException is thrown. */
  445. $value = $this->potentiallyProcessIterable($value);
  446. }
  448. return $value;
  449. }
  451. /**
  452. * If no mapping is detected, trying to resolve the value as a Traversable
  453. *
  454. * @param mixed $value
  455. *
  456. * @return mixed
  457. */
  458. private function potentiallyProcessIterable($value)
  459. {
  460. if ($value instanceof Traversable) {
  461. $value = iterator_to_array($value);
  462. $value = $this->processArrayParameterValue($value);
  463. }
  465. return $value;
  466. }
  468. /**
  469. * Process a parameter value which was previously identified as an array
  470. *
  471. * @param mixed[] $value
  472. *
  473. * @return mixed[]
  474. */
  475. private function processArrayParameterValue(array $value): array
  476. {
  477. foreach ($value as $key => $paramValue) {
  478. $paramValue = $this->processParameterValue($paramValue);
  479. $value[$key] = is_array($paramValue) ? reset($paramValue) : $paramValue;
  480. }
  482. return $value;
  483. }
  485. /**
  486. * Sets the ResultSetMapping that should be used for hydration.
  487. *
  488. * @return $this
  489. */
  490. public function setResultSetMapping(Query\ResultSetMapping $rsm)
  491. {
  492. $this->translateNamespaces($rsm);
  493. $this->_resultSetMapping = $rsm;
  495. return $this;
  496. }
  498. /**
  499. * Gets the ResultSetMapping used for hydration.
  500. *
  501. * @return ResultSetMapping|null
  502. */
  503. protected function getResultSetMapping()
  504. {
  505. return $this->_resultSetMapping;
  506. }
  508. /**
  509. * Allows to translate entity namespaces to full qualified names.
  510. */
  511. private function translateNamespaces(Query\ResultSetMapping $rsm): void
  512. {
  513. $translate = function ($alias): string {
  514. return $this->_em->getClassMetadata($alias)->getName();
  515. };
  517. $rsm->aliasMap = array_map($translate, $rsm->aliasMap);
  518. $rsm->declaringClasses = array_map($translate, $rsm->declaringClasses);
  519. }
  521. /**
  522. * Set a cache profile for hydration caching.
  523. *
  524. * If no result cache driver is set in the QueryCacheProfile, the default
  525. * result cache driver is used from the configuration.
  526. *
  527. * Important: Hydration caching does NOT register entities in the
  528. * UnitOfWork when retrieved from the cache. Never use result cached
  529. * entities for requests that also flush the EntityManager. If you want
  530. * some form of caching with UnitOfWork registration you should use
  531. * {@see AbstractQuery::setResultCacheProfile()}.
  532. *
  533. * @return $this
  534. *
  535. * @example
  536. * $lifetime = 100;
  537. * $resultKey = "abc";
  538. * $query->setHydrationCacheProfile(new QueryCacheProfile());
  539. * $query->setHydrationCacheProfile(new QueryCacheProfile($lifetime, $resultKey));
  540. */
  541. public function setHydrationCacheProfile(?QueryCacheProfile $profile = null)
  542. {
  543. if ($profile === null) {
  544. if (func_num_args() < 1) {
  545. Deprecation::trigger(
  546. 'doctrine/orm',
  547. 'https://github.com/doctrine/orm/pull/9791',
  548. 'Calling %s without arguments is deprecated, pass null instead.',
  549. __METHOD__
  550. );
  551. }
  553. $this->_hydrationCacheProfile = null;
  555. return $this;
  556. }
  558. // DBAL 2
  559. if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  560. // @phpstan-ignore method.deprecated
  561. if (! $profile->getResultCacheDriver()) {
  562. $defaultHydrationCacheImpl = $this->_em->getConfiguration()->getHydrationCache();
  563. if ($defaultHydrationCacheImpl) {
  564. // @phpstan-ignore method.deprecated
  565. $profile = $profile->setResultCacheDriver(DoctrineProvider::wrap($defaultHydrationCacheImpl));
  566. }
  567. }
  568. } elseif (! $profile->getResultCache()) {
  569. $defaultHydrationCacheImpl = $this->_em->getConfiguration()->getHydrationCache();
  570. if ($defaultHydrationCacheImpl) {
  571. $profile = $profile->setResultCache($defaultHydrationCacheImpl);
  572. }
  573. }
  575. $this->_hydrationCacheProfile = $profile;
  577. return $this;
  578. }
  580. /** @return QueryCacheProfile|null */
  581. public function getHydrationCacheProfile()
  582. {
  583. return $this->_hydrationCacheProfile;
  584. }
  586. /**
  587. * Set a cache profile for the result cache.
  588. *
  589. * If no result cache driver is set in the QueryCacheProfile, the default
  590. * result cache driver is used from the configuration.
  591. *
  592. * @return $this
  593. */
  594. public function setResultCacheProfile(?QueryCacheProfile $profile = null)
  595. {
  596. if ($profile === null) {
  597. if (func_num_args() < 1) {
  598. Deprecation::trigger(
  599. 'doctrine/orm',
  600. 'https://github.com/doctrine/orm/pull/9791',
  601. 'Calling %s without arguments is deprecated, pass null instead.',
  602. __METHOD__
  603. );
  604. }
  606. $this->_queryCacheProfile = null;
  608. return $this;
  609. }
  611. // DBAL 2
  612. if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  613. // @phpstan-ignore method.deprecated
  614. if (! $profile->getResultCacheDriver()) {
  615. $defaultResultCacheDriver = $this->_em->getConfiguration()->getResultCache();
  616. if ($defaultResultCacheDriver) {
  617. // @phpstan-ignore method.deprecated
  618. $profile = $profile->setResultCacheDriver(DoctrineProvider::wrap($defaultResultCacheDriver));
  619. }
  620. }
  621. } elseif (! $profile->getResultCache()) {
  622. $defaultResultCache = $this->_em->getConfiguration()->getResultCache();
  623. if ($defaultResultCache) {
  624. $profile = $profile->setResultCache($defaultResultCache);
  625. }
  626. }
  628. $this->_queryCacheProfile = $profile;
  630. return $this;
  631. }
  633. /**
  634. * Defines a cache driver to be used for caching result sets and implicitly enables caching.
  635. *
  636. * @deprecated Use {@see setResultCache()} instead.
  637. *
  638. * @param \Doctrine\Common\Cache\Cache|null $resultCacheDriver Cache driver
  639. *
  640. * @return $this
  641. *
  642. * @throws InvalidResultCacheDriver
  643. */
  644. public function setResultCacheDriver($resultCacheDriver = null)
  645. {
  646. /** @phpstan-ignore-next-line */
  647. if ($resultCacheDriver !== null && ! ($resultCacheDriver instanceof \Doctrine\Common\Cache\Cache)) {
  648. throw InvalidResultCacheDriver::create();
  649. }
  651. return $this->setResultCache($resultCacheDriver ? CacheAdapter::wrap($resultCacheDriver) : null);
  652. }
  654. /**
  655. * Defines a cache driver to be used for caching result sets and implicitly enables caching.
  656. *
  657. * @return $this
  658. */
  659. public function setResultCache(?CacheItemPoolInterface $resultCache = null)
  660. {
  661. if ($resultCache === null) {
  662. if (func_num_args() < 1) {
  663. Deprecation::trigger(
  664. 'doctrine/orm',
  665. 'https://github.com/doctrine/orm/pull/9791',
  666. 'Calling %s without arguments is deprecated, pass null instead.',
  667. __METHOD__
  668. );
  669. }
  671. if ($this->_queryCacheProfile) {
  672. $this->_queryCacheProfile = new QueryCacheProfile($this->_queryCacheProfile->getLifetime(), $this->_queryCacheProfile->getCacheKey());
  673. }
  675. return $this;
  676. }
  678. // DBAL 2
  679. if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  680. $resultCacheDriver = DoctrineProvider::wrap($resultCache);
  682. $this->_queryCacheProfile = $this->_queryCacheProfile
  683. // @phpstan-ignore method.deprecated
  684. ? $this->_queryCacheProfile->setResultCacheDriver($resultCacheDriver)
  685. : new QueryCacheProfile(0, null, $resultCacheDriver);
  687. return $this;
  688. }
  690. $this->_queryCacheProfile = $this->_queryCacheProfile
  691. ? $this->_queryCacheProfile->setResultCache($resultCache)
  692. : new QueryCacheProfile(0, null, $resultCache);
  694. return $this;
  695. }
  697. /**
  698. * Returns the cache driver used for caching result sets.
  699. *
  700. * @deprecated
  701. *
  702. * @return \Doctrine\Common\Cache\Cache Cache driver
  703. */
  704. public function getResultCacheDriver()
  705. {
  706. if ($this->_queryCacheProfile && $this->_queryCacheProfile->getResultCacheDriver()) {
  707. return $this->_queryCacheProfile->getResultCacheDriver();
  708. }
  710. return $this->_em->getConfiguration()->getResultCacheImpl();
  711. }
  713. /**
  714. * Set whether or not to cache the results of this query and if so, for
  715. * how long and which ID to use for the cache entry.
  716. *
  717. * @deprecated 2.7 Use {@see enableResultCache} and {@see disableResultCache} instead.
  718. *
  719. * @param bool $useCache Whether or not to cache the results of this query.
  720. * @param int $lifetime How long the cache entry is valid, in seconds.
  721. * @param string $resultCacheId ID to use for the cache entry.
  722. *
  723. * @return $this
  724. */
  725. public function useResultCache($useCache, $lifetime = null, $resultCacheId = null)
  726. {
  727. return $useCache
  728. ? $this->enableResultCache($lifetime, $resultCacheId)
  729. : $this->disableResultCache();
  730. }
  732. /**
  733. * Enables caching of the results of this query, for given or default amount of seconds
  734. * and optionally specifies which ID to use for the cache entry.
  735. *
  736. * @param int|null $lifetime How long the cache entry is valid, in seconds.
  737. * @param string|null $resultCacheId ID to use for the cache entry.
  738. *
  739. * @return $this
  740. */
  741. public function enableResultCache(?int $lifetime = null, ?string $resultCacheId = null): self
  742. {
  743. $this->setResultCacheLifetime($lifetime);
  744. $this->setResultCacheId($resultCacheId);
  746. return $this;
  747. }
  749. /**
  750. * Disables caching of the results of this query.
  751. *
  752. * @return $this
  753. */
  754. public function disableResultCache(): self
  755. {
  756. $this->_queryCacheProfile = null;
  758. return $this;
  759. }
  761. /**
  762. * Defines how long the result cache will be active before expire.
  763. *
  764. * @param int|null $lifetime How long the cache entry is valid, in seconds.
  765. *
  766. * @return $this
  767. */
  768. public function setResultCacheLifetime($lifetime)
  769. {
  770. $lifetime = (int) $lifetime;
  772. if ($this->_queryCacheProfile) {
  773. $this->_queryCacheProfile = $this->_queryCacheProfile->setLifetime($lifetime);
  775. return $this;
  776. }
  778. $this->_queryCacheProfile = new QueryCacheProfile($lifetime);
  780. $cache = $this->_em->getConfiguration()->getResultCache();
  781. if (! $cache) {
  782. return $this;
  783. }
  785. // Compatibility for DBAL 2
  786. if (! method_exists($this->_queryCacheProfile, 'setResultCache')) {
  787. // @phpstan-ignore method.deprecated
  788. $this->_queryCacheProfile = $this->_queryCacheProfile->setResultCacheDriver(DoctrineProvider::wrap($cache));
  790. return $this;
  791. }
  793. $this->_queryCacheProfile = $this->_queryCacheProfile->setResultCache($cache);
  795. return $this;
  796. }
  798. /**
  799. * Retrieves the lifetime of resultset cache.
  800. *
  801. * @deprecated
  802. *
  803. * @return int
  804. */
  805. public function getResultCacheLifetime()
  806. {
  807. return $this->_queryCacheProfile ? $this->_queryCacheProfile->getLifetime() : 0;
  808. }
  810. /**
  811. * Defines if the result cache is active or not.
  812. *
  813. * @param bool $expire Whether or not to force resultset cache expiration.
  814. *
  815. * @return $this
  816. */
  817. public function expireResultCache($expire = true)
  818. {
  819. $this->_expireResultCache = $expire;
  821. return $this;
  822. }
  824. /**
  825. * Retrieves if the resultset cache is active or not.
  826. *
  827. * @return bool
  828. */
  829. public function getExpireResultCache()
  830. {
  831. return $this->_expireResultCache;
  832. }
  834. /** @return QueryCacheProfile|null */
  835. public function getQueryCacheProfile()
  836. {
  837. return $this->_queryCacheProfile;
  838. }
  840. /**
  841. * Change the default fetch mode of an association for this query.
  842. *
  843. * @param class-string $class
  844. * @param string $assocName
  845. * @param int $fetchMode
  846. * @phpstan-param Mapping\ClassMetadata::FETCH_EAGER|Mapping\ClassMetadata::FETCH_LAZY $fetchMode
  847. *
  848. * @return $this
  849. */
  850. public function setFetchMode($class, $assocName, $fetchMode)
  851. {
  852. if (! in_array($fetchMode, [Mapping\ClassMetadata::FETCH_EAGER, Mapping\ClassMetadata::FETCH_LAZY], true)) {
  853. Deprecation::trigger(
  854. 'doctrine/orm',
  855. 'https://github.com/doctrine/orm/pull/9777',
  856. 'Calling %s() with something else than ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY is deprecated.',
  857. __METHOD__
  858. );
  859. $fetchMode = Mapping\ClassMetadata::FETCH_LAZY;
  860. }
  862. $this->_hints['fetchMode'][$class][$assocName] = $fetchMode;
  864. return $this;
  865. }
  867. /**
  868. * Defines the processing mode to be used during hydration / result set transformation.
  869. *
  870. * @param string|int $hydrationMode Doctrine processing mode to be used during hydration process.
  871. * One of the Query::HYDRATE_* constants.
  872. * @phpstan-param string|AbstractQuery::HYDRATE_* $hydrationMode
  873. *
  874. * @return $this
  875. */
  876. public function setHydrationMode($hydrationMode)
  877. {
  878. $this->_hydrationMode = $hydrationMode;
  880. return $this;
  881. }
  883. /**
  884. * Gets the hydration mode currently used by the query.
  885. *
  886. * @return string|int
  887. * @phpstan-return string|AbstractQuery::HYDRATE_*
  888. */
  889. public function getHydrationMode()
  890. {
  891. return $this->_hydrationMode;
  892. }
  894. /**
  895. * Gets the list of results for the query.
  896. *
  897. * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).
  898. *
  899. * @param string|int $hydrationMode
  900. * @phpstan-param string|AbstractQuery::HYDRATE_* $hydrationMode
  901. *
  902. * @return mixed
  903. */
  904. public function getResult($hydrationMode = self::HYDRATE_OBJECT)
  905. {
  906. return $this->execute(null, $hydrationMode);
  907. }
  909. /**
  910. * Gets the array of results for the query.
  911. *
  912. * Alias for execute(null, HYDRATE_ARRAY).
  913. *
  914. * @return mixed[]
  915. */
  916. public function getArrayResult()
  917. {
  918. return $this->execute(null, self::HYDRATE_ARRAY);
  919. }
  921. /**
  922. * Gets one-dimensional array of results for the query.
  923. *
  924. * Alias for execute(null, HYDRATE_SCALAR_COLUMN).
  925. *
  926. * @return mixed[]
  927. */
  928. public function getSingleColumnResult()
  929. {
  930. return $this->execute(null, self::HYDRATE_SCALAR_COLUMN);
  931. }
  933. /**
  934. * Gets the scalar results for the query.
  935. *
  936. * Alias for execute(null, HYDRATE_SCALAR).
  937. *
  938. * @return mixed[]
  939. */
  940. public function getScalarResult()
  941. {
  942. return $this->execute(null, self::HYDRATE_SCALAR);
  943. }
  945. /**
  946. * Get exactly one result or null.
  947. *
  948. * @param string|int|null $hydrationMode
  949. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  950. *
  951. * @return mixed
  952. *
  953. * @throws NonUniqueResultException
  954. */
  955. public function getOneOrNullResult($hydrationMode = null)
  956. {
  957. try {
  958. $result = $this->execute(null, $hydrationMode);
  959. } catch (NoResultException $e) {
  960. return null;
  961. }
  963. if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  964. return null;
  965. }
  967. if (! is_array($result)) {
  968. return $result;
  969. }
  971. if (count($result) > 1) {
  972. throw new NonUniqueResultException();
  973. }
  975. return array_shift($result);
  976. }
  978. /**
  979. * Gets the single result of the query.
  980. *
  981. * Enforces the presence as well as the uniqueness of the result.
  982. *
  983. * If the result is not unique, a NonUniqueResultException is thrown.
  984. * If there is no result, a NoResultException is thrown.
  985. *
  986. * @param string|int|null $hydrationMode
  987. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  988. *
  989. * @return mixed
  990. *
  991. * @throws NonUniqueResultException If the query result is not unique.
  992. * @throws NoResultException If the query returned no result.
  993. */
  994. public function getSingleResult($hydrationMode = null)
  995. {
  996. $result = $this->execute(null, $hydrationMode);
  998. if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  999. throw new NoResultException();
  1000. }
  1002. if (! is_array($result)) {
  1003. return $result;
  1004. }
  1006. if (count($result) > 1) {
  1007. throw new NonUniqueResultException();
  1008. }
  1010. return array_shift($result);
  1011. }
  1013. /**
  1014. * Gets the single scalar result of the query.
  1015. *
  1016. * Alias for getSingleResult(HYDRATE_SINGLE_SCALAR).
  1017. *
  1018. * @return bool|float|int|string|null The scalar result.
  1019. *
  1020. * @throws NoResultException If the query returned no result.
  1021. * @throws NonUniqueResultException If the query result is not unique.
  1022. */
  1023. public function getSingleScalarResult()
  1024. {
  1025. return $this->getSingleResult(self::HYDRATE_SINGLE_SCALAR);
  1026. }
  1028. /**
  1029. * Sets a query hint. If the hint name is not recognized, it is silently ignored.
  1030. *
  1031. * @param string $name The name of the hint.
  1032. * @param mixed $value The value of the hint.
  1033. *
  1034. * @return $this
  1035. */
  1036. public function setHint($name, $value)
  1037. {
  1038. $this->_hints[$name] = $value;
  1040. return $this;
  1041. }
  1043. /**
  1044. * Gets the value of a query hint. If the hint name is not recognized, FALSE is returned.
  1045. *
  1046. * @param string $name The name of the hint.
  1047. *
  1048. * @return mixed The value of the hint or FALSE, if the hint name is not recognized.
  1049. */
  1050. public function getHint($name)
  1051. {
  1052. return $this->_hints[$name] ?? false;
  1053. }
  1055. /**
  1056. * Check if the query has a hint
  1057. *
  1058. * @param string $name The name of the hint
  1059. *
  1060. * @return bool False if the query does not have any hint
  1061. */
  1062. public function hasHint($name)
  1063. {
  1064. return isset($this->_hints[$name]);
  1065. }
  1067. /**
  1068. * Return the key value map of query hints that are currently set.
  1069. *
  1070. * @return array<string,mixed>
  1071. */
  1072. public function getHints()
  1073. {
  1074. return $this->_hints;
  1075. }
  1077. /**
  1078. * Executes the query and returns an IterableResult that can be used to incrementally
  1079. * iterate over the result.
  1080. *
  1081. * @deprecated 2.8 Use {@see toIterable} instead. See https://github.com/doctrine/orm/issues/8463
  1082. *
  1083. * @param ArrayCollection|mixed[]|null $parameters The query parameters.
  1084. * @param string|int|null $hydrationMode The hydration mode to use.
  1085. * @phpstan-param ArrayCollection<int, Parameter>|array<string, mixed>|null $parameters
  1086. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode The hydration mode to use.
  1087. *
  1088. * @return IterableResult
  1089. */
  1090. public function iterate($parameters = null, $hydrationMode = null)
  1091. {
  1092. Deprecation::trigger(
  1093. 'doctrine/orm',
  1094. 'https://github.com/doctrine/orm/issues/8463',
  1095. 'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use toIterable() instead.',
  1096. __METHOD__
  1097. );
  1099. if ($hydrationMode !== null) {
  1100. $this->setHydrationMode($hydrationMode);
  1101. }
  1103. if (! empty($parameters)) {
  1104. $this->setParameters($parameters);
  1105. }
  1107. $rsm = $this->getResultSetMapping();
  1108. if ($rsm === null) {
  1109. throw new LogicException('Uninitialized result set mapping.');
  1110. }
  1112. $stmt = $this->_doExecute();
  1114. return $this->_em->newHydrator($this->_hydrationMode)->iterate($stmt, $rsm, $this->_hints);
  1115. }
  1117. /**
  1118. * Executes the query and returns an iterable that can be used to incrementally
  1119. * iterate over the result.
  1120. *
  1121. * @param ArrayCollection|array|mixed[] $parameters The query parameters.
  1122. * @param string|int|null $hydrationMode The hydration mode to use.
  1123. * @phpstan-param ArrayCollection<int, Parameter>|mixed[] $parameters
  1124. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  1125. *
  1126. * @return iterable<mixed>
  1127. */
  1128. public function toIterable(iterable $parameters = [], $hydrationMode = null): iterable
  1129. {
  1130. if ($hydrationMode !== null) {
  1131. $this->setHydrationMode($hydrationMode);
  1132. }
  1134. if (
  1135. ($this->isCountable($parameters) && count($parameters) !== 0)
  1136. || ($parameters instanceof Traversable && iterator_count($parameters) !== 0)
  1137. ) {
  1138. $this->setParameters($parameters);
  1139. }
  1141. $rsm = $this->getResultSetMapping();
  1142. if ($rsm === null) {
  1143. throw new LogicException('Uninitialized result set mapping.');
  1144. }
  1146. $stmt = $this->_doExecute();
  1148. return $this->_em->newHydrator($this->_hydrationMode)->toIterable($stmt, $rsm, $this->_hints);
  1149. }
  1151. /**
  1152. * Executes the query.
  1153. *
  1154. * @param ArrayCollection|mixed[]|null $parameters Query parameters.
  1155. * @param string|int|null $hydrationMode Processing mode to be used during the hydration process.
  1156. * @phpstan-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1157. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  1158. *
  1159. * @return mixed
  1160. */
  1161. public function execute($parameters = null, $hydrationMode = null)
  1162. {
  1163. if ($this->cacheable && $this->isCacheEnabled()) {
  1164. return $this->executeUsingQueryCache($parameters, $hydrationMode);
  1165. }
  1167. return $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1168. }
  1170. /**
  1171. * Execute query ignoring second level cache.
  1172. *
  1173. * @param ArrayCollection|mixed[]|null $parameters
  1174. * @param string|int|null $hydrationMode
  1175. * @phpstan-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1176. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  1177. *
  1178. * @return mixed
  1179. */
  1180. private function executeIgnoreQueryCache($parameters = null, $hydrationMode = null)
  1181. {
  1182. if ($hydrationMode !== null) {
  1183. $this->setHydrationMode($hydrationMode);
  1184. }
  1186. if (! empty($parameters)) {
  1187. $this->setParameters($parameters);
  1188. }
  1190. $setCacheEntry = static function ($data): void {
  1191. };
  1193. if ($this->_hydrationCacheProfile !== null) {
  1194. [$cacheKey, $realCacheKey] = $this->getHydrationCacheId();
  1196. $cache = $this->getHydrationCache();
  1197. $cacheItem = $cache->getItem($cacheKey);
  1198. $result = $cacheItem->isHit() ? $cacheItem->get() : [];
  1200. if (isset($result[$realCacheKey])) {
  1201. return $result[$realCacheKey];
  1202. }
  1204. if (! $result) {
  1205. $result = [];
  1206. }
  1208. $setCacheEntry = static function ($data) use ($cache, $result, $cacheItem, $realCacheKey): void {
  1209. $cache->save($cacheItem->set($result + [$realCacheKey => $data]));
  1210. };
  1211. }
  1213. $stmt = $this->_doExecute();
  1215. if (is_numeric($stmt)) {
  1216. $setCacheEntry($stmt);
  1218. return $stmt;
  1219. }
  1221. $rsm = $this->getResultSetMapping();
  1222. if ($rsm === null) {
  1223. throw new LogicException('Uninitialized result set mapping.');
  1224. }
  1226. $data = $this->_em->newHydrator($this->_hydrationMode)->hydrateAll($stmt, $rsm, $this->_hints);
  1228. $setCacheEntry($data);
  1230. return $data;
  1231. }
  1233. private function getHydrationCache(): CacheItemPoolInterface
  1234. {
  1235. assert($this->_hydrationCacheProfile !== null);
  1237. // Support for DBAL 2
  1238. if (! method_exists($this->_hydrationCacheProfile, 'getResultCache')) {
  1239. // @phpstan-ignore method.deprecated
  1240. $cacheDriver = $this->_hydrationCacheProfile->getResultCacheDriver();
  1241. assert($cacheDriver !== null);
  1243. return CacheAdapter::wrap($cacheDriver);
  1244. }
  1246. $cache = $this->_hydrationCacheProfile->getResultCache();
  1247. assert($cache !== null);
  1249. return $cache;
  1250. }
  1252. /**
  1253. * Load from second level cache or executes the query and put into cache.
  1254. *
  1255. * @param ArrayCollection|mixed[]|null $parameters
  1256. * @param string|int|null $hydrationMode
  1257. * @phpstan-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1258. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  1259. *
  1260. * @return mixed
  1261. */
  1262. private function executeUsingQueryCache($parameters = null, $hydrationMode = null)
  1263. {
  1264. $rsm = $this->getResultSetMapping();
  1265. if ($rsm === null) {
  1266. throw new LogicException('Uninitialized result set mapping.');
  1267. }
  1269. $queryCache = $this->_em->getCache()->getQueryCache($this->cacheRegion);
  1270. $queryKey = new QueryCacheKey(
  1271. $this->getHash(),
  1272. $this->lifetime,
  1273. $this->cacheMode ?: Cache::MODE_NORMAL,
  1274. $this->getTimestampKey()
  1275. );
  1277. $result = $queryCache->get($queryKey, $rsm, $this->_hints);
  1279. if ($result !== null) {
  1280. if ($this->cacheLogger) {
  1281. $this->cacheLogger->queryCacheHit($queryCache->getRegion()->getName(), $queryKey);
  1282. }
  1284. return $result;
  1285. }
  1287. $result = $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1288. $cached = $queryCache->put($queryKey, $rsm, $result, $this->_hints);
  1290. if ($this->cacheLogger) {
  1291. $this->cacheLogger->queryCacheMiss($queryCache->getRegion()->getName(), $queryKey);
  1293. if ($cached) {
  1294. $this->cacheLogger->queryCachePut($queryCache->getRegion()->getName(), $queryKey);
  1295. }
  1296. }
  1298. return $result;
  1299. }
  1301. private function getTimestampKey(): ?TimestampCacheKey
  1302. {
  1303. assert($this->_resultSetMapping !== null);
  1304. $entityName = reset($this->_resultSetMapping->aliasMap);
  1306. if (empty($entityName)) {
  1307. return null;
  1308. }
  1310. $metadata = $this->_em->getClassMetadata($entityName);
  1312. return new Cache\TimestampCacheKey($metadata->rootEntityName);
  1313. }
  1315. /**
  1316. * Get the result cache id to use to store the result set cache entry.
  1317. * Will return the configured id if it exists otherwise a hash will be
  1318. * automatically generated for you.
  1319. *
  1320. * @return string[] ($key, $hash)
  1321. * @phpstan-return array{string, string} ($key, $hash)
  1322. */
  1323. protected function getHydrationCacheId()
  1324. {
  1325. $parameters = [];
  1326. $types = [];
  1328. foreach ($this->getParameters() as $parameter) {
  1329. $parameters[$parameter->getName()] = $this->processParameterValue($parameter->getValue());
  1330. $types[$parameter->getName()] = $parameter->getType();
  1331. }
  1333. $sql = $this->getSQL();
  1334. assert(is_string($sql));
  1335. $queryCacheProfile = $this->getHydrationCacheProfile();
  1336. $hints = $this->getHints();
  1337. $hints['hydrationMode'] = $this->getHydrationMode();
  1339. ksort($hints);
  1340. assert($queryCacheProfile !== null);
  1342. return $queryCacheProfile->generateCacheKeys($sql, $parameters, $types, $hints);
  1343. }
  1345. /**
  1346. * Set the result cache id to use to store the result set cache entry.
  1347. * If this is not explicitly set by the developer then a hash is automatically
  1348. * generated for you.
  1349. *
  1350. * @param string|null $id
  1351. *
  1352. * @return $this
  1353. */
  1354. public function setResultCacheId($id)
  1355. {
  1356. if (! $this->_queryCacheProfile) {
  1357. return $this->setResultCacheProfile(new QueryCacheProfile(0, $id));
  1358. }
  1360. $this->_queryCacheProfile = $this->_queryCacheProfile->setCacheKey($id);
  1362. return $this;
  1363. }
  1365. /**
  1366. * Get the result cache id to use to store the result set cache entry if set.
  1367. *
  1368. * @deprecated
  1369. *
  1370. * @return string|null
  1371. */
  1372. public function getResultCacheId()
  1373. {
  1374. return $this->_queryCacheProfile ? $this->_queryCacheProfile->getCacheKey() : null;
  1375. }
  1377. /**
  1378. * Executes the query and returns a the resulting Statement object.
  1379. *
  1380. * @return Result|int The executed database statement that holds
  1381. * the results, or an integer indicating how
  1382. * many rows were affected.
  1383. */
  1384. abstract protected function _doExecute();
  1386. /**
  1387. * Cleanup Query resource when clone is called.
  1388. *
  1389. * @return void
  1390. */
  1391. public function __clone()
  1392. {
  1393. $this->parameters = new ArrayCollection();
  1395. $this->_hints = [];
  1396. $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  1397. }
  1399. /**
  1400. * Generates a string of currently query to use for the cache second level cache.
  1401. *
  1402. * @return string
  1403. */
  1404. protected function getHash()
  1405. {
  1406. $query = $this->getSQL();
  1407. assert(is_string($query));
  1408. $hints = $this->getHints();
  1409. $params = array_map(function (Parameter $parameter) {
  1410. $value = $parameter->getValue();
  1412. // Small optimization
  1413. // Does not invoke processParameterValue for scalar value
  1414. if (is_scalar($value)) {
  1415. return $value;
  1416. }
  1418. return $this->processParameterValue($value);
  1419. }, $this->parameters->getValues());
  1421. ksort($hints);
  1423. return sha1($query . '-' . serialize($params) . '-' . serialize($hints));
  1424. }
  1426. /** @param iterable<mixed> $subject */
  1427. private function isCountable(iterable $subject): bool
  1428. {
  1429. return $subject instanceof Countable || is_array($subject);
  1430. }
  1431. }