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

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 LogicException;
  26. use Psr\Cache\CacheItemPoolInterface;
  27. use Traversable;
  29. use function array_map;
  30. use function array_shift;
  31. use function assert;
  32. use function count;
  33. use function is_array;
  34. use function is_numeric;
  35. use function is_object;
  36. use function is_scalar;
  37. use function iterator_count;
  38. use function iterator_to_array;
  39. use function ksort;
  40. use function method_exists;
  41. use function reset;
  42. use function serialize;
  43. use function sha1;
  45. /**
  46.  * Base contract for ORM queries. Base class for Query and NativeQuery.
  47.  *
  48.  * @link    www.doctrine-project.org
  49.  */
  50. abstract class AbstractQuery
  51. {
  52.     /* Hydration mode constants */
  54.     /**
  55.      * Hydrates an object graph. This is the default behavior.
  56.      */
  57.     public const HYDRATE_OBJECT = 1;
  59.     /**
  60.      * Hydrates an array graph.
  61.      */
  62.     public const HYDRATE_ARRAY = 2;
  64.     /**
  65.      * Hydrates a flat, rectangular result set with scalar values.
  66.      */
  67.     public const HYDRATE_SCALAR = 3;
  69.     /**
  70.      * Hydrates a single scalar value.
  71.      */
  72.     public const HYDRATE_SINGLE_SCALAR = 4;
  74.     /**
  75.      * Very simple object hydrator (optimized for performance).
  76.      */
  77.     public const HYDRATE_SIMPLEOBJECT = 5;
  79.     /**
  80.      * Hydrates scalar column value.
  81.      */
  82.     public const HYDRATE_SCALAR_COLUMN = 6;
  84.     /**
  85.      * The parameter map of this query.
  86.      *
  87.      * @var ArrayCollection|Parameter[]
  88.      * @psalm-var ArrayCollection<int, Parameter>
  89.      */
  90.     protected $parameters;
  92.     /**
  93.      * The user-specified ResultSetMapping to use.
  94.      *
  95.      * @var ResultSetMapping|null
  96.      */
  97.     protected $_resultSetMapping;
  99.     /**
  100.      * The entity manager used by this query object.
  101.      *
  102.      * @var EntityManagerInterface
  103.      */
  104.     protected $_em;
  106.     /**
  107.      * The map of query hints.
  108.      *
  109.      * @psalm-var array<string, mixed>
  110.      */
  111.     protected $_hints = [];
  113.     /**
  114.      * The hydration mode.
  115.      *
  116.      * @var string|int
  117.      * @psalm-var string|AbstractQuery::HYDRATE_*
  118.      */
  119.     protected $_hydrationMode = self::HYDRATE_OBJECT;
  121.     /** @var QueryCacheProfile|null */
  122.     protected $_queryCacheProfile;
  124.     /**
  125.      * Whether or not expire the result cache.
  126.      *
  127.      * @var bool
  128.      */
  129.     protected $_expireResultCache = false;
  131.     /** @var QueryCacheProfile|null */
  132.     protected $_hydrationCacheProfile;
  134.     /**
  135.      * Whether to use second level cache, if available.
  136.      *
  137.      * @var bool
  138.      */
  139.     protected $cacheable = false;
  141.     /** @var bool */
  142.     protected $hasCache = false;
  144.     /**
  145.      * Second level cache region name.
  146.      *
  147.      * @var string|null
  148.      */
  149.     protected $cacheRegion;
  151.     /**
  152.      * Second level query cache mode.
  153.      *
  154.      * @var int|null
  155.      * @psalm-var Cache::MODE_*|null
  156.      */
  157.     protected $cacheMode;
  159.     /** @var CacheLogger|null */
  160.     protected $cacheLogger;
  162.     /** @var int */
  163.     protected $lifetime = 0;
  165.     /**
  166.      * Initializes a new instance of a class derived from <tt>AbstractQuery</tt>.
  167.      */
  168.     public function __construct(EntityManagerInterface $em)
  169.     {
  170.         $this->_em        = $em;
  171.         $this->parameters = new ArrayCollection();
  172.         $this->_hints     = $em->getConfiguration()->getDefaultQueryHints();
  173.         $this->hasCache   = $this->_em->getConfiguration()->isSecondLevelCacheEnabled();
  175.         if ($this->hasCache) {
  176.             $this->cacheLogger = $em->getConfiguration()
  177.                 ->getSecondLevelCacheConfiguration()
  178.                 ->getCacheLogger();
  179.         }
  180.     }
  182.     /**
  183.      * Enable/disable second level query (result) caching for this query.
  184.      *
  185.      * @param bool $cacheable
  186.      *
  187.      * @return $this
  188.      */
  189.     public function setCacheable($cacheable)
  190.     {
  191.         $this->cacheable = (bool) $cacheable;
  193.         return $this;
  194.     }
  196.     /**
  197.      * @return bool TRUE if the query results are enable for second level cache, FALSE otherwise.
  198.      */
  199.     public function isCacheable()
  200.     {
  201.         return $this->cacheable;
  202.     }
  204.     /**
  205.      * @param string $cacheRegion
  206.      *
  207.      * @return $this
  208.      */
  209.     public function setCacheRegion($cacheRegion)
  210.     {
  211.         $this->cacheRegion = (string) $cacheRegion;
  213.         return $this;
  214.     }
  216.     /**
  217.      * Obtain the name of the second level query cache region in which query results will be stored
  218.      *
  219.      * @return string|null The cache region name; NULL indicates the default region.
  220.      */
  221.     public function getCacheRegion()
  222.     {
  223.         return $this->cacheRegion;
  224.     }
  226.     /**
  227.      * @return bool TRUE if the query cache and second level cache are enabled, FALSE otherwise.
  228.      */
  229.     protected function isCacheEnabled()
  230.     {
  231.         return $this->cacheable && $this->hasCache;
  232.     }
  234.     /**
  235.      * @return int
  236.      */
  237.     public function getLifetime()
  238.     {
  239.         return $this->lifetime;
  240.     }
  242.     /**
  243.      * Sets the life-time for this query into second level cache.
  244.      *
  245.      * @param int $lifetime
  246.      *
  247.      * @return $this
  248.      */
  249.     public function setLifetime($lifetime)
  250.     {
  251.         $this->lifetime = (int) $lifetime;
  253.         return $this;
  254.     }
  256.     /**
  257.      * @return int|null
  258.      * @psalm-return Cache::MODE_*|null
  259.      */
  260.     public function getCacheMode()
  261.     {
  262.         return $this->cacheMode;
  263.     }
  265.     /**
  266.      * @param int $cacheMode
  267.      * @psalm-param Cache::MODE_* $cacheMode
  268.      *
  269.      * @return $this
  270.      */
  271.     public function setCacheMode($cacheMode)
  272.     {
  273.         $this->cacheMode = (int) $cacheMode;
  275.         return $this;
  276.     }
  278.     /**
  279.      * Gets the SQL query that corresponds to this query object.
  280.      * The returned SQL syntax depends on the connection driver that is used
  281.      * by this query object at the time of this method call.
  282.      *
  283.      * @return string SQL query
  284.      */
  285.     abstract public function getSQL();
  287.     /**
  288.      * Retrieves the associated EntityManager of this Query instance.
  289.      *
  290.      * @return EntityManagerInterface
  291.      */
  292.     public function getEntityManager()
  293.     {
  294.         return $this->_em;
  295.     }
  297.     /**
  298.      * Frees the resources used by the query object.
  299.      *
  300.      * Resets Parameters, Parameter Types and Query Hints.
  301.      *
  302.      * @return void
  303.      */
  304.     public function free()
  305.     {
  306.         $this->parameters = new ArrayCollection();
  308.         $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  309.     }
  311.     /**
  312.      * Get all defined parameters.
  313.      *
  314.      * @return ArrayCollection The defined query parameters.
  315.      * @psalm-return ArrayCollection<int, Parameter>
  316.      */
  317.     public function getParameters()
  318.     {
  319.         return $this->parameters;
  320.     }
  322.     /**
  323.      * Gets a query parameter.
  324.      *
  325.      * @param mixed $key The key (index or name) of the bound parameter.
  326.      *
  327.      * @return Parameter|null The value of the bound parameter, or NULL if not available.
  328.      */
  329.     public function getParameter($key)
  330.     {
  331.         $key = Query\Parameter::normalizeName($key);
  333.         $filteredParameters = $this->parameters->filter(
  334.             static function (Query\Parameter $parameter) use ($key): bool {
  335.                 $parameterName = $parameter->getName();
  337.                 return $key === $parameterName;
  338.             }
  339.         );
  341.         return ! $filteredParameters->isEmpty() ? $filteredParameters->first() : null;
  342.     }
  344.     /**
  345.      * Sets a collection of query parameters.
  346.      *
  347.      * @param ArrayCollection|mixed[] $parameters
  348.      * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
  349.      *
  350.      * @return $this
  351.      */
  352.     public function setParameters($parameters)
  353.     {
  354.         // BC compatibility with 2.3-
  355.         if (is_array($parameters)) {
  356.             /** @psalm-var ArrayCollection<int, Parameter> $parameterCollection */
  357.             $parameterCollection = new ArrayCollection();
  359.             foreach ($parameters as $key => $value) {
  360.                 $parameterCollection->add(new Parameter($key, $value));
  361.             }
  363.             $parameters = $parameterCollection;
  364.         }
  366.         $this->parameters = $parameters;
  368.         return $this;
  369.     }
  371.     /**
  372.      * Sets a query parameter.
  373.      *
  374.      * @param string|int      $key   The parameter position or name.
  375.      * @param mixed           $value The parameter value.
  376.      * @param string|int|null $type  The parameter type. If specified, the given value will be run through
  377.      *                               the type conversion of this type. This is usually not needed for
  378.      *                               strings and numeric types.
  379.      *
  380.      * @return $this
  381.      */
  382.     public function setParameter($key, $value, $type = null)
  383.     {
  384.         $existingParameter = $this->getParameter($key);
  386.         if ($existingParameter !== null) {
  387.             $existingParameter->setValue($value, $type);
  389.             return $this;
  390.         }
  392.         $this->parameters->add(new Parameter($key, $value, $type));
  394.         return $this;
  395.     }
  397.     /**
  398.      * Processes an individual parameter value.
  399.      *
  400.      * @param mixed $value
  401.      *
  402.      * @return mixed[]|string|int|float|bool
  403.      * @psalm-return array|scalar
  404.      *
  405.      * @throws ORMInvalidArgumentException
  406.      */
  407.     public function processParameterValue($value)
  408.     {
  409.         if (is_scalar($value)) {
  410.             return $value;
  411.         }
  413.         if ($value instanceof Collection) {
  414.             $value = iterator_to_array($value);
  415.         }
  417.         if (is_array($value)) {
  418.             $value = $this->processArrayParameterValue($value);
  420.             return $value;
  421.         }
  423.         if ($value instanceof Mapping\ClassMetadata) {
  424.             return $value->name;
  425.         }
  427.         if (! is_object($value)) {
  428.             return $value;
  429.         }
  431.         try {
  432.             $value = $this->_em->getUnitOfWork()->getSingleIdentifierValue($value);
  434.             if ($value === null) {
  435.                 throw ORMInvalidArgumentException::invalidIdentifierBindingEntity();
  436.             }
  437.         } catch (MappingException | ORMMappingException $e) {
  438.             /* Silence any mapping exceptions. These can occur if the object in
  439.                question is not a mapped entity, in which case we just don't do
  440.                any preparation on the value.
  441.                Depending on MappingDriver, either MappingException or
  442.                ORMMappingException is thrown. */
  444.             $value = $this->potentiallyProcessIterable($value);
  445.         }
  447.         return $value;
  448.     }
  450.     /**
  451.      * If no mapping is detected, trying to resolve the value as a Traversable
  452.      *
  453.      * @param mixed $value
  454.      *
  455.      * @return mixed
  456.      */
  457.     private function potentiallyProcessIterable($value)
  458.     {
  459.         if ($value instanceof Traversable) {
  460.             $value = iterator_to_array($value);
  461.             $value = $this->processArrayParameterValue($value);
  462.         }
  464.         return $value;
  465.     }
  467.     /**
  468.      * Process a parameter value which was previously identified as an array
  469.      *
  470.      * @param mixed[] $value
  471.      *
  472.      * @return mixed[]
  473.      */
  474.     private function processArrayParameterValue(array $value): array
  475.     {
  476.         foreach ($value as $key => $paramValue) {
  477.             $paramValue  = $this->processParameterValue($paramValue);
  478.             $value[$key] = is_array($paramValue) ? reset($paramValue) : $paramValue;
  479.         }
  481.         return $value;
  482.     }
  484.     /**
  485.      * Sets the ResultSetMapping that should be used for hydration.
  486.      *
  487.      * @return $this
  488.      */
  489.     public function setResultSetMapping(Query\ResultSetMapping $rsm)
  490.     {
  491.         $this->translateNamespaces($rsm);
  492.         $this->_resultSetMapping = $rsm;
  494.         return $this;
  495.     }
  497.     /**
  498.      * Gets the ResultSetMapping used for hydration.
  499.      *
  500.      * @return ResultSetMapping|null
  501.      */
  502.     protected function getResultSetMapping()
  503.     {
  504.         return $this->_resultSetMapping;
  505.     }
  507.     /**
  508.      * Allows to translate entity namespaces to full qualified names.
  509.      */
  510.     private function translateNamespaces(Query\ResultSetMapping $rsm): void
  511.     {
  512.         $translate = function ($alias): string {
  513.             return $this->_em->getClassMetadata($alias)->getName();
  514.         };
  516.         $rsm->aliasMap         = array_map($translate, $rsm->aliasMap);
  517.         $rsm->declaringClasses = array_map($translate, $rsm->declaringClasses);
  518.     }
  520.     /**
  521.      * Set a cache profile for hydration caching.
  522.      *
  523.      * If no result cache driver is set in the QueryCacheProfile, the default
  524.      * result cache driver is used from the configuration.
  525.      *
  526.      * Important: Hydration caching does NOT register entities in the
  527.      * UnitOfWork when retrieved from the cache. Never use result cached
  528.      * entities for requests that also flush the EntityManager. If you want
  529.      * some form of caching with UnitOfWork registration you should use
  530.      * {@see AbstractQuery::setResultCacheProfile()}.
  531.      *
  532.      * @return $this
  533.      *
  534.      * @example
  535.      * $lifetime = 100;
  536.      * $resultKey = "abc";
  537.      * $query->setHydrationCacheProfile(new QueryCacheProfile());
  538.      * $query->setHydrationCacheProfile(new QueryCacheProfile($lifetime, $resultKey));
  539.      */
  540.     public function setHydrationCacheProfile(?QueryCacheProfile $profile = null)
  541.     {
  542.         if ($profile === null) {
  543.             $this->_hydrationCacheProfile = null;
  545.             return $this;
  546.         }
  548.         // DBAL 2
  549.         if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  550.             if (! $profile->getResultCacheDriver()) {
  551.                 $defaultHydrationCacheImpl = $this->_em->getConfiguration()->getHydrationCache();
  552.                 if ($defaultHydrationCacheImpl) {
  553.                     $profile = $profile->setResultCacheDriver(DoctrineProvider::wrap($defaultHydrationCacheImpl));
  554.                 }
  555.             }
  556.         } elseif (! $profile->getResultCache()) {
  557.             $defaultHydrationCacheImpl = $this->_em->getConfiguration()->getHydrationCache();
  558.             if ($defaultHydrationCacheImpl) {
  559.                 $profile = $profile->setResultCache($defaultHydrationCacheImpl);
  560.             }
  561.         }
  563.         $this->_hydrationCacheProfile = $profile;
  565.         return $this;
  566.     }
  568.     /**
  569.      * @return QueryCacheProfile|null
  570.      */
  571.     public function getHydrationCacheProfile()
  572.     {
  573.         return $this->_hydrationCacheProfile;
  574.     }
  576.     /**
  577.      * Set a cache profile for the result cache.
  578.      *
  579.      * If no result cache driver is set in the QueryCacheProfile, the default
  580.      * result cache driver is used from the configuration.
  581.      *
  582.      * @return $this
  583.      */
  584.     public function setResultCacheProfile(?QueryCacheProfile $profile = null)
  585.     {
  586.         if ($profile === null) {
  587.             $this->_queryCacheProfile = null;
  589.             return $this;
  590.         }
  592.         // DBAL 2
  593.         if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  594.             if (! $profile->getResultCacheDriver()) {
  595.                 $defaultResultCacheDriver = $this->_em->getConfiguration()->getResultCache();
  596.                 if ($defaultResultCacheDriver) {
  597.                     $profile = $profile->setResultCacheDriver(DoctrineProvider::wrap($defaultResultCacheDriver));
  598.                 }
  599.             }
  600.         } elseif (! $profile->getResultCache()) {
  601.             $defaultResultCache = $this->_em->getConfiguration()->getResultCache();
  602.             if ($defaultResultCache) {
  603.                 $profile = $profile->setResultCache($defaultResultCache);
  604.             }
  605.         }
  607.         $this->_queryCacheProfile = $profile;
  609.         return $this;
  610.     }
  612.     /**
  613.      * Defines a cache driver to be used for caching result sets and implicitly enables caching.
  614.      *
  615.      * @deprecated Use {@see setResultCache()} instead.
  616.      *
  617.      * @param \Doctrine\Common\Cache\Cache|null $resultCacheDriver Cache driver
  618.      *
  619.      * @return $this
  620.      *
  621.      * @throws InvalidResultCacheDriver
  622.      */
  623.     public function setResultCacheDriver($resultCacheDriver = null)
  624.     {
  625.         /** @phpstan-ignore-next-line */
  626.         if ($resultCacheDriver !== null && ! ($resultCacheDriver instanceof \Doctrine\Common\Cache\Cache)) {
  627.             throw InvalidResultCacheDriver::create();
  628.         }
  630.         return $this->setResultCache($resultCacheDriver ? CacheAdapter::wrap($resultCacheDriver) : null);
  631.     }
  633.     /**
  634.      * Defines a cache driver to be used for caching result sets and implicitly enables caching.
  635.      *
  636.      * @return $this
  637.      */
  638.     public function setResultCache(?CacheItemPoolInterface $resultCache = null)
  639.     {
  640.         if ($resultCache === null) {
  641.             if ($this->_queryCacheProfile) {
  642.                 $this->_queryCacheProfile = new QueryCacheProfile($this->_queryCacheProfile->getLifetime(), $this->_queryCacheProfile->getCacheKey());
  643.             }
  645.             return $this;
  646.         }
  648.         // DBAL 2
  649.         if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
  650.             $resultCacheDriver = DoctrineProvider::wrap($resultCache);
  652.             $this->_queryCacheProfile = $this->_queryCacheProfile
  653.                 ? $this->_queryCacheProfile->setResultCacheDriver($resultCacheDriver)
  654.                 : new QueryCacheProfile(0, null, $resultCacheDriver);
  656.             return $this;
  657.         }
  659.         $this->_queryCacheProfile = $this->_queryCacheProfile
  660.             ? $this->_queryCacheProfile->setResultCache($resultCache)
  661.             : new QueryCacheProfile(0, null, $resultCache);
  663.         return $this;
  664.     }
  666.     /**
  667.      * Returns the cache driver used for caching result sets.
  668.      *
  669.      * @deprecated
  670.      *
  671.      * @return \Doctrine\Common\Cache\Cache Cache driver
  672.      */
  673.     public function getResultCacheDriver()
  674.     {
  675.         if ($this->_queryCacheProfile && $this->_queryCacheProfile->getResultCacheDriver()) {
  676.             return $this->_queryCacheProfile->getResultCacheDriver();
  677.         }
  679.         return $this->_em->getConfiguration()->getResultCacheImpl();
  680.     }
  682.     /**
  683.      * Set whether or not to cache the results of this query and if so, for
  684.      * how long and which ID to use for the cache entry.
  685.      *
  686.      * @deprecated 2.7 Use {@see enableResultCache} and {@see disableResultCache} instead.
  687.      *
  688.      * @param bool   $useCache      Whether or not to cache the results of this query.
  689.      * @param int    $lifetime      How long the cache entry is valid, in seconds.
  690.      * @param string $resultCacheId ID to use for the cache entry.
  691.      *
  692.      * @return $this
  693.      */
  694.     public function useResultCache($useCache, $lifetime = null, $resultCacheId = null)
  695.     {
  696.         return $useCache
  697.             ? $this->enableResultCache($lifetime, $resultCacheId)
  698.             : $this->disableResultCache();
  699.     }
  701.     /**
  702.      * Enables caching of the results of this query, for given or default amount of seconds
  703.      * and optionally specifies which ID to use for the cache entry.
  704.      *
  705.      * @param int|null    $lifetime      How long the cache entry is valid, in seconds.
  706.      * @param string|null $resultCacheId ID to use for the cache entry.
  707.      *
  708.      * @return $this
  709.      */
  710.     public function enableResultCache(?int $lifetime = null, ?string $resultCacheId = null): self
  711.     {
  712.         $this->setResultCacheLifetime($lifetime);
  713.         $this->setResultCacheId($resultCacheId);
  715.         return $this;
  716.     }
  718.     /**
  719.      * Disables caching of the results of this query.
  720.      *
  721.      * @return $this
  722.      */
  723.     public function disableResultCache(): self
  724.     {
  725.         $this->_queryCacheProfile = null;
  727.         return $this;
  728.     }
  730.     /**
  731.      * Defines how long the result cache will be active before expire.
  732.      *
  733.      * @param int|null $lifetime How long the cache entry is valid, in seconds.
  734.      *
  735.      * @return $this
  736.      */
  737.     public function setResultCacheLifetime($lifetime)
  738.     {
  739.         $lifetime = (int) $lifetime;
  741.         if ($this->_queryCacheProfile) {
  742.             $this->_queryCacheProfile = $this->_queryCacheProfile->setLifetime($lifetime);
  744.             return $this;
  745.         }
  747.         $this->_queryCacheProfile = new QueryCacheProfile($lifetime);
  749.         $cache = $this->_em->getConfiguration()->getResultCache();
  750.         if (! $cache) {
  751.             return $this;
  752.         }
  754.         // Compatibility for DBAL 2
  755.         if (! method_exists($this->_queryCacheProfile, 'setResultCache')) {
  756.             $this->_queryCacheProfile = $this->_queryCacheProfile->setResultCacheDriver(DoctrineProvider::wrap($cache));
  758.             return $this;
  759.         }
  761.         $this->_queryCacheProfile = $this->_queryCacheProfile->setResultCache($cache);
  763.         return $this;
  764.     }
  766.     /**
  767.      * Retrieves the lifetime of resultset cache.
  768.      *
  769.      * @deprecated
  770.      *
  771.      * @return int
  772.      */
  773.     public function getResultCacheLifetime()
  774.     {
  775.         return $this->_queryCacheProfile ? $this->_queryCacheProfile->getLifetime() : 0;
  776.     }
  778.     /**
  779.      * Defines if the result cache is active or not.
  780.      *
  781.      * @param bool $expire Whether or not to force resultset cache expiration.
  782.      *
  783.      * @return $this
  784.      */
  785.     public function expireResultCache($expire = true)
  786.     {
  787.         $this->_expireResultCache = $expire;
  789.         return $this;
  790.     }
  792.     /**
  793.      * Retrieves if the resultset cache is active or not.
  794.      *
  795.      * @return bool
  796.      */
  797.     public function getExpireResultCache()
  798.     {
  799.         return $this->_expireResultCache;
  800.     }
  802.     /**
  803.      * @return QueryCacheProfile|null
  804.      */
  805.     public function getQueryCacheProfile()
  806.     {
  807.         return $this->_queryCacheProfile;
  808.     }
  810.     /**
  811.      * Change the default fetch mode of an association for this query.
  812.      *
  813.      * $fetchMode can be one of ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY
  814.      *
  815.      * @param string $class
  816.      * @param string $assocName
  817.      * @param int    $fetchMode
  818.      *
  819.      * @return $this
  820.      */
  821.     public function setFetchMode($class, $assocName, $fetchMode)
  822.     {
  823.         if ($fetchMode !== Mapping\ClassMetadata::FETCH_EAGER) {
  824.             $fetchMode = Mapping\ClassMetadata::FETCH_LAZY;
  825.         }
  827.         $this->_hints['fetchMode'][$class][$assocName] = $fetchMode;
  829.         return $this;
  830.     }
  832.     /**
  833.      * Defines the processing mode to be used during hydration / result set transformation.
  834.      *
  835.      * @param string|int $hydrationMode Doctrine processing mode to be used during hydration process.
  836.      *                                  One of the Query::HYDRATE_* constants.
  837.      * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
  838.      *
  839.      * @return $this
  840.      */
  841.     public function setHydrationMode($hydrationMode)
  842.     {
  843.         $this->_hydrationMode = $hydrationMode;
  845.         return $this;
  846.     }
  848.     /**
  849.      * Gets the hydration mode currently used by the query.
  850.      *
  851.      * @return string|int
  852.      * @psalm-return string|AbstractQuery::HYDRATE_*
  853.      */
  854.     public function getHydrationMode()
  855.     {
  856.         return $this->_hydrationMode;
  857.     }
  859.     /**
  860.      * Gets the list of results for the query.
  861.      *
  862.      * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).
  863.      *
  864.      * @param string|int $hydrationMode
  865.      * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
  866.      *
  867.      * @return mixed
  868.      */
  869.     public function getResult($hydrationMode = self::HYDRATE_OBJECT)
  870.     {
  871.         return $this->execute(null, $hydrationMode);
  872.     }
  874.     /**
  875.      * Gets the array of results for the query.
  876.      *
  877.      * Alias for execute(null, HYDRATE_ARRAY).
  878.      *
  879.      * @return mixed[]
  880.      */
  881.     public function getArrayResult()
  882.     {
  883.         return $this->execute(null, self::HYDRATE_ARRAY);
  884.     }
  886.     /**
  887.      * Gets one-dimensional array of results for the query.
  888.      *
  889.      * Alias for execute(null, HYDRATE_SCALAR_COLUMN).
  890.      *
  891.      * @return mixed[]
  892.      */
  893.     public function getSingleColumnResult()
  894.     {
  895.         return $this->execute(null, self::HYDRATE_SCALAR_COLUMN);
  896.     }
  898.     /**
  899.      * Gets the scalar results for the query.
  900.      *
  901.      * Alias for execute(null, HYDRATE_SCALAR).
  902.      *
  903.      * @return mixed[]
  904.      */
  905.     public function getScalarResult()
  906.     {
  907.         return $this->execute(null, self::HYDRATE_SCALAR);
  908.     }
  910.     /**
  911.      * Get exactly one result or null.
  912.      *
  913.      * @param string|int|null $hydrationMode
  914.      * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  915.      *
  916.      * @return mixed
  917.      *
  918.      * @throws NonUniqueResultException
  919.      */
  920.     public function getOneOrNullResult($hydrationMode = null)
  921.     {
  922.         try {
  923.             $result = $this->execute(null, $hydrationMode);
  924.         } catch (NoResultException $e) {
  925.             return null;
  926.         }
  928.         if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  929.             return null;
  930.         }
  932.         if (! is_array($result)) {
  933.             return $result;
  934.         }
  936.         if (count($result) > 1) {
  937.             throw new NonUniqueResultException();
  938.         }
  940.         return array_shift($result);
  941.     }
  943.     /**
  944.      * Gets the single result of the query.
  945.      *
  946.      * Enforces the presence as well as the uniqueness of the result.
  947.      *
  948.      * If the result is not unique, a NonUniqueResultException is thrown.
  949.      * If there is no result, a NoResultException is thrown.
  950.      *
  951.      * @param string|int|null $hydrationMode
  952.      * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
  953.      *
  954.      * @return mixed
  955.      *
  956.      * @throws NonUniqueResultException If the query result is not unique.
  957.      * @throws NoResultException        If the query returned no result.
  958.      */
  959.     public function getSingleResult($hydrationMode = null)
  960.     {
  961.         $result = $this->execute(null, $hydrationMode);
  963.         if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  964.             throw new NoResultException();
  965.         }
  967.         if (! is_array($result)) {
  968.             return $result;
  969.         }
  971.         if (count($result) > 1) {
  972.             throw new NonUniqueResultException();
  973.         }
  975.         return array_shift($result);
  976.     }
  978.     /**
  979.      * Gets the single scalar result of the query.
  980.      *
  981.      * Alias for getSingleResult(HYDRATE_SINGLE_SCALAR).
  982.      *
  983.      * @return mixed The scalar result.
  984.      *
  985.      * @throws NoResultException        If the query returned no result.
  986.      * @throws NonUniqueResultException If the query result is not unique.
  987.      */
  988.     public function getSingleScalarResult()
  989.     {
  990.         return $this->getSingleResult(self::HYDRATE_SINGLE_SCALAR);
  991.     }
  993.     /**
  994.      * Sets a query hint. If the hint name is not recognized, it is silently ignored.
  995.      *
  996.      * @param string $name  The name of the hint.
  997.      * @param mixed  $value The value of the hint.
  998.      *
  999.      * @return $this
  1000.      */
  1001.     public function setHint($name, $value)
  1002.     {
  1003.         $this->_hints[$name] = $value;
  1005.         return $this;
  1006.     }
  1008.     /**
  1009.      * Gets the value of a query hint. If the hint name is not recognized, FALSE is returned.
  1010.      *
  1011.      * @param string $name The name of the hint.
  1012.      *
  1013.      * @return mixed The value of the hint or FALSE, if the hint name is not recognized.
  1014.      */
  1015.     public function getHint($name)
  1016.     {
  1017.         return $this->_hints[$name] ?? false;
  1018.     }
  1020.     /**
  1021.      * Check if the query has a hint
  1022.      *
  1023.      * @param string $name The name of the hint
  1024.      *
  1025.      * @return bool False if the query does not have any hint
  1026.      */
  1027.     public function hasHint($name)
  1028.     {
  1029.         return isset($this->_hints[$name]);
  1030.     }
  1032.     /**
  1033.      * Return the key value map of query hints that are currently set.
  1034.      *
  1035.      * @return array<string,mixed>
  1036.      */
  1037.     public function getHints()
  1038.     {
  1039.         return $this->_hints;
  1040.     }
  1042.     /**
  1043.      * Executes the query and returns an IterableResult that can be used to incrementally
  1044.      * iterate over the result.
  1045.      *
  1046.      * @deprecated 2.8 Use {@see toIterable} instead. See https://github.com/doctrine/orm/issues/8463
  1047.      *
  1048.      * @param ArrayCollection|mixed[]|null $parameters    The query parameters.
  1049.      * @param string|int|null              $hydrationMode The hydration mode to use.
  1050.      * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode The hydration mode to use.
  1051.      *
  1052.      * @return IterableResult
  1053.      */
  1054.     public function iterate($parameters = null, $hydrationMode = null)
  1055.     {
  1056.         Deprecation::trigger(
  1057.             'doctrine/orm',
  1058.             'https://github.com/doctrine/orm/issues/8463',
  1059.             'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use toIterable() instead.',
  1060.             __METHOD__
  1061.         );
  1063.         if ($hydrationMode !== null) {
  1064.             $this->setHydrationMode($hydrationMode);
  1065.         }
  1067.         if (! empty($parameters)) {
  1068.             $this->setParameters($parameters);
  1069.         }
  1071.         $rsm = $this->getResultSetMapping();
  1072.         if ($rsm === null) {
  1073.             throw new LogicException('Uninitialized result set mapping.');
  1074.         }
  1076.         $stmt = $this->_doExecute();
  1078.         return $this->_em->newHydrator($this->_hydrationMode)->iterate($stmt, $rsm, $this->_hints);
  1079.     }
  1081.     /**
  1082.      * Executes the query and returns an iterable that can be used to incrementally
  1083.      * iterate over the result.
  1084.      *
  1085.      * @param ArrayCollection|array|mixed[] $parameters    The query parameters.
  1086.      * @param string|int|null               $hydrationMode The hydration mode to use.
  1087.      * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
  1088.      * @psalm-param string|AbstractQuery::HYDRATE_*|null    $hydrationMode
  1089.      *
  1090.      * @return iterable<mixed>
  1091.      */
  1092.     public function toIterable(iterable $parameters = [], $hydrationMode = null): iterable
  1093.     {
  1094.         if ($hydrationMode !== null) {
  1095.             $this->setHydrationMode($hydrationMode);
  1096.         }
  1098.         if (
  1099.             ($this->isCountable($parameters) && count($parameters) !== 0)
  1100.             || ($parameters instanceof Traversable && iterator_count($parameters) !== 0)
  1101.         ) {
  1102.             $this->setParameters($parameters);
  1103.         }
  1105.         $rsm = $this->getResultSetMapping();
  1106.         if ($rsm === null) {
  1107.             throw new LogicException('Uninitialized result set mapping.');
  1108.         }
  1110.         if ($rsm->isMixed && count($rsm->scalarMappings) > 0) {
  1111.             throw QueryException::iterateWithMixedResultNotAllowed();
  1112.         }
  1114.         $stmt = $this->_doExecute();
  1116.         return $this->_em->newHydrator($this->_hydrationMode)->toIterable($stmt, $rsm, $this->_hints);
  1117.     }
  1119.     /**
  1120.      * Executes the query.
  1121.      *
  1122.      * @param ArrayCollection|mixed[]|null $parameters    Query parameters.
  1123.      * @param string|int|null              $hydrationMode Processing mode to be used during the hydration process.
  1124.      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1125.      * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
  1126.      *
  1127.      * @return mixed
  1128.      */
  1129.     public function execute($parameters = null, $hydrationMode = null)
  1130.     {
  1131.         if ($this->cacheable && $this->isCacheEnabled()) {
  1132.             return $this->executeUsingQueryCache($parameters, $hydrationMode);
  1133.         }
  1135.         return $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1136.     }
  1138.     /**
  1139.      * Execute query ignoring second level cache.
  1140.      *
  1141.      * @param ArrayCollection|mixed[]|null $parameters
  1142.      * @param string|int|null              $hydrationMode
  1143.      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1144.      * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
  1145.      *
  1146.      * @return mixed
  1147.      */
  1148.     private function executeIgnoreQueryCache($parameters = null, $hydrationMode = null)
  1149.     {
  1150.         if ($hydrationMode !== null) {
  1151.             $this->setHydrationMode($hydrationMode);
  1152.         }
  1154.         if (! empty($parameters)) {
  1155.             $this->setParameters($parameters);
  1156.         }
  1158.         $setCacheEntry = static function ($data): void {
  1159.         };
  1161.         if ($this->_hydrationCacheProfile !== null) {
  1162.             [$cacheKey, $realCacheKey] = $this->getHydrationCacheId();
  1164.             $cache     = $this->getHydrationCache();
  1165.             $cacheItem = $cache->getItem($cacheKey);
  1166.             $result    = $cacheItem->isHit() ? $cacheItem->get() : [];
  1168.             if (isset($result[$realCacheKey])) {
  1169.                 return $result[$realCacheKey];
  1170.             }
  1172.             if (! $result) {
  1173.                 $result = [];
  1174.             }
  1176.             $setCacheEntry = static function ($data) use ($cache, $result, $cacheItem, $realCacheKey): void {
  1177.                 $cache->save($cacheItem->set($result + [$realCacheKey => $data]));
  1178.             };
  1179.         }
  1181.         $stmt = $this->_doExecute();
  1183.         if (is_numeric($stmt)) {
  1184.             $setCacheEntry($stmt);
  1186.             return $stmt;
  1187.         }
  1189.         $rsm = $this->getResultSetMapping();
  1190.         if ($rsm === null) {
  1191.             throw new LogicException('Uninitialized result set mapping.');
  1192.         }
  1194.         $data = $this->_em->newHydrator($this->_hydrationMode)->hydrateAll($stmt, $rsm, $this->_hints);
  1196.         $setCacheEntry($data);
  1198.         return $data;
  1199.     }
  1201.     private function getHydrationCache(): CacheItemPoolInterface
  1202.     {
  1203.         assert($this->_hydrationCacheProfile !== null);
  1205.         // Support for DBAL 2
  1206.         if (! method_exists($this->_hydrationCacheProfile, 'getResultCache')) {
  1207.             $cacheDriver = $this->_hydrationCacheProfile->getResultCacheDriver();
  1208.             assert($cacheDriver !== null);
  1210.             return CacheAdapter::wrap($cacheDriver);
  1211.         }
  1213.         $cache = $this->_hydrationCacheProfile->getResultCache();
  1214.         assert($cache !== null);
  1216.         return $cache;
  1217.     }
  1219.     /**
  1220.      * Load from second level cache or executes the query and put into cache.
  1221.      *
  1222.      * @param ArrayCollection|mixed[]|null $parameters
  1223.      * @param string|int|null              $hydrationMode
  1224.      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1225.      * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
  1226.      *
  1227.      * @return mixed
  1228.      */
  1229.     private function executeUsingQueryCache($parameters = null, $hydrationMode = null)
  1230.     {
  1231.         $rsm = $this->getResultSetMapping();
  1232.         if ($rsm === null) {
  1233.             throw new LogicException('Uninitialized result set mapping.');
  1234.         }
  1236.         $queryCache = $this->_em->getCache()->getQueryCache($this->cacheRegion);
  1237.         $queryKey   = new QueryCacheKey(
  1238.             $this->getHash(),
  1239.             $this->lifetime,
  1240.             $this->cacheMode ?: Cache::MODE_NORMAL,
  1241.             $this->getTimestampKey()
  1242.         );
  1244.         $result = $queryCache->get($queryKey, $rsm, $this->_hints);
  1246.         if ($result !== null) {
  1247.             if ($this->cacheLogger) {
  1248.                 $this->cacheLogger->queryCacheHit($queryCache->getRegion()->getName(), $queryKey);
  1249.             }
  1251.             return $result;
  1252.         }
  1254.         $result = $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1255.         $cached = $queryCache->put($queryKey, $rsm, $result, $this->_hints);
  1257.         if ($this->cacheLogger) {
  1258.             $this->cacheLogger->queryCacheMiss($queryCache->getRegion()->getName(), $queryKey);
  1260.             if ($cached) {
  1261.                 $this->cacheLogger->queryCachePut($queryCache->getRegion()->getName(), $queryKey);
  1262.             }
  1263.         }
  1265.         return $result;
  1266.     }
  1268.     private function getTimestampKey(): ?TimestampCacheKey
  1269.     {
  1270.         assert($this->_resultSetMapping !== null);
  1271.         $entityName = reset($this->_resultSetMapping->aliasMap);
  1273.         if (empty($entityName)) {
  1274.             return null;
  1275.         }
  1277.         $metadata = $this->_em->getClassMetadata($entityName);
  1279.         return new Cache\TimestampCacheKey($metadata->rootEntityName);
  1280.     }
  1282.     /**
  1283.      * Get the result cache id to use to store the result set cache entry.
  1284.      * Will return the configured id if it exists otherwise a hash will be
  1285.      * automatically generated for you.
  1286.      *
  1287.      * @return string[] ($key, $hash)
  1288.      * @psalm-return array{string, string} ($key, $hash)
  1289.      */
  1290.     protected function getHydrationCacheId()
  1291.     {
  1292.         $parameters = [];
  1294.         foreach ($this->getParameters() as $parameter) {
  1295.             $parameters[$parameter->getName()] = $this->processParameterValue($parameter->getValue());
  1296.         }
  1298.         $sql                    = $this->getSQL();
  1299.         $queryCacheProfile      = $this->getHydrationCacheProfile();
  1300.         $hints                  = $this->getHints();
  1301.         $hints['hydrationMode'] = $this->getHydrationMode();
  1303.         ksort($hints);
  1304.         assert($queryCacheProfile !== null);
  1306.         return $queryCacheProfile->generateCacheKeys($sql, $parameters, $hints);
  1307.     }
  1309.     /**
  1310.      * Set the result cache id to use to store the result set cache entry.
  1311.      * If this is not explicitly set by the developer then a hash is automatically
  1312.      * generated for you.
  1313.      *
  1314.      * @param string|null $id
  1315.      *
  1316.      * @return $this
  1317.      */
  1318.     public function setResultCacheId($id)
  1319.     {
  1320.         if (! $this->_queryCacheProfile) {
  1321.             return $this->setResultCacheProfile(new QueryCacheProfile(0, $id));
  1322.         }
  1324.         $this->_queryCacheProfile = $this->_queryCacheProfile->setCacheKey($id);
  1326.         return $this;
  1327.     }
  1329.     /**
  1330.      * Get the result cache id to use to store the result set cache entry if set.
  1331.      *
  1332.      * @deprecated
  1333.      *
  1334.      * @return string|null
  1335.      */
  1336.     public function getResultCacheId()
  1337.     {
  1338.         return $this->_queryCacheProfile ? $this->_queryCacheProfile->getCacheKey() : null;
  1339.     }
  1341.     /**
  1342.      * Executes the query and returns a the resulting Statement object.
  1343.      *
  1344.      * @return Result|int The executed database statement that holds
  1345.      *                    the results, or an integer indicating how
  1346.      *                    many rows were affected.
  1347.      */
  1348.     abstract protected function _doExecute();
  1350.     /**
  1351.      * Cleanup Query resource when clone is called.
  1352.      *
  1353.      * @return void
  1354.      */
  1355.     public function __clone()
  1356.     {
  1357.         $this->parameters = new ArrayCollection();
  1359.         $this->_hints = [];
  1360.         $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  1361.     }
  1363.     /**
  1364.      * Generates a string of currently query to use for the cache second level cache.
  1365.      *
  1366.      * @return string
  1367.      */
  1368.     protected function getHash()
  1369.     {
  1370.         $query  = $this->getSQL();
  1371.         $hints  = $this->getHints();
  1372.         $params = array_map(function (Parameter $parameter) {
  1373.             $value = $parameter->getValue();
  1375.             // Small optimization
  1376.             // Does not invoke processParameterValue for scalar value
  1377.             if (is_scalar($value)) {
  1378.                 return $value;
  1379.             }
  1381.             return $this->processParameterValue($value);
  1382.         }, $this->parameters->getValues());
  1384.         ksort($hints);
  1386.         return sha1($query . '-' . serialize($params) . '-' . serialize($hints));
  1387.     }
  1389.     /** @param iterable<mixed> $subject */
  1390.     private function isCountable(iterable $subject): bool
  1391.     {
  1392.         return $subject instanceof Countable || is_array($subject);
  1393.     }
  1394. }