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

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