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

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\Common\Util\ClassUtils;
  14. use Doctrine\DBAL\Cache\QueryCacheProfile;
  15. use Doctrine\DBAL\Result;
  16. use Doctrine\Deprecations\Deprecation;
  17. use Doctrine\ORM\Cache\Exception\InvalidResultCacheDriver;
  18. use Doctrine\ORM\Cache\Logging\CacheLogger;
  19. use Doctrine\ORM\Cache\QueryCacheKey;
  20. use Doctrine\ORM\Cache\TimestampCacheKey;
  21. use Doctrine\ORM\Internal\Hydration\IterableResult;
  22. use Doctrine\ORM\Mapping\MappingException as ORMMappingException;
  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.     /**
  202.      * @return bool TRUE if the query results are enabled for second level cache, FALSE otherwise.
  203.      */
  204.     public function isCacheable()
  205.     {
  206.         return $this->cacheable;
  207.     }
  209.     /**
  210.      * @param string $cacheRegion
  211.      *
  212.      * @return $this
  213.      */
  214.     public function setCacheRegion($cacheRegion)
  215.     {
  216.         $this->cacheRegion = (string) $cacheRegion;
  218.         return $this;
  219.     }
  221.     /**
  222.      * Obtain the name of the second level query cache region in which query results will be stored
  223.      *
  224.      * @return string|null The cache region name; NULL indicates the default region.
  225.      */
  226.     public function getCacheRegion()
  227.     {
  228.         return $this->cacheRegion;
  229.     }
  231.     /**
  232.      * @return bool TRUE if the query cache and second level cache are enabled, FALSE otherwise.
  233.      */
  234.     protected function isCacheEnabled()
  235.     {
  236.         return $this->cacheable && $this->hasCache;
  237.     }
  239.     /**
  240.      * @return int
  241.      */
  242.     public function getLifetime()
  243.     {
  244.         return $this->lifetime;
  245.     }
  247.     /**
  248.      * Sets the life-time for this query into second level cache.
  249.      *
  250.      * @param int $lifetime
  251.      *
  252.      * @return $this
  253.      */
  254.     public function setLifetime($lifetime)
  255.     {
  256.         $this->lifetime = (int) $lifetime;
  258.         return $this;
  259.     }
  261.     /**
  262.      * @return int|null
  263.      * @psalm-return Cache::MODE_*|null
  264.      */
  265.     public function getCacheMode()
  266.     {
  267.         return $this->cacheMode;
  268.     }
  270.     /**
  271.      * @param int $cacheMode
  272.      * @psalm-param Cache::MODE_* $cacheMode
  273.      *
  274.      * @return $this
  275.      */
  276.     public function setCacheMode($cacheMode)
  277.     {
  278.         $this->cacheMode = (int) $cacheMode;
  280.         return $this;
  281.     }
  283.     /**
  284.      * Gets the SQL query that corresponds to this query object.
  285.      * The returned SQL syntax depends on the connection driver that is used
  286.      * by this query object at the time of this method call.
  287.      *
  288.      * @return list<string>|string SQL query
  289.      */
  290.     abstract public function getSQL();
  292.     /**
  293.      * Retrieves the associated EntityManager of this Query instance.
  294.      *
  295.      * @return EntityManagerInterface
  296.      */
  297.     public function getEntityManager()
  298.     {
  299.         return $this->_em;
  300.     }
  302.     /**
  303.      * Frees the resources used by the query object.
  304.      *
  305.      * Resets Parameters, Parameter Types and Query Hints.
  306.      *
  307.      * @return void
  308.      */
  309.     public function free()
  310.     {
  311.         $this->parameters = new ArrayCollection();
  313.         $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  314.     }
  316.     /**
  317.      * Get all defined parameters.
  318.      *
  319.      * @return ArrayCollection The defined query parameters.
  320.      * @psalm-return ArrayCollection<int, Parameter>
  321.      */
  322.     public function getParameters()
  323.     {
  324.         return $this->parameters;
  325.     }
  327.     /**
  328.      * Gets a query parameter.
  329.      *
  330.      * @param int|string $key The key (index or name) of the bound parameter.
  331.      *
  332.      * @return Parameter|null The value of the bound parameter, or NULL if not available.
  333.      */
  334.     public function getParameter($key)
  335.     {
  336.         $key = Query\Parameter::normalizeName($key);
  338.         $filteredParameters = $this->parameters->filter(
  339.             static function (Query\Parameter $parameter) use ($key): bool {
  340.                 $parameterName = $parameter->getName();
  342.                 return $key === $parameterName;
  343.             }
  344.         );
  346.         return ! $filteredParameters->isEmpty() ? $filteredParameters->first() : null;
  347.     }
  349.     /**
  350.      * Sets a collection of query parameters.
  351.      *
  352.      * @param ArrayCollection|mixed[] $parameters
  353.      * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
  354.      *
  355.      * @return $this
  356.      */
  357.     public function setParameters($parameters)
  358.     {
  359.         if (is_array($parameters)) {
  360.             /** @psalm-var ArrayCollection<int, Parameter> $parameterCollection */
  361.             $parameterCollection = new ArrayCollection();
  363.             foreach ($parameters as $key => $value) {
  364.                 $parameterCollection->add(new Parameter($key, $value));
  365.             }
  367.             $parameters = $parameterCollection;
  368.         }
  370.         $this->parameters = $parameters;
  372.         return $this;
  373.     }
  375.     /**
  376.      * Sets a query parameter.
  377.      *
  378.      * @param string|int      $key   The parameter position or name.
  379.      * @param mixed           $value The parameter value.
  380.      * @param string|int|null $type  The parameter type. If specified, the given value will be run through
  381.      *                               the type conversion of this type. This is usually not needed for
  382.      *                               strings and numeric types.
  383.      *
  384.      * @return $this
  385.      */
  386.     public function setParameter($key, $value, $type = null)
  387.     {
  388.         $existingParameter = $this->getParameter($key);
  390.         if ($existingParameter !== null) {
  391.             $existingParameter->setValue($value, $type);
  393.             return $this;
  394.         }
  396.         $this->parameters->add(new Parameter($key, $value, $type));
  398.         return $this;
  399.     }
  401.     /**
  402.      * Processes an individual parameter value.
  403.      *
  404.      * @param mixed $value
  405.      *
  406.      * @return mixed
  407.      *
  408.      * @throws ORMInvalidArgumentException
  409.      */
  410.     public function processParameterValue($value)
  411.     {
  412.         if (is_scalar($value)) {
  413.             return $value;
  414.         }
  416.         if ($value instanceof Collection) {
  417.             $value = iterator_to_array($value);
  418.         }
  420.         if (is_array($value)) {
  421.             $value = $this->processArrayParameterValue($value);
  423.             return $value;
  424.         }
  426.         if ($value instanceof Mapping\ClassMetadata) {
  427.             return $value->name;
  428.         }
  430.         if ($value instanceof BackedEnum) {
  431.             return $value->value;
  432.         }
  434.         if (! is_object($value)) {
  435.             return $value;
  436.         }
  438.         try {
  439.             $class = ClassUtils::getClass($value);
  440.             $value = $this->_em->getUnitOfWork()->getSingleIdentifierValue($value);
  442.             if ($value === null) {
  443.                 throw ORMInvalidArgumentException::invalidIdentifierBindingEntity($class);
  444.             }
  445.         } catch (MappingException | ORMMappingException $e) {
  446.             /* Silence any mapping exceptions. These can occur if the object in
  447.                question is not a mapped entity, in which case we just don't do
  448.                any preparation on the value.
  449.                Depending on MappingDriver, either MappingException or
  450.                ORMMappingException is thrown. */
  452.             $value = $this->potentiallyProcessIterable($value);
  453.         }
  455.         return $value;
  456.     }
  458.     /**
  459.      * If no mapping is detected, trying to resolve the value as a Traversable
  460.      *
  461.      * @param mixed $value
  462.      *
  463.      * @return mixed
  464.      */
  465.     private function potentiallyProcessIterable($value)
  466.     {
  467.         if ($value instanceof Traversable) {
  468.             $value = iterator_to_array($value);
  469.             $value = $this->processArrayParameterValue($value);
  470.         }
  472.         return $value;
  473.     }
  475.     /**
  476.      * Process a parameter value which was previously identified as an array
  477.      *
  478.      * @param mixed[] $value
  479.      *
  480.      * @return mixed[]
  481.      */
  482.     private function processArrayParameterValue(array $value): array
  483.     {
  484.         foreach ($value as $key => $paramValue) {
  485.             $paramValue  = $this->processParameterValue($paramValue);
  486.             $value[$key] = is_array($paramValue) ? reset($paramValue) : $paramValue;
  487.         }
  489.         return $value;
  490.     }
  492.     /**
  493.      * Sets the ResultSetMapping that should be used for hydration.
  494.      *
  495.      * @return $this
  496.      */
  497.     public function setResultSetMapping(Query\ResultSetMapping $rsm)
  498.     {
  499.         $this->translateNamespaces($rsm);
  500.         $this->_resultSetMapping = $rsm;
  502.         return $this;
  503.     }
  505.     /**
  506.      * Gets the ResultSetMapping used for hydration.
  507.      *
  508.      * @return ResultSetMapping|null
  509.      */
  510.     protected function getResultSetMapping()
  511.     {
  512.         return $this->_resultSetMapping;
  513.     }
  515.     /**
  516.      * Allows to translate entity namespaces to full qualified names.
  517.      */
  518.     private function translateNamespaces(Query\ResultSetMapping $rsm): void
  519.     {
  520.         $translate = function ($alias): string {
  521.             return $this->_em->getClassMetadata($alias)->getName();
  522.         };
  524.         $rsm->aliasMap         = array_map($translate, $rsm->aliasMap);
  525.         $rsm->declaringClasses = array_map($translate, $rsm->declaringClasses);
  526.     }
  528.     /**
  529.      * Set a cache profile for hydration caching.
  530.      *
  531.      * If no result cache driver is set in the QueryCacheProfile, the default
  532.      * result cache driver is used from the configuration.
  533.      *
  534.      * Important: Hydration caching does NOT register entities in the
  535.      * UnitOfWork when retrieved from the cache. Never use result cached
  536.      * entities for requests that also flush the EntityManager. If you want
  537.      * some form of caching with UnitOfWork registration you should use
  538.      * {@see AbstractQuery::setResultCacheProfile()}.
  539.      *
  540.      * @return $this
  541.      *
  542.      * @example
  543.      * $lifetime = 100;
  544.      * $resultKey = "abc";
  545.      * $query->setHydrationCacheProfile(new QueryCacheProfile());
  546.      * $query->setHydrationCacheProfile(new QueryCacheProfile($lifetime, $resultKey));
  547.      */
  548.     public function setHydrationCacheProfile(?QueryCacheProfile $profile = null)
  549.     {
  550.         if ($profile === null) {
  551.             if (func_num_args() < 1) {
  552.                 Deprecation::trigger(
  553.                     'doctrine/orm',
  554.                     'https://github.com/doctrine/orm/pull/9791',
  555.                     'Calling %s without arguments is deprecated, pass null instead.',
  556.                     __METHOD__
  557.                 );
  558.             }
  560.             $this->_hydrationCacheProfile = null;
  562.             return $this;
  563.         }
  565.         // DBAL 2
  566.         if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  567.             if (! $profile->getResultCacheDriver()) {
  568.                 $defaultHydrationCacheImpl = $this->_em->getConfiguration()->getHydrationCache();
  569.                 if ($defaultHydrationCacheImpl) {
  570.                     $profile = $profile->setResultCacheDriver(DoctrineProvider::wrap($defaultHydrationCacheImpl));
  571.                 }
  572.             }
  573.         } elseif (! $profile->getResultCache()) {
  574.             $defaultHydrationCacheImpl = $this->_em->getConfiguration()->getHydrationCache();
  575.             if ($defaultHydrationCacheImpl) {
  576.                 $profile = $profile->setResultCache($defaultHydrationCacheImpl);
  577.             }
  578.         }
  580.         $this->_hydrationCacheProfile = $profile;
  582.         return $this;
  583.     }
  585.     /**
  586.      * @return QueryCacheProfile|null
  587.      */
  588.     public function getHydrationCacheProfile()
  589.     {
  590.         return $this->_hydrationCacheProfile;
  591.     }
  593.     /**
  594.      * Set a cache profile for the result cache.
  595.      *
  596.      * If no result cache driver is set in the QueryCacheProfile, the default
  597.      * result cache driver is used from the configuration.
  598.      *
  599.      * @return $this
  600.      */
  601.     public function setResultCacheProfile(?QueryCacheProfile $profile = null)
  602.     {
  603.         if ($profile === null) {
  604.             if (func_num_args() < 1) {
  605.                 Deprecation::trigger(
  606.                     'doctrine/orm',
  607.                     'https://github.com/doctrine/orm/pull/9791',
  608.                     'Calling %s without arguments is deprecated, pass null instead.',
  609.                     __METHOD__
  610.                 );
  611.             }
  613.             $this->_queryCacheProfile = null;
  615.             return $this;
  616.         }
  618.         // DBAL 2
  619.         if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  620.             if (! $profile->getResultCacheDriver()) {
  621.                 $defaultResultCacheDriver = $this->_em->getConfiguration()->getResultCache();
  622.                 if ($defaultResultCacheDriver) {
  623.                     $profile = $profile->setResultCacheDriver(DoctrineProvider::wrap($defaultResultCacheDriver));
  624.                 }
  625.             }
  626.         } elseif (! $profile->getResultCache()) {
  627.             $defaultResultCache = $this->_em->getConfiguration()->getResultCache();
  628.             if ($defaultResultCache) {
  629.                 $profile = $profile->setResultCache($defaultResultCache);
  630.             }
  631.         }
  633.         $this->_queryCacheProfile = $profile;
  635.         return $this;
  636.     }
  638.     /**
  639.      * Defines a cache driver to be used for caching result sets and implicitly enables caching.
  640.      *
  641.      * @deprecated Use {@see setResultCache()} instead.
  642.      *
  643.      * @param \Doctrine\Common\Cache\Cache|null $resultCacheDriver Cache driver
  644.      *
  645.      * @return $this
  646.      *
  647.      * @throws InvalidResultCacheDriver
  648.      */
  649.     public function setResultCacheDriver($resultCacheDriver = null)
  650.     {
  651.         /** @phpstan-ignore-next-line */
  652.         if ($resultCacheDriver !== null && ! ($resultCacheDriver instanceof \Doctrine\Common\Cache\Cache)) {
  653.             throw InvalidResultCacheDriver::create();
  654.         }
  656.         return $this->setResultCache($resultCacheDriver ? CacheAdapter::wrap($resultCacheDriver) : null);
  657.     }
  659.     /**
  660.      * Defines a cache driver to be used for caching result sets and implicitly enables caching.
  661.      *
  662.      * @return $this
  663.      */
  664.     public function setResultCache(?CacheItemPoolInterface $resultCache = null)
  665.     {
  666.         if ($resultCache === null) {
  667.             if (func_num_args() < 1) {
  668.                 Deprecation::trigger(
  669.                     'doctrine/orm',
  670.                     'https://github.com/doctrine/orm/pull/9791',
  671.                     'Calling %s without arguments is deprecated, pass null instead.',
  672.                     __METHOD__
  673.                 );
  674.             }
  676.             if ($this->_queryCacheProfile) {
  677.                 $this->_queryCacheProfile = new QueryCacheProfile($this->_queryCacheProfile->getLifetime(), $this->_queryCacheProfile->getCacheKey());
  678.             }
  680.             return $this;
  681.         }
  683.         // DBAL 2
  684.         if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  685.             $resultCacheDriver = DoctrineProvider::wrap($resultCache);
  687.             $this->_queryCacheProfile = $this->_queryCacheProfile
  688.                 ? $this->_queryCacheProfile->setResultCacheDriver($resultCacheDriver)
  689.                 : new QueryCacheProfile(0, null, $resultCacheDriver);
  691.             return $this;
  692.         }
  694.         $this->_queryCacheProfile = $this->_queryCacheProfile
  695.             ? $this->_queryCacheProfile->setResultCache($resultCache)
  696.             : new QueryCacheProfile(0, null, $resultCache);
  698.         return $this;
  699.     }
  701.     /**
  702.      * Returns the cache driver used for caching result sets.
  703.      *
  704.      * @deprecated
  705.      *
  706.      * @return \Doctrine\Common\Cache\Cache Cache driver
  707.      */
  708.     public function getResultCacheDriver()
  709.     {
  710.         if ($this->_queryCacheProfile && $this->_queryCacheProfile->getResultCacheDriver()) {
  711.             return $this->_queryCacheProfile->getResultCacheDriver();
  712.         }
  714.         return $this->_em->getConfiguration()->getResultCacheImpl();
  715.     }
  717.     /**
  718.      * Set whether or not to cache the results of this query and if so, for
  719.      * how long and which ID to use for the cache entry.
  720.      *
  721.      * @deprecated 2.7 Use {@see enableResultCache} and {@see disableResultCache} instead.
  722.      *
  723.      * @param bool   $useCache      Whether or not to cache the results of this query.
  724.      * @param int    $lifetime      How long the cache entry is valid, in seconds.
  725.      * @param string $resultCacheId ID to use for the cache entry.
  726.      *
  727.      * @return $this
  728.      */
  729.     public function useResultCache($useCache, $lifetime = null, $resultCacheId = null)
  730.     {
  731.         return $useCache
  732.             ? $this->enableResultCache($lifetime, $resultCacheId)
  733.             : $this->disableResultCache();
  734.     }
  736.     /**
  737.      * Enables caching of the results of this query, for given or default amount of seconds
  738.      * and optionally specifies which ID to use for the cache entry.
  739.      *
  740.      * @param int|null    $lifetime      How long the cache entry is valid, in seconds.
  741.      * @param string|null $resultCacheId ID to use for the cache entry.
  742.      *
  743.      * @return $this
  744.      */
  745.     public function enableResultCache(?int $lifetime = null, ?string $resultCacheId = null): self
  746.     {
  747.         $this->setResultCacheLifetime($lifetime);
  748.         $this->setResultCacheId($resultCacheId);
  750.         return $this;
  751.     }
  753.     /**
  754.      * Disables caching of the results of this query.
  755.      *
  756.      * @return $this
  757.      */
  758.     public function disableResultCache(): self
  759.     {
  760.         $this->_queryCacheProfile = null;
  762.         return $this;
  763.     }
  765.     /**
  766.      * Defines how long the result cache will be active before expire.
  767.      *
  768.      * @param int|null $lifetime How long the cache entry is valid, in seconds.
  769.      *
  770.      * @return $this
  771.      */
  772.     public function setResultCacheLifetime($lifetime)
  773.     {
  774.         $lifetime = (int) $lifetime;
  776.         if ($this->_queryCacheProfile) {
  777.             $this->_queryCacheProfile = $this->_queryCacheProfile->setLifetime($lifetime);
  779.             return $this;
  780.         }
  782.         $this->_queryCacheProfile = new QueryCacheProfile($lifetime);
  784.         $cache = $this->_em->getConfiguration()->getResultCache();
  785.         if (! $cache) {
  786.             return $this;
  787.         }
  789.         // Compatibility for DBAL 2
  790.         if (! method_exists($this->_queryCacheProfile, 'setResultCache')) {
  791.             $this->_queryCacheProfile = $this->_queryCacheProfile->setResultCacheDriver(DoctrineProvider::wrap($cache));
  793.             return $this;
  794.         }
  796.         $this->_queryCacheProfile = $this->_queryCacheProfile->setResultCache($cache);
  798.         return $this;
  799.     }
  801.     /**
  802.      * Retrieves the lifetime of resultset cache.
  803.      *
  804.      * @deprecated
  805.      *
  806.      * @return int
  807.      */
  808.     public function getResultCacheLifetime()
  809.     {
  810.         return $this->_queryCacheProfile ? $this->_queryCacheProfile->getLifetime() : 0;
  811.     }
  813.     /**
  814.      * Defines if the result cache is active or not.
  815.      *
  816.      * @param bool $expire Whether or not to force resultset cache expiration.
  817.      *
  818.      * @return $this
  819.      */
  820.     public function expireResultCache($expire = true)
  821.     {
  822.         $this->_expireResultCache = $expire;
  824.         return $this;
  825.     }
  827.     /**
  828.      * Retrieves if the resultset cache is active or not.
  829.      *
  830.      * @return bool
  831.      */
  832.     public function getExpireResultCache()
  833.     {
  834.         return $this->_expireResultCache;
  835.     }
  837.     /**
  838.      * @return QueryCacheProfile|null
  839.      */
  840.     public function getQueryCacheProfile()
  841.     {
  842.         return $this->_queryCacheProfile;
  843.     }
  845.     /**
  846.      * Change the default fetch mode of an association for this query.
  847.      *
  848.      * @param class-string $class
  849.      * @param string       $assocName
  850.      * @param int          $fetchMode
  851.      * @psalm-param Mapping\ClassMetadata::FETCH_EAGER|Mapping\ClassMetadata::FETCH_LAZY $fetchMode
  852.      *
  853.      * @return $this
  854.      */
  855.     public function setFetchMode($class, $assocName, $fetchMode)
  856.     {
  857.         if (! in_array($fetchMode, [Mapping\ClassMetadata::FETCH_EAGER, Mapping\ClassMetadata::FETCH_LAZY], true)) {
  858.             Deprecation::trigger(
  859.                 'doctrine/orm',
  860.                 'https://github.com/doctrine/orm/pull/9777',
  861.                 'Calling %s() with something else than ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY is deprecated.',
  862.                 __METHOD__
  863.             );
  864.             $fetchMode = Mapping\ClassMetadata::FETCH_LAZY;
  865.         }
  867.         $this->_hints['fetchMode'][$class][$assocName] = $fetchMode;
  869.         return $this;
  870.     }
  872.     /**
  873.      * Defines the processing mode to be used during hydration / result set transformation.
  874.      *
  875.      * @param string|int $hydrationMode Doctrine processing mode to be used during hydration process.
  876.      *                                  One of the Query::HYDRATE_* constants.
  877.      * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
  878.      *
  879.      * @return $this
  880.      */
  881.     public function setHydrationMode($hydrationMode)
  882.     {
  883.         $this->_hydrationMode = $hydrationMode;
  885.         return $this;
  886.     }
  888.     /**
  889.      * Gets the hydration mode currently used by the query.
  890.      *
  891.      * @return string|int
  892.      * @psalm-return string|AbstractQuery::HYDRATE_*
  893.      */
  894.     public function getHydrationMode()
  895.     {
  896.         return $this->_hydrationMode;
  897.     }
  899.     /**
  900.      * Gets the list of results for the query.
  901.      *
  902.      * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).
  903.      *
  904.      * @param string|int $hydrationMode
  905.      * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
  906.      *
  907.      * @return mixed
  908.      */
  909.     public function getResult($hydrationMode = self::HYDRATE_OBJECT)
  910.     {
  911.         return $this->execute(null, $hydrationMode);
  912.     }
  914.     /**
  915.      * Gets the array of results for the query.
  916.      *
  917.      * Alias for execute(null, HYDRATE_ARRAY).
  918.      *
  919.      * @return mixed[]
  920.      */
  921.     public function getArrayResult()
  922.     {
  923.         return $this->execute(null, self::HYDRATE_ARRAY);
  924.     }
  926.     /**
  927.      * Gets one-dimensional array of results for the query.
  928.      *
  929.      * Alias for execute(null, HYDRATE_SCALAR_COLUMN).
  930.      *
  931.      * @return mixed[]
  932.      */
  933.     public function getSingleColumnResult()
  934.     {
  935.         return $this->execute(null, self::HYDRATE_SCALAR_COLUMN);
  936.     }
  938.     /**
  939.      * Gets the scalar results for the query.
  940.      *
  941.      * Alias for execute(null, HYDRATE_SCALAR).
  942.      *
  943.      * @return mixed[]
  944.      */
  945.     public function getScalarResult()
  946.     {
  947.         return $this->execute(null, self::HYDRATE_SCALAR);
  948.     }
  950.     /**
  951.      * Get exactly one result or null.
  952.      *
  953.      * @param string|int|null $hydrationMode
  954.      * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  955.      *
  956.      * @return mixed
  957.      *
  958.      * @throws NonUniqueResultException
  959.      */
  960.     public function getOneOrNullResult($hydrationMode = null)
  961.     {
  962.         try {
  963.             $result = $this->execute(null, $hydrationMode);
  964.         } catch (NoResultException $e) {
  965.             return null;
  966.         }
  968.         if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  969.             return null;
  970.         }
  972.         if (! is_array($result)) {
  973.             return $result;
  974.         }
  976.         if (count($result) > 1) {
  977.             throw new NonUniqueResultException();
  978.         }
  980.         return array_shift($result);
  981.     }
  983.     /**
  984.      * Gets the single result of the query.
  985.      *
  986.      * Enforces the presence as well as the uniqueness of the result.
  987.      *
  988.      * If the result is not unique, a NonUniqueResultException is thrown.
  989.      * If there is no result, a NoResultException is thrown.
  990.      *
  991.      * @param string|int|null $hydrationMode
  992.      * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  993.      *
  994.      * @return mixed
  995.      *
  996.      * @throws NonUniqueResultException If the query result is not unique.
  997.      * @throws NoResultException        If the query returned no result.
  998.      */
  999.     public function getSingleResult($hydrationMode = null)
  1000.     {
  1001.         $result = $this->execute(null, $hydrationMode);
  1003.         if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  1004.             throw new NoResultException();
  1005.         }
  1007.         if (! is_array($result)) {
  1008.             return $result;
  1009.         }
  1011.         if (count($result) > 1) {
  1012.             throw new NonUniqueResultException();
  1013.         }
  1015.         return array_shift($result);
  1016.     }
  1018.     /**
  1019.      * Gets the single scalar result of the query.
  1020.      *
  1021.      * Alias for getSingleResult(HYDRATE_SINGLE_SCALAR).
  1022.      *
  1023.      * @return mixed The scalar result.
  1024.      *
  1025.      * @throws NoResultException        If the query returned no result.
  1026.      * @throws NonUniqueResultException If the query result is not unique.
  1027.      */
  1028.     public function getSingleScalarResult()
  1029.     {
  1030.         return $this->getSingleResult(self::HYDRATE_SINGLE_SCALAR);
  1031.     }
  1033.     /**
  1034.      * Sets a query hint. If the hint name is not recognized, it is silently ignored.
  1035.      *
  1036.      * @param string $name  The name of the hint.
  1037.      * @param mixed  $value The value of the hint.
  1038.      *
  1039.      * @return $this
  1040.      */
  1041.     public function setHint($name, $value)
  1042.     {
  1043.         $this->_hints[$name] = $value;
  1045.         return $this;
  1046.     }
  1048.     /**
  1049.      * Gets the value of a query hint. If the hint name is not recognized, FALSE is returned.
  1050.      *
  1051.      * @param string $name The name of the hint.
  1052.      *
  1053.      * @return mixed The value of the hint or FALSE, if the hint name is not recognized.
  1054.      */
  1055.     public function getHint($name)
  1056.     {
  1057.         return $this->_hints[$name] ?? false;
  1058.     }
  1060.     /**
  1061.      * Check if the query has a hint
  1062.      *
  1063.      * @param string $name The name of the hint
  1064.      *
  1065.      * @return bool False if the query does not have any hint
  1066.      */
  1067.     public function hasHint($name)
  1068.     {
  1069.         return isset($this->_hints[$name]);
  1070.     }
  1072.     /**
  1073.      * Return the key value map of query hints that are currently set.
  1074.      *
  1075.      * @return array<string,mixed>
  1076.      */
  1077.     public function getHints()
  1078.     {
  1079.         return $this->_hints;
  1080.     }
  1082.     /**
  1083.      * Executes the query and returns an IterableResult that can be used to incrementally
  1084.      * iterate over the result.
  1085.      *
  1086.      * @deprecated 2.8 Use {@see toIterable} instead. See https://github.com/doctrine/orm/issues/8463
  1087.      *
  1088.      * @param ArrayCollection|mixed[]|null $parameters    The query parameters.
  1089.      * @param string|int|null              $hydrationMode The hydration mode to use.
  1090.      * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode The hydration mode to use.
  1091.      *
  1092.      * @return IterableResult
  1093.      */
  1094.     public function iterate($parameters = null, $hydrationMode = null)
  1095.     {
  1096.         Deprecation::trigger(
  1097.             'doctrine/orm',
  1098.             'https://github.com/doctrine/orm/issues/8463',
  1099.             'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use toIterable() instead.',
  1100.             __METHOD__
  1101.         );
  1103.         if ($hydrationMode !== null) {
  1104.             $this->setHydrationMode($hydrationMode);
  1105.         }
  1107.         if (! empty($parameters)) {
  1108.             $this->setParameters($parameters);
  1109.         }
  1111.         $rsm = $this->getResultSetMapping();
  1112.         if ($rsm === null) {
  1113.             throw new LogicException('Uninitialized result set mapping.');
  1114.         }
  1116.         $stmt = $this->_doExecute();
  1118.         return $this->_em->newHydrator($this->_hydrationMode)->iterate($stmt, $rsm, $this->_hints);
  1119.     }
  1121.     /**
  1122.      * Executes the query and returns an iterable that can be used to incrementally
  1123.      * iterate over the result.
  1124.      *
  1125.      * @param ArrayCollection|array|mixed[] $parameters    The query parameters.
  1126.      * @param string|int|null               $hydrationMode The hydration mode to use.
  1127.      * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
  1128.      * @psalm-param string|AbstractQuery::HYDRATE_*|null    $hydrationMode
  1129.      *
  1130.      * @return iterable<mixed>
  1131.      */
  1132.     public function toIterable(iterable $parameters = [], $hydrationMode = null): iterable
  1133.     {
  1134.         if ($hydrationMode !== null) {
  1135.             $this->setHydrationMode($hydrationMode);
  1136.         }
  1138.         if (
  1139.             ($this->isCountable($parameters) && count($parameters) !== 0)
  1140.             || ($parameters instanceof Traversable && iterator_count($parameters) !== 0)
  1141.         ) {
  1142.             $this->setParameters($parameters);
  1143.         }
  1145.         $rsm = $this->getResultSetMapping();
  1146.         if ($rsm === null) {
  1147.             throw new LogicException('Uninitialized result set mapping.');
  1148.         }
  1150.         if ($rsm->isMixed && count($rsm->scalarMappings) > 0) {
  1151.             throw QueryException::iterateWithMixedResultNotAllowed();
  1152.         }
  1154.         $stmt = $this->_doExecute();
  1156.         return $this->_em->newHydrator($this->_hydrationMode)->toIterable($stmt, $rsm, $this->_hints);
  1157.     }
  1159.     /**
  1160.      * Executes the query.
  1161.      *
  1162.      * @param ArrayCollection|mixed[]|null $parameters    Query parameters.
  1163.      * @param string|int|null              $hydrationMode Processing mode to be used during the hydration process.
  1164.      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1165.      * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
  1166.      *
  1167.      * @return mixed
  1168.      */
  1169.     public function execute($parameters = null, $hydrationMode = null)
  1170.     {
  1171.         if ($this->cacheable && $this->isCacheEnabled()) {
  1172.             return $this->executeUsingQueryCache($parameters, $hydrationMode);
  1173.         }
  1175.         return $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1176.     }
  1178.     /**
  1179.      * Execute query ignoring second level cache.
  1180.      *
  1181.      * @param ArrayCollection|mixed[]|null $parameters
  1182.      * @param string|int|null              $hydrationMode
  1183.      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1184.      * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
  1185.      *
  1186.      * @return mixed
  1187.      */
  1188.     private function executeIgnoreQueryCache($parameters = null, $hydrationMode = null)
  1189.     {
  1190.         if ($hydrationMode !== null) {
  1191.             $this->setHydrationMode($hydrationMode);
  1192.         }
  1194.         if (! empty($parameters)) {
  1195.             $this->setParameters($parameters);
  1196.         }
  1198.         $setCacheEntry = static function ($data): void {
  1199.         };
  1201.         if ($this->_hydrationCacheProfile !== null) {
  1202.             [$cacheKey, $realCacheKey] = $this->getHydrationCacheId();
  1204.             $cache     = $this->getHydrationCache();
  1205.             $cacheItem = $cache->getItem($cacheKey);
  1206.             $result    = $cacheItem->isHit() ? $cacheItem->get() : [];
  1208.             if (isset($result[$realCacheKey])) {
  1209.                 return $result[$realCacheKey];
  1210.             }
  1212.             if (! $result) {
  1213.                 $result = [];
  1214.             }
  1216.             $setCacheEntry = static function ($data) use ($cache, $result, $cacheItem, $realCacheKey): void {
  1217.                 $cache->save($cacheItem->set($result + [$realCacheKey => $data]));
  1218.             };
  1219.         }
  1221.         $stmt = $this->_doExecute();
  1223.         if (is_numeric($stmt)) {
  1224.             $setCacheEntry($stmt);
  1226.             return $stmt;
  1227.         }
  1229.         $rsm = $this->getResultSetMapping();
  1230.         if ($rsm === null) {
  1231.             throw new LogicException('Uninitialized result set mapping.');
  1232.         }
  1234.         $data = $this->_em->newHydrator($this->_hydrationMode)->hydrateAll($stmt, $rsm, $this->_hints);
  1236.         $setCacheEntry($data);
  1238.         return $data;
  1239.     }
  1241.     private function getHydrationCache(): CacheItemPoolInterface
  1242.     {
  1243.         assert($this->_hydrationCacheProfile !== null);
  1245.         // Support for DBAL 2
  1246.         if (! method_exists($this->_hydrationCacheProfile, 'getResultCache')) {
  1247.             $cacheDriver = $this->_hydrationCacheProfile->getResultCacheDriver();
  1248.             assert($cacheDriver !== null);
  1250.             return CacheAdapter::wrap($cacheDriver);
  1251.         }
  1253.         $cache = $this->_hydrationCacheProfile->getResultCache();
  1254.         assert($cache !== null);
  1256.         return $cache;
  1257.     }
  1259.     /**
  1260.      * Load from second level cache or executes the query and put into cache.
  1261.      *
  1262.      * @param ArrayCollection|mixed[]|null $parameters
  1263.      * @param string|int|null              $hydrationMode
  1264.      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1265.      * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
  1266.      *
  1267.      * @return mixed
  1268.      */
  1269.     private function executeUsingQueryCache($parameters = null, $hydrationMode = null)
  1270.     {
  1271.         $rsm = $this->getResultSetMapping();
  1272.         if ($rsm === null) {
  1273.             throw new LogicException('Uninitialized result set mapping.');
  1274.         }
  1276.         $queryCache = $this->_em->getCache()->getQueryCache($this->cacheRegion);
  1277.         $queryKey   = new QueryCacheKey(
  1278.             $this->getHash(),
  1279.             $this->lifetime,
  1280.             $this->cacheMode ?: Cache::MODE_NORMAL,
  1281.             $this->getTimestampKey()
  1282.         );
  1284.         $result = $queryCache->get($queryKey, $rsm, $this->_hints);
  1286.         if ($result !== null) {
  1287.             if ($this->cacheLogger) {
  1288.                 $this->cacheLogger->queryCacheHit($queryCache->getRegion()->getName(), $queryKey);
  1289.             }
  1291.             return $result;
  1292.         }
  1294.         $result = $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1295.         $cached = $queryCache->put($queryKey, $rsm, $result, $this->_hints);
  1297.         if ($this->cacheLogger) {
  1298.             $this->cacheLogger->queryCacheMiss($queryCache->getRegion()->getName(), $queryKey);
  1300.             if ($cached) {
  1301.                 $this->cacheLogger->queryCachePut($queryCache->getRegion()->getName(), $queryKey);
  1302.             }
  1303.         }
  1305.         return $result;
  1306.     }
  1308.     private function getTimestampKey(): ?TimestampCacheKey
  1309.     {
  1310.         assert($this->_resultSetMapping !== null);
  1311.         $entityName = reset($this->_resultSetMapping->aliasMap);
  1313.         if (empty($entityName)) {
  1314.             return null;
  1315.         }
  1317.         $metadata = $this->_em->getClassMetadata($entityName);
  1319.         return new Cache\TimestampCacheKey($metadata->rootEntityName);
  1320.     }
  1322.     /**
  1323.      * Get the result cache id to use to store the result set cache entry.
  1324.      * Will return the configured id if it exists otherwise a hash will be
  1325.      * automatically generated for you.
  1326.      *
  1327.      * @return string[] ($key, $hash)
  1328.      * @psalm-return array{string, string} ($key, $hash)
  1329.      */
  1330.     protected function getHydrationCacheId()
  1331.     {
  1332.         $parameters = [];
  1334.         foreach ($this->getParameters() as $parameter) {
  1335.             $parameters[$parameter->getName()] = $this->processParameterValue($parameter->getValue());
  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, $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. }