vendor/doctrine/orm/lib/Doctrine/ORM/AbstractQuery.php line 907

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