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

Open in your IDE?
  1. <?php
  3. declare(strict_types=1);
  5. namespace Doctrine\ORM;
  7. use BackedEnum;
  8. use Countable;
  9. use Doctrine\Common\Cache\Psr6\CacheAdapter;
  10. use Doctrine\Common\Cache\Psr6\DoctrineProvider;
  11. use Doctrine\Common\Collections\ArrayCollection;
  12. use Doctrine\Common\Collections\Collection;
  13. use Doctrine\DBAL\Cache\QueryCacheProfile;
  14. use Doctrine\DBAL\Result;
  15. use Doctrine\Deprecations\Deprecation;
  16. use Doctrine\ORM\Cache\Exception\InvalidResultCacheDriver;
  17. use Doctrine\ORM\Cache\Logging\CacheLogger;
  18. use Doctrine\ORM\Cache\QueryCacheKey;
  19. use Doctrine\ORM\Cache\TimestampCacheKey;
  20. use Doctrine\ORM\Internal\Hydration\IterableResult;
  21. use Doctrine\ORM\Mapping\MappingException as ORMMappingException;
  22. use Doctrine\ORM\Proxy\DefaultProxyClassNameResolver;
  23. use Doctrine\ORM\Query\Parameter;
  24. use Doctrine\ORM\Query\QueryException;
  25. use Doctrine\ORM\Query\ResultSetMapping;
  26. use Doctrine\Persistence\Mapping\MappingException;
  27. use LogicException;
  28. use Psr\Cache\CacheItemPoolInterface;
  29. use Traversable;
  31. use function array_map;
  32. use function array_shift;
  33. use function assert;
  34. use function count;
  35. use function func_num_args;
  36. use function in_array;
  37. use function is_array;
  38. use function is_numeric;
  39. use function is_object;
  40. use function is_scalar;
  41. use function is_string;
  42. use function iterator_count;
  43. use function iterator_to_array;
  44. use function ksort;
  45. use function method_exists;
  46. use function reset;
  47. use function serialize;
  48. use function sha1;
  50. /**
  51.  * Base contract for ORM queries. Base class for Query and NativeQuery.
  52.  *
  53.  * @link    www.doctrine-project.org
  54.  */
  55. abstract class AbstractQuery
  56. {
  57.     /* Hydration mode constants */
  59.     /**
  60.      * Hydrates an object graph. This is the default behavior.
  61.      */
  62.     public const HYDRATE_OBJECT = 1;
  64.     /**
  65.      * Hydrates an array graph.
  66.      */
  67.     public const HYDRATE_ARRAY = 2;
  69.     /**
  70.      * Hydrates a flat, rectangular result set with scalar values.
  71.      */
  72.     public const HYDRATE_SCALAR = 3;
  74.     /**
  75.      * Hydrates a single scalar value.
  76.      */
  77.     public const HYDRATE_SINGLE_SCALAR = 4;
  79.     /**
  80.      * Very simple object hydrator (optimized for performance).
  81.      */
  82.     public const HYDRATE_SIMPLEOBJECT = 5;
  84.     /**
  85.      * Hydrates scalar column value.
  86.      */
  87.     public const HYDRATE_SCALAR_COLUMN = 6;
  89.     /**
  90.      * The parameter map of this query.
  91.      *
  92.      * @var ArrayCollection|Parameter[]
  93.      * @psalm-var ArrayCollection<int, Parameter>
  94.      */
  95.     protected $parameters;
  97.     /**
  98.      * The user-specified ResultSetMapping to use.
  99.      *
  100.      * @var ResultSetMapping|null
  101.      */
  102.     protected $_resultSetMapping;
  104.     /**
  105.      * The entity manager used by this query object.
  106.      *
  107.      * @var EntityManagerInterface
  108.      */
  109.     protected $_em;
  111.     /**
  112.      * The map of query hints.
  113.      *
  114.      * @psalm-var array<string, mixed>
  115.      */
  116.     protected $_hints = [];
  118.     /**
  119.      * The hydration mode.
  120.      *
  121.      * @var string|int
  122.      * @psalm-var string|AbstractQuery::HYDRATE_*
  123.      */
  124.     protected $_hydrationMode = self::HYDRATE_OBJECT;
  126.     /** @var QueryCacheProfile|null */
  127.     protected $_queryCacheProfile;
  129.     /**
  130.      * Whether or not expire the result cache.
  131.      *
  132.      * @var bool
  133.      */
  134.     protected $_expireResultCache = false;
  136.     /** @var QueryCacheProfile|null */
  137.     protected $_hydrationCacheProfile;
  139.     /**
  140.      * Whether to use second level cache, if available.
  141.      *
  142.      * @var bool
  143.      */
  144.     protected $cacheable = false;
  146.     /** @var bool */
  147.     protected $hasCache = false;
  149.     /**
  150.      * Second level cache region name.
  151.      *
  152.      * @var string|null
  153.      */
  154.     protected $cacheRegion;
  156.     /**
  157.      * Second level query cache mode.
  158.      *
  159.      * @var int|null
  160.      * @psalm-var Cache::MODE_*|null
  161.      */
  162.     protected $cacheMode;
  164.     /** @var CacheLogger|null */
  165.     protected $cacheLogger;
  167.     /** @var int */
  168.     protected $lifetime = 0;
  170.     /**
  171.      * Initializes a new instance of a class derived from <tt>AbstractQuery</tt>.
  172.      */
  173.     public function __construct(EntityManagerInterface $em)
  174.     {
  175.         $this->_em        = $em;
  176.         $this->parameters = new ArrayCollection();
  177.         $this->_hints     = $em->getConfiguration()->getDefaultQueryHints();
  178.         $this->hasCache   = $this->_em->getConfiguration()->isSecondLevelCacheEnabled();
  180.         if ($this->hasCache) {
  181.             $this->cacheLogger = $em->getConfiguration()
  182.                 ->getSecondLevelCacheConfiguration()
  183.                 ->getCacheLogger();
  184.         }
  185.     }
  187.     /**
  188.      * Enable/disable second level query (result) caching for this query.
  189.      *
  190.      * @param bool $cacheable
  191.      *
  192.      * @return $this
  193.      */
  194.     public function setCacheable($cacheable)
  195.     {
  196.         $this->cacheable = (bool) $cacheable;
  198.         return $this;
  199.     }
  201.     /** @return bool TRUE if the query results are enabled for second level cache, FALSE otherwise. */
  202.     public function isCacheable()
  203.     {
  204.         return $this->cacheable;
  205.     }
  207.     /**
  208.      * @param string $cacheRegion
  209.      *
  210.      * @return $this
  211.      */
  212.     public function setCacheRegion($cacheRegion)
  213.     {
  214.         $this->cacheRegion = (string) $cacheRegion;
  216.         return $this;
  217.     }
  219.     /**
  220.      * Obtain the name of the second level query cache region in which query results will be stored
  221.      *
  222.      * @return string|null The cache region name; NULL indicates the default region.
  223.      */
  224.     public function getCacheRegion()
  225.     {
  226.         return $this->cacheRegion;
  227.     }
  229.     /** @return bool TRUE if the query cache and second level cache are enabled, FALSE otherwise. */
  230.     protected function isCacheEnabled()
  231.     {
  232.         return $this->cacheable && $this->hasCache;
  233.     }
  235.     /** @return int */
  236.     public function getLifetime()
  237.     {
  238.         return $this->lifetime;
  239.     }
  241.     /**
  242.      * Sets the life-time for this query into second level cache.
  243.      *
  244.      * @param int $lifetime
  245.      *
  246.      * @return $this
  247.      */
  248.     public function setLifetime($lifetime)
  249.     {
  250.         $this->lifetime = (int) $lifetime;
  252.         return $this;
  253.     }
  255.     /**
  256.      * @return int|null
  257.      * @psalm-return Cache::MODE_*|null
  258.      */
  259.     public function getCacheMode()
  260.     {
  261.         return $this->cacheMode;
  262.     }
  264.     /**
  265.      * @param int $cacheMode
  266.      * @psalm-param Cache::MODE_* $cacheMode
  267.      *
  268.      * @return $this
  269.      */
  270.     public function setCacheMode($cacheMode)
  271.     {
  272.         $this->cacheMode = (int) $cacheMode;
  274.         return $this;
  275.     }
  277.     /**
  278.      * Gets the SQL query that corresponds to this query object.
  279.      * The returned SQL syntax depends on the connection driver that is used
  280.      * by this query object at the time of this method call.
  281.      *
  282.      * @return list<string>|string SQL query
  283.      */
  284.     abstract public function getSQL();
  286.     /**
  287.      * Retrieves the associated EntityManager of this Query instance.
  288.      *
  289.      * @return EntityManagerInterface
  290.      */
  291.     public function getEntityManager()
  292.     {
  293.         return $this->_em;
  294.     }
  296.     /**
  297.      * Frees the resources used by the query object.
  298.      *
  299.      * Resets Parameters, Parameter Types and Query Hints.
  300.      *
  301.      * @return void
  302.      */
  303.     public function free()
  304.     {
  305.         $this->parameters = new ArrayCollection();
  307.         $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  308.     }
  310.     /**
  311.      * Get all defined parameters.
  312.      *
  313.      * @return ArrayCollection The defined query parameters.
  314.      * @psalm-return ArrayCollection<int, Parameter>
  315.      */
  316.     public function getParameters()
  317.     {
  318.         return $this->parameters;
  319.     }
  321.     /**
  322.      * Gets a query parameter.
  323.      *
  324.      * @param int|string $key The key (index or name) of the bound parameter.
  325.      *
  326.      * @return Parameter|null The value of the bound parameter, or NULL if not available.
  327.      */
  328.     public function getParameter($key)
  329.     {
  330.         $key = Query\Parameter::normalizeName($key);
  332.         $filteredParameters = $this->parameters->filter(
  333.             static function (Query\Parameter $parameter) use ($key): bool {
  334.                 $parameterName = $parameter->getName();
  336.                 return $key === $parameterName;
  337.             }
  338.         );
  340.         return ! $filteredParameters->isEmpty() ? $filteredParameters->first() : null;
  341.     }
  343.     /**
  344.      * Sets a collection of query parameters.
  345.      *
  346.      * @param ArrayCollection|mixed[] $parameters
  347.      * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
  348.      *
  349.      * @return $this
  350.      */
  351.     public function setParameters($parameters)
  352.     {
  353.         if (is_array($parameters)) {
  354.             /** @psalm-var ArrayCollection<int, Parameter> $parameterCollection */
  355.             $parameterCollection = new ArrayCollection();
  357.             foreach ($parameters as $key => $value) {
  358.                 $parameterCollection->add(new Parameter($key, $value));
  359.             }
  361.             $parameters = $parameterCollection;
  362.         }
  364.         $this->parameters = $parameters;
  366.         return $this;
  367.     }
  369.     /**
  370.      * Sets a query parameter.
  371.      *
  372.      * @param string|int      $key   The parameter position or name.
  373.      * @param mixed           $value The parameter value.
  374.      * @param string|int|null $type  The parameter type. If specified, the given value will be run through
  375.      *                               the type conversion of this type. This is usually not needed for
  376.      *                               strings and numeric types.
  377.      *
  378.      * @return $this
  379.      */
  380.     public function setParameter($key, $value, $type = null)
  381.     {
  382.         $existingParameter = $this->getParameter($key);
  384.         if ($existingParameter !== null) {
  385.             $existingParameter->setValue($value, $type);
  387.             return $this;
  388.         }
  390.         $this->parameters->add(new Parameter($key, $value, $type));
  392.         return $this;
  393.     }
  395.     /**
  396.      * Processes an individual parameter value.
  397.      *
  398.      * @param mixed $value
  399.      *
  400.      * @return mixed
  401.      *
  402.      * @throws ORMInvalidArgumentException
  403.      */
  404.     public function processParameterValue($value)
  405.     {
  406.         if (is_scalar($value)) {
  407.             return $value;
  408.         }
  410.         if ($value instanceof Collection) {
  411.             $value = iterator_to_array($value);
  412.         }
  414.         if (is_array($value)) {
  415.             $value = $this->processArrayParameterValue($value);
  417.             return $value;
  418.         }
  420.         if ($value instanceof Mapping\ClassMetadata) {
  421.             return $value->name;
  422.         }
  424.         if ($value instanceof BackedEnum) {
  425.             return $value->value;
  426.         }
  428.         if (! is_object($value)) {
  429.             return $value;
  430.         }
  432.         try {
  433.             $class = DefaultProxyClassNameResolver::getClass($value);
  434.             $value = $this->_em->getUnitOfWork()->getSingleIdentifierValue($value);
  436.             if ($value === null) {
  437.                 throw ORMInvalidArgumentException::invalidIdentifierBindingEntity($class);
  438.             }
  439.         } catch (MappingException | ORMMappingException $e) {
  440.             /* Silence any mapping exceptions. These can occur if the object in
  441.                question is not a mapped entity, in which case we just don't do
  442.                any preparation on the value.
  443.                Depending on MappingDriver, either MappingException or
  444.                ORMMappingException is thrown. */
  446.             $value = $this->potentiallyProcessIterable($value);
  447.         }
  449.         return $value;
  450.     }
  452.     /**
  453.      * If no mapping is detected, trying to resolve the value as a Traversable
  454.      *
  455.      * @param mixed $value
  456.      *
  457.      * @return mixed
  458.      */
  459.     private function potentiallyProcessIterable($value)
  460.     {
  461.         if ($value instanceof Traversable) {
  462.             $value = iterator_to_array($value);
  463.             $value = $this->processArrayParameterValue($value);
  464.         }
  466.         return $value;
  467.     }
  469.     /**
  470.      * Process a parameter value which was previously identified as an array
  471.      *
  472.      * @param mixed[] $value
  473.      *
  474.      * @return mixed[]
  475.      */
  476.     private function processArrayParameterValue(array $value): array
  477.     {
  478.         foreach ($value as $key => $paramValue) {
  479.             $paramValue  = $this->processParameterValue($paramValue);
  480.             $value[$key] = is_array($paramValue) ? reset($paramValue) : $paramValue;
  481.         }
  483.         return $value;
  484.     }
  486.     /**
  487.      * Sets the ResultSetMapping that should be used for hydration.
  488.      *
  489.      * @return $this
  490.      */
  491.     public function setResultSetMapping(Query\ResultSetMapping $rsm)
  492.     {
  493.         $this->translateNamespaces($rsm);
  494.         $this->_resultSetMapping = $rsm;
  496.         return $this;
  497.     }
  499.     /**
  500.      * Gets the ResultSetMapping used for hydration.
  501.      *
  502.      * @return ResultSetMapping|null
  503.      */
  504.     protected function getResultSetMapping()
  505.     {
  506.         return $this->_resultSetMapping;
  507.     }
  509.     /**
  510.      * Allows to translate entity namespaces to full qualified names.
  511.      */
  512.     private function translateNamespaces(Query\ResultSetMapping $rsm): void
  513.     {
  514.         $translate = function ($alias): string {
  515.             return $this->_em->getClassMetadata($alias)->getName();
  516.         };
  518.         $rsm->aliasMap         = array_map($translate, $rsm->aliasMap);
  519.         $rsm->declaringClasses = array_map($translate, $rsm->declaringClasses);
  520.     }
  522.     /**
  523.      * Set a cache profile for hydration caching.
  524.      *
  525.      * If no result cache driver is set in the QueryCacheProfile, the default
  526.      * result cache driver is used from the configuration.
  527.      *
  528.      * Important: Hydration caching does NOT register entities in the
  529.      * UnitOfWork when retrieved from the cache. Never use result cached
  530.      * entities for requests that also flush the EntityManager. If you want
  531.      * some form of caching with UnitOfWork registration you should use
  532.      * {@see AbstractQuery::setResultCacheProfile()}.
  533.      *
  534.      * @return $this
  535.      *
  536.      * @example
  537.      * $lifetime = 100;
  538.      * $resultKey = "abc";
  539.      * $query->setHydrationCacheProfile(new QueryCacheProfile());
  540.      * $query->setHydrationCacheProfile(new QueryCacheProfile($lifetime, $resultKey));
  541.      */
  542.     public function setHydrationCacheProfile(?QueryCacheProfile $profile = null)
  543.     {
  544.         if ($profile === null) {
  545.             if (func_num_args() < 1) {
  546.                 Deprecation::trigger(
  547.                     'doctrine/orm',
  548.                     'https://github.com/doctrine/orm/pull/9791',
  549.                     'Calling %s without arguments is deprecated, pass null instead.',
  550.                     __METHOD__
  551.                 );
  552.             }
  554.             $this->_hydrationCacheProfile = null;
  556.             return $this;
  557.         }
  559.         // DBAL 2
  560.         if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  561.             // @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.      * @psalm-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.      * @psalm-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.      * @psalm-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.      * @psalm-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.      * @psalm-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.      * @psalm-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.      * @psalm-param ArrayCollection<int, Parameter>|array<string, mixed>|null $parameters
  1087.      * @psalm-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.      * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
  1125.      * @psalm-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.      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1162.      * @psalm-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.      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1181.      * @psalm-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.      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1263.      * @psalm-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.      * @psalm-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. }