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

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