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

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