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

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. * @phpstan-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. * @phpstan-var array<string, mixed>
  115. */
  116. protected $_hints = [];
  118. /**
  119. * The hydration mode.
  120. *
  121. * @var string|int
  122. * @phpstan-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. * @phpstan-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. * @phpstan-return Cache::MODE_*|null
  258. */
  259. public function getCacheMode()
  260. {
  261. return $this->cacheMode;
  262. }
  264. /**
  265. * @param int $cacheMode
  266. * @phpstan-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. * @phpstan-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. * @phpstan-param ArrayCollection<int, Parameter>|mixed[] $parameters
  348. *
  349. * @return $this
  350. */
  351. public function setParameters($parameters)
  352. {
  353. if (is_array($parameters)) {
  354. /** @phpstan-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. // @phpstan-ignore method.deprecated
  562. if (! $profile->getResultCacheDriver()) {
  563. $defaultHydrationCacheImpl = $this->_em->getConfiguration()->getHydrationCache();
  564. if ($defaultHydrationCacheImpl) {
  565. // @phpstan-ignore method.deprecated
  566. $profile = $profile->setResultCacheDriver(DoctrineProvider::wrap($defaultHydrationCacheImpl));
  567. }
  568. }
  569. } elseif (! $profile->getResultCache()) {
  570. $defaultHydrationCacheImpl = $this->_em->getConfiguration()->getHydrationCache();
  571. if ($defaultHydrationCacheImpl) {
  572. $profile = $profile->setResultCache($defaultHydrationCacheImpl);
  573. }
  574. }
  576. $this->_hydrationCacheProfile = $profile;
  578. return $this;
  579. }
  581. /** @return QueryCacheProfile|null */
  582. public function getHydrationCacheProfile()
  583. {
  584. return $this->_hydrationCacheProfile;
  585. }
  587. /**
  588. * Set a cache profile for the result cache.
  589. *
  590. * If no result cache driver is set in the QueryCacheProfile, the default
  591. * result cache driver is used from the configuration.
  592. *
  593. * @return $this
  594. */
  595. public function setResultCacheProfile(?QueryCacheProfile $profile = null)
  596. {
  597. if ($profile === null) {
  598. if (func_num_args() < 1) {
  599. Deprecation::trigger(
  600. 'doctrine/orm',
  601. 'https://github.com/doctrine/orm/pull/9791',
  602. 'Calling %s without arguments is deprecated, pass null instead.',
  603. __METHOD__
  604. );
  605. }
  607. $this->_queryCacheProfile = null;
  609. return $this;
  610. }
  612. // DBAL 2
  613. if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  614. // @phpstan-ignore method.deprecated
  615. if (! $profile->getResultCacheDriver()) {
  616. $defaultResultCacheDriver = $this->_em->getConfiguration()->getResultCache();
  617. if ($defaultResultCacheDriver) {
  618. // @phpstan-ignore method.deprecated
  619. $profile = $profile->setResultCacheDriver(DoctrineProvider::wrap($defaultResultCacheDriver));
  620. }
  621. }
  622. } elseif (! $profile->getResultCache()) {
  623. $defaultResultCache = $this->_em->getConfiguration()->getResultCache();
  624. if ($defaultResultCache) {
  625. $profile = $profile->setResultCache($defaultResultCache);
  626. }
  627. }
  629. $this->_queryCacheProfile = $profile;
  631. return $this;
  632. }
  634. /**
  635. * Defines a cache driver to be used for caching result sets and implicitly enables caching.
  636. *
  637. * @deprecated Use {@see setResultCache()} instead.
  638. *
  639. * @param \Doctrine\Common\Cache\Cache|null $resultCacheDriver Cache driver
  640. *
  641. * @return $this
  642. *
  643. * @throws InvalidResultCacheDriver
  644. */
  645. public function setResultCacheDriver($resultCacheDriver = null)
  646. {
  647. /** @phpstan-ignore-next-line */
  648. if ($resultCacheDriver !== null && ! ($resultCacheDriver instanceof \Doctrine\Common\Cache\Cache)) {
  649. throw InvalidResultCacheDriver::create();
  650. }
  652. return $this->setResultCache($resultCacheDriver ? CacheAdapter::wrap($resultCacheDriver) : null);
  653. }
  655. /**
  656. * Defines a cache driver to be used for caching result sets and implicitly enables caching.
  657. *
  658. * @return $this
  659. */
  660. public function setResultCache(?CacheItemPoolInterface $resultCache = null)
  661. {
  662. if ($resultCache === null) {
  663. if (func_num_args() < 1) {
  664. Deprecation::trigger(
  665. 'doctrine/orm',
  666. 'https://github.com/doctrine/orm/pull/9791',
  667. 'Calling %s without arguments is deprecated, pass null instead.',
  668. __METHOD__
  669. );
  670. }
  672. if ($this->_queryCacheProfile) {
  673. $this->_queryCacheProfile = new QueryCacheProfile($this->_queryCacheProfile->getLifetime(), $this->_queryCacheProfile->getCacheKey());
  674. }
  676. return $this;
  677. }
  679. // DBAL 2
  680. if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  681. $resultCacheDriver = DoctrineProvider::wrap($resultCache);
  683. $this->_queryCacheProfile = $this->_queryCacheProfile
  684. // @phpstan-ignore method.deprecated
  685. ? $this->_queryCacheProfile->setResultCacheDriver($resultCacheDriver)
  686. : new QueryCacheProfile(0, null, $resultCacheDriver);
  688. return $this;
  689. }
  691. $this->_queryCacheProfile = $this->_queryCacheProfile
  692. ? $this->_queryCacheProfile->setResultCache($resultCache)
  693. : new QueryCacheProfile(0, null, $resultCache);
  695. return $this;
  696. }
  698. /**
  699. * Returns the cache driver used for caching result sets.
  700. *
  701. * @deprecated
  702. *
  703. * @return \Doctrine\Common\Cache\Cache Cache driver
  704. */
  705. public function getResultCacheDriver()
  706. {
  707. if ($this->_queryCacheProfile && $this->_queryCacheProfile->getResultCacheDriver()) {
  708. return $this->_queryCacheProfile->getResultCacheDriver();
  709. }
  711. return $this->_em->getConfiguration()->getResultCacheImpl();
  712. }
  714. /**
  715. * Set whether or not to cache the results of this query and if so, for
  716. * how long and which ID to use for the cache entry.
  717. *
  718. * @deprecated 2.7 Use {@see enableResultCache} and {@see disableResultCache} instead.
  719. *
  720. * @param bool $useCache Whether or not to cache the results of this query.
  721. * @param int $lifetime How long the cache entry is valid, in seconds.
  722. * @param string $resultCacheId ID to use for the cache entry.
  723. *
  724. * @return $this
  725. */
  726. public function useResultCache($useCache, $lifetime = null, $resultCacheId = null)
  727. {
  728. return $useCache
  729. ? $this->enableResultCache($lifetime, $resultCacheId)
  730. : $this->disableResultCache();
  731. }
  733. /**
  734. * Enables caching of the results of this query, for given or default amount of seconds
  735. * and optionally specifies which ID to use for the cache entry.
  736. *
  737. * @param int|null $lifetime How long the cache entry is valid, in seconds.
  738. * @param string|null $resultCacheId ID to use for the cache entry.
  739. *
  740. * @return $this
  741. */
  742. public function enableResultCache(?int $lifetime = null, ?string $resultCacheId = null): self
  743. {
  744. $this->setResultCacheLifetime($lifetime);
  745. $this->setResultCacheId($resultCacheId);
  747. return $this;
  748. }
  750. /**
  751. * Disables caching of the results of this query.
  752. *
  753. * @return $this
  754. */
  755. public function disableResultCache(): self
  756. {
  757. $this->_queryCacheProfile = null;
  759. return $this;
  760. }
  762. /**
  763. * Defines how long the result cache will be active before expire.
  764. *
  765. * @param int|null $lifetime How long the cache entry is valid, in seconds.
  766. *
  767. * @return $this
  768. */
  769. public function setResultCacheLifetime($lifetime)
  770. {
  771. $lifetime = (int) $lifetime;
  773. if ($this->_queryCacheProfile) {
  774. $this->_queryCacheProfile = $this->_queryCacheProfile->setLifetime($lifetime);
  776. return $this;
  777. }
  779. $this->_queryCacheProfile = new QueryCacheProfile($lifetime);
  781. $cache = $this->_em->getConfiguration()->getResultCache();
  782. if (! $cache) {
  783. return $this;
  784. }
  786. // Compatibility for DBAL 2
  787. if (! method_exists($this->_queryCacheProfile, 'setResultCache')) {
  788. // @phpstan-ignore method.deprecated
  789. $this->_queryCacheProfile = $this->_queryCacheProfile->setResultCacheDriver(DoctrineProvider::wrap($cache));
  791. return $this;
  792. }
  794. $this->_queryCacheProfile = $this->_queryCacheProfile->setResultCache($cache);
  796. return $this;
  797. }
  799. /**
  800. * Retrieves the lifetime of resultset cache.
  801. *
  802. * @deprecated
  803. *
  804. * @return int
  805. */
  806. public function getResultCacheLifetime()
  807. {
  808. return $this->_queryCacheProfile ? $this->_queryCacheProfile->getLifetime() : 0;
  809. }
  811. /**
  812. * Defines if the result cache is active or not.
  813. *
  814. * @param bool $expire Whether or not to force resultset cache expiration.
  815. *
  816. * @return $this
  817. */
  818. public function expireResultCache($expire = true)
  819. {
  820. $this->_expireResultCache = $expire;
  822. return $this;
  823. }
  825. /**
  826. * Retrieves if the resultset cache is active or not.
  827. *
  828. * @return bool
  829. */
  830. public function getExpireResultCache()
  831. {
  832. return $this->_expireResultCache;
  833. }
  835. /** @return QueryCacheProfile|null */
  836. public function getQueryCacheProfile()
  837. {
  838. return $this->_queryCacheProfile;
  839. }
  841. /**
  842. * Change the default fetch mode of an association for this query.
  843. *
  844. * @param class-string $class
  845. * @param string $assocName
  846. * @param int $fetchMode
  847. * @phpstan-param Mapping\ClassMetadata::FETCH_EAGER|Mapping\ClassMetadata::FETCH_LAZY $fetchMode
  848. *
  849. * @return $this
  850. */
  851. public function setFetchMode($class, $assocName, $fetchMode)
  852. {
  853. if (! in_array($fetchMode, [Mapping\ClassMetadata::FETCH_EAGER, Mapping\ClassMetadata::FETCH_LAZY], true)) {
  854. Deprecation::trigger(
  855. 'doctrine/orm',
  856. 'https://github.com/doctrine/orm/pull/9777',
  857. 'Calling %s() with something else than ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY is deprecated.',
  858. __METHOD__
  859. );
  860. $fetchMode = Mapping\ClassMetadata::FETCH_LAZY;
  861. }
  863. $this->_hints['fetchMode'][$class][$assocName] = $fetchMode;
  865. return $this;
  866. }
  868. /**
  869. * Defines the processing mode to be used during hydration / result set transformation.
  870. *
  871. * @param string|int $hydrationMode Doctrine processing mode to be used during hydration process.
  872. * One of the Query::HYDRATE_* constants.
  873. * @phpstan-param string|AbstractQuery::HYDRATE_* $hydrationMode
  874. *
  875. * @return $this
  876. */
  877. public function setHydrationMode($hydrationMode)
  878. {
  879. $this->_hydrationMode = $hydrationMode;
  881. return $this;
  882. }
  884. /**
  885. * Gets the hydration mode currently used by the query.
  886. *
  887. * @return string|int
  888. * @phpstan-return string|AbstractQuery::HYDRATE_*
  889. */
  890. public function getHydrationMode()
  891. {
  892. return $this->_hydrationMode;
  893. }
  895. /**
  896. * Gets the list of results for the query.
  897. *
  898. * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).
  899. *
  900. * @param string|int $hydrationMode
  901. * @phpstan-param string|AbstractQuery::HYDRATE_* $hydrationMode
  902. *
  903. * @return mixed
  904. */
  905. public function getResult($hydrationMode = self::HYDRATE_OBJECT)
  906. {
  907. return $this->execute(null, $hydrationMode);
  908. }
  910. /**
  911. * Gets the array of results for the query.
  912. *
  913. * Alias for execute(null, HYDRATE_ARRAY).
  914. *
  915. * @return mixed[]
  916. */
  917. public function getArrayResult()
  918. {
  919. return $this->execute(null, self::HYDRATE_ARRAY);
  920. }
  922. /**
  923. * Gets one-dimensional array of results for the query.
  924. *
  925. * Alias for execute(null, HYDRATE_SCALAR_COLUMN).
  926. *
  927. * @return mixed[]
  928. */
  929. public function getSingleColumnResult()
  930. {
  931. return $this->execute(null, self::HYDRATE_SCALAR_COLUMN);
  932. }
  934. /**
  935. * Gets the scalar results for the query.
  936. *
  937. * Alias for execute(null, HYDRATE_SCALAR).
  938. *
  939. * @return mixed[]
  940. */
  941. public function getScalarResult()
  942. {
  943. return $this->execute(null, self::HYDRATE_SCALAR);
  944. }
  946. /**
  947. * Get exactly one result or null.
  948. *
  949. * @param string|int|null $hydrationMode
  950. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  951. *
  952. * @return mixed
  953. *
  954. * @throws NonUniqueResultException
  955. */
  956. public function getOneOrNullResult($hydrationMode = null)
  957. {
  958. try {
  959. $result = $this->execute(null, $hydrationMode);
  960. } catch (NoResultException $e) {
  961. return null;
  962. }
  964. if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  965. return null;
  966. }
  968. if (! is_array($result)) {
  969. return $result;
  970. }
  972. if (count($result) > 1) {
  973. throw new NonUniqueResultException();
  974. }
  976. return array_shift($result);
  977. }
  979. /**
  980. * Gets the single result of the query.
  981. *
  982. * Enforces the presence as well as the uniqueness of the result.
  983. *
  984. * If the result is not unique, a NonUniqueResultException is thrown.
  985. * If there is no result, a NoResultException is thrown.
  986. *
  987. * @param string|int|null $hydrationMode
  988. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  989. *
  990. * @return mixed
  991. *
  992. * @throws NonUniqueResultException If the query result is not unique.
  993. * @throws NoResultException If the query returned no result.
  994. */
  995. public function getSingleResult($hydrationMode = null)
  996. {
  997. $result = $this->execute(null, $hydrationMode);
  999. if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  1000. throw new NoResultException();
  1001. }
  1003. if (! is_array($result)) {
  1004. return $result;
  1005. }
  1007. if (count($result) > 1) {
  1008. throw new NonUniqueResultException();
  1009. }
  1011. return array_shift($result);
  1012. }
  1014. /**
  1015. * Gets the single scalar result of the query.
  1016. *
  1017. * Alias for getSingleResult(HYDRATE_SINGLE_SCALAR).
  1018. *
  1019. * @return bool|float|int|string|null The scalar result.
  1020. *
  1021. * @throws NoResultException If the query returned no result.
  1022. * @throws NonUniqueResultException If the query result is not unique.
  1023. */
  1024. public function getSingleScalarResult()
  1025. {
  1026. return $this->getSingleResult(self::HYDRATE_SINGLE_SCALAR);
  1027. }
  1029. /**
  1030. * Sets a query hint. If the hint name is not recognized, it is silently ignored.
  1031. *
  1032. * @param string $name The name of the hint.
  1033. * @param mixed $value The value of the hint.
  1034. *
  1035. * @return $this
  1036. */
  1037. public function setHint($name, $value)
  1038. {
  1039. $this->_hints[$name] = $value;
  1041. return $this;
  1042. }
  1044. /**
  1045. * Gets the value of a query hint. If the hint name is not recognized, FALSE is returned.
  1046. *
  1047. * @param string $name The name of the hint.
  1048. *
  1049. * @return mixed The value of the hint or FALSE, if the hint name is not recognized.
  1050. */
  1051. public function getHint($name)
  1052. {
  1053. return $this->_hints[$name] ?? false;
  1054. }
  1056. /**
  1057. * Check if the query has a hint
  1058. *
  1059. * @param string $name The name of the hint
  1060. *
  1061. * @return bool False if the query does not have any hint
  1062. */
  1063. public function hasHint($name)
  1064. {
  1065. return isset($this->_hints[$name]);
  1066. }
  1068. /**
  1069. * Return the key value map of query hints that are currently set.
  1070. *
  1071. * @return array<string,mixed>
  1072. */
  1073. public function getHints()
  1074. {
  1075. return $this->_hints;
  1076. }
  1078. /**
  1079. * Executes the query and returns an IterableResult that can be used to incrementally
  1080. * iterate over the result.
  1081. *
  1082. * @deprecated 2.8 Use {@see toIterable} instead. See https://github.com/doctrine/orm/issues/8463
  1083. *
  1084. * @param ArrayCollection|mixed[]|null $parameters The query parameters.
  1085. * @param string|int|null $hydrationMode The hydration mode to use.
  1086. * @phpstan-param ArrayCollection<int, Parameter>|array<string, mixed>|null $parameters
  1087. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode The hydration mode to use.
  1088. *
  1089. * @return IterableResult
  1090. */
  1091. public function iterate($parameters = null, $hydrationMode = null)
  1092. {
  1093. Deprecation::trigger(
  1094. 'doctrine/orm',
  1095. 'https://github.com/doctrine/orm/issues/8463',
  1096. 'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use toIterable() instead.',
  1097. __METHOD__
  1098. );
  1100. if ($hydrationMode !== null) {
  1101. $this->setHydrationMode($hydrationMode);
  1102. }
  1104. if (! empty($parameters)) {
  1105. $this->setParameters($parameters);
  1106. }
  1108. $rsm = $this->getResultSetMapping();
  1109. if ($rsm === null) {
  1110. throw new LogicException('Uninitialized result set mapping.');
  1111. }
  1113. $stmt = $this->_doExecute();
  1115. return $this->_em->newHydrator($this->_hydrationMode)->iterate($stmt, $rsm, $this->_hints);
  1116. }
  1118. /**
  1119. * Executes the query and returns an iterable that can be used to incrementally
  1120. * iterate over the result.
  1121. *
  1122. * @param ArrayCollection|array|mixed[] $parameters The query parameters.
  1123. * @param string|int|null $hydrationMode The hydration mode to use.
  1124. * @phpstan-param ArrayCollection<int, Parameter>|mixed[] $parameters
  1125. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  1126. *
  1127. * @return iterable<mixed>
  1128. */
  1129. public function toIterable(iterable $parameters = [], $hydrationMode = null): iterable
  1130. {
  1131. if ($hydrationMode !== null) {
  1132. $this->setHydrationMode($hydrationMode);
  1133. }
  1135. if (
  1136. ($this->isCountable($parameters) && count($parameters) !== 0)
  1137. || ($parameters instanceof Traversable && iterator_count($parameters) !== 0)
  1138. ) {
  1139. $this->setParameters($parameters);
  1140. }
  1142. $rsm = $this->getResultSetMapping();
  1143. if ($rsm === null) {
  1144. throw new LogicException('Uninitialized result set mapping.');
  1145. }
  1147. if ($rsm->isMixed && count($rsm->scalarMappings) > 0) {
  1148. throw QueryException::iterateWithMixedResultNotAllowed();
  1149. }
  1151. $stmt = $this->_doExecute();
  1153. return $this->_em->newHydrator($this->_hydrationMode)->toIterable($stmt, $rsm, $this->_hints);
  1154. }
  1156. /**
  1157. * Executes the query.
  1158. *
  1159. * @param ArrayCollection|mixed[]|null $parameters Query parameters.
  1160. * @param string|int|null $hydrationMode Processing mode to be used during the hydration process.
  1161. * @phpstan-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1162. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  1163. *
  1164. * @return mixed
  1165. */
  1166. public function execute($parameters = null, $hydrationMode = null)
  1167. {
  1168. if ($this->cacheable && $this->isCacheEnabled()) {
  1169. return $this->executeUsingQueryCache($parameters, $hydrationMode);
  1170. }
  1172. return $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1173. }
  1175. /**
  1176. * Execute query ignoring second level cache.
  1177. *
  1178. * @param ArrayCollection|mixed[]|null $parameters
  1179. * @param string|int|null $hydrationMode
  1180. * @phpstan-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1181. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  1182. *
  1183. * @return mixed
  1184. */
  1185. private function executeIgnoreQueryCache($parameters = null, $hydrationMode = null)
  1186. {
  1187. if ($hydrationMode !== null) {
  1188. $this->setHydrationMode($hydrationMode);
  1189. }
  1191. if (! empty($parameters)) {
  1192. $this->setParameters($parameters);
  1193. }
  1195. $setCacheEntry = static function ($data): void {
  1196. };
  1198. if ($this->_hydrationCacheProfile !== null) {
  1199. [$cacheKey, $realCacheKey] = $this->getHydrationCacheId();
  1201. $cache = $this->getHydrationCache();
  1202. $cacheItem = $cache->getItem($cacheKey);
  1203. $result = $cacheItem->isHit() ? $cacheItem->get() : [];
  1205. if (isset($result[$realCacheKey])) {
  1206. return $result[$realCacheKey];
  1207. }
  1209. if (! $result) {
  1210. $result = [];
  1211. }
  1213. $setCacheEntry = static function ($data) use ($cache, $result, $cacheItem, $realCacheKey): void {
  1214. $cache->save($cacheItem->set($result + [$realCacheKey => $data]));
  1215. };
  1216. }
  1218. $stmt = $this->_doExecute();
  1220. if (is_numeric($stmt)) {
  1221. $setCacheEntry($stmt);
  1223. return $stmt;
  1224. }
  1226. $rsm = $this->getResultSetMapping();
  1227. if ($rsm === null) {
  1228. throw new LogicException('Uninitialized result set mapping.');
  1229. }
  1231. $data = $this->_em->newHydrator($this->_hydrationMode)->hydrateAll($stmt, $rsm, $this->_hints);
  1233. $setCacheEntry($data);
  1235. return $data;
  1236. }
  1238. private function getHydrationCache(): CacheItemPoolInterface
  1239. {
  1240. assert($this->_hydrationCacheProfile !== null);
  1242. // Support for DBAL 2
  1243. if (! method_exists($this->_hydrationCacheProfile, 'getResultCache')) {
  1244. // @phpstan-ignore method.deprecated
  1245. $cacheDriver = $this->_hydrationCacheProfile->getResultCacheDriver();
  1246. assert($cacheDriver !== null);
  1248. return CacheAdapter::wrap($cacheDriver);
  1249. }
  1251. $cache = $this->_hydrationCacheProfile->getResultCache();
  1252. assert($cache !== null);
  1254. return $cache;
  1255. }
  1257. /**
  1258. * Load from second level cache or executes the query and put into cache.
  1259. *
  1260. * @param ArrayCollection|mixed[]|null $parameters
  1261. * @param string|int|null $hydrationMode
  1262. * @phpstan-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1263. * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  1264. *
  1265. * @return mixed
  1266. */
  1267. private function executeUsingQueryCache($parameters = null, $hydrationMode = null)
  1268. {
  1269. $rsm = $this->getResultSetMapping();
  1270. if ($rsm === null) {
  1271. throw new LogicException('Uninitialized result set mapping.');
  1272. }
  1274. $queryCache = $this->_em->getCache()->getQueryCache($this->cacheRegion);
  1275. $queryKey = new QueryCacheKey(
  1276. $this->getHash(),
  1277. $this->lifetime,
  1278. $this->cacheMode ?: Cache::MODE_NORMAL,
  1279. $this->getTimestampKey()
  1280. );
  1282. $result = $queryCache->get($queryKey, $rsm, $this->_hints);
  1284. if ($result !== null) {
  1285. if ($this->cacheLogger) {
  1286. $this->cacheLogger->queryCacheHit($queryCache->getRegion()->getName(), $queryKey);
  1287. }
  1289. return $result;
  1290. }
  1292. $result = $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1293. $cached = $queryCache->put($queryKey, $rsm, $result, $this->_hints);
  1295. if ($this->cacheLogger) {
  1296. $this->cacheLogger->queryCacheMiss($queryCache->getRegion()->getName(), $queryKey);
  1298. if ($cached) {
  1299. $this->cacheLogger->queryCachePut($queryCache->getRegion()->getName(), $queryKey);
  1300. }
  1301. }
  1303. return $result;
  1304. }
  1306. private function getTimestampKey(): ?TimestampCacheKey
  1307. {
  1308. assert($this->_resultSetMapping !== null);
  1309. $entityName = reset($this->_resultSetMapping->aliasMap);
  1311. if (empty($entityName)) {
  1312. return null;
  1313. }
  1315. $metadata = $this->_em->getClassMetadata($entityName);
  1317. return new Cache\TimestampCacheKey($metadata->rootEntityName);
  1318. }
  1320. /**
  1321. * Get the result cache id to use to store the result set cache entry.
  1322. * Will return the configured id if it exists otherwise a hash will be
  1323. * automatically generated for you.
  1324. *
  1325. * @return string[] ($key, $hash)
  1326. * @phpstan-return array{string, string} ($key, $hash)
  1327. */
  1328. protected function getHydrationCacheId()
  1329. {
  1330. $parameters = [];
  1331. $types = [];
  1333. foreach ($this->getParameters() as $parameter) {
  1334. $parameters[$parameter->getName()] = $this->processParameterValue($parameter->getValue());
  1335. $types[$parameter->getName()] = $parameter->getType();
  1336. }
  1338. $sql = $this->getSQL();
  1339. assert(is_string($sql));
  1340. $queryCacheProfile = $this->getHydrationCacheProfile();
  1341. $hints = $this->getHints();
  1342. $hints['hydrationMode'] = $this->getHydrationMode();
  1344. ksort($hints);
  1345. assert($queryCacheProfile !== null);
  1347. return $queryCacheProfile->generateCacheKeys($sql, $parameters, $types, $hints);
  1348. }
  1350. /**
  1351. * Set the result cache id to use to store the result set cache entry.
  1352. * If this is not explicitly set by the developer then a hash is automatically
  1353. * generated for you.
  1354. *
  1355. * @param string|null $id
  1356. *
  1357. * @return $this
  1358. */
  1359. public function setResultCacheId($id)
  1360. {
  1361. if (! $this->_queryCacheProfile) {
  1362. return $this->setResultCacheProfile(new QueryCacheProfile(0, $id));
  1363. }
  1365. $this->_queryCacheProfile = $this->_queryCacheProfile->setCacheKey($id);
  1367. return $this;
  1368. }
  1370. /**
  1371. * Get the result cache id to use to store the result set cache entry if set.
  1372. *
  1373. * @deprecated
  1374. *
  1375. * @return string|null
  1376. */
  1377. public function getResultCacheId()
  1378. {
  1379. return $this->_queryCacheProfile ? $this->_queryCacheProfile->getCacheKey() : null;
  1380. }
  1382. /**
  1383. * Executes the query and returns a the resulting Statement object.
  1384. *
  1385. * @return Result|int The executed database statement that holds
  1386. * the results, or an integer indicating how
  1387. * many rows were affected.
  1388. */
  1389. abstract protected function _doExecute();
  1391. /**
  1392. * Cleanup Query resource when clone is called.
  1393. *
  1394. * @return void
  1395. */
  1396. public function __clone()
  1397. {
  1398. $this->parameters = new ArrayCollection();
  1400. $this->_hints = [];
  1401. $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  1402. }
  1404. /**
  1405. * Generates a string of currently query to use for the cache second level cache.
  1406. *
  1407. * @return string
  1408. */
  1409. protected function getHash()
  1410. {
  1411. $query = $this->getSQL();
  1412. assert(is_string($query));
  1413. $hints = $this->getHints();
  1414. $params = array_map(function (Parameter $parameter) {
  1415. $value = $parameter->getValue();
  1417. // Small optimization
  1418. // Does not invoke processParameterValue for scalar value
  1419. if (is_scalar($value)) {
  1420. return $value;
  1421. }
  1423. return $this->processParameterValue($value);
  1424. }, $this->parameters->getValues());
  1426. ksort($hints);
  1428. return sha1($query . '-' . serialize($params) . '-' . serialize($hints));
  1429. }
  1431. /** @param iterable<mixed> $subject */
  1432. private function isCountable(iterable $subject): bool
  1433. {
  1434. return $subject instanceof Countable || is_array($subject);
  1435. }
  1436. }