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

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