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

Open in your IDE?
  1. <?php
  3. /*
  4.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  5.  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  6.  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  7.  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  8.  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  9.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  10.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  11.  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  12.  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  13.  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  14.  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  15.  *
  16.  * This software consists of voluntary contributions made by many individuals
  17.  * and is licensed under the MIT license. For more information, see
  18.  * <http://www.doctrine-project.org>.
  19.  */
  21. namespace Doctrine\ORM;
  23. use Countable;
  24. use Doctrine\Common\Collections\ArrayCollection;
  25. use Doctrine\Common\Collections\Collection;
  26. use Doctrine\DBAL\Cache\QueryCacheProfile;
  27. use Doctrine\DBAL\Driver\ResultStatement;
  28. use Doctrine\Deprecations\Deprecation;
  29. use Doctrine\ORM\Cache\Logging\CacheLogger;
  30. use Doctrine\ORM\Cache\QueryCacheKey;
  31. use Doctrine\ORM\Cache\TimestampCacheKey;
  32. use Doctrine\ORM\Internal\Hydration\IterableResult;
  33. use Doctrine\ORM\Mapping\MappingException as ORMMappingException;
  34. use Doctrine\ORM\Query\Parameter;
  35. use Doctrine\ORM\Query\QueryException;
  36. use Doctrine\ORM\Query\ResultSetMapping;
  37. use Doctrine\Persistence\Mapping\MappingException;
  38. use Traversable;
  40. use function array_map;
  41. use function array_shift;
  42. use function count;
  43. use function is_array;
  44. use function is_numeric;
  45. use function is_object;
  46. use function is_scalar;
  47. use function iterator_count;
  48. use function iterator_to_array;
  49. use function ksort;
  50. use function reset;
  51. use function serialize;
  52. use function sha1;
  54. /**
  55.  * Base contract for ORM queries. Base class for Query and NativeQuery.
  56.  *
  57.  * @link    www.doctrine-project.org
  58.  */
  59. abstract class AbstractQuery
  60. {
  61.     /* Hydration mode constants */
  63.     /**
  64.      * Hydrates an object graph. This is the default behavior.
  65.      */
  66.     public const HYDRATE_OBJECT = 1;
  68.     /**
  69.      * Hydrates an array graph.
  70.      */
  71.     public const HYDRATE_ARRAY = 2;
  73.     /**
  74.      * Hydrates a flat, rectangular result set with scalar values.
  75.      */
  76.     public const HYDRATE_SCALAR = 3;
  78.     /**
  79.      * Hydrates a single scalar value.
  80.      */
  81.     public const HYDRATE_SINGLE_SCALAR = 4;
  83.     /**
  84.      * Very simple object hydrator (optimized for performance).
  85.      */
  86.     public const HYDRATE_SIMPLEOBJECT = 5;
  88.     /**
  89.      * The parameter map of this query.
  90.      *
  91.      * @var ArrayCollection|Parameter[]
  92.      * @psalm-var ArrayCollection<int, Parameter>
  93.      */
  94.     protected $parameters;
  96.     /**
  97.      * The user-specified ResultSetMapping to use.
  98.      *
  99.      * @var ResultSetMapping
  100.      */
  101.     protected $_resultSetMapping;
  103.     /**
  104.      * The entity manager used by this query object.
  105.      *
  106.      * @var EntityManagerInterface
  107.      */
  108.     protected $_em;
  110.     /**
  111.      * The map of query hints.
  112.      *
  113.      * @psalm-var array<string, mixed>
  114.      */
  115.     protected $_hints = [];
  117.     /**
  118.      * The hydration mode.
  119.      *
  120.      * @var string|int
  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 */
  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.      */
  159.     protected $cacheMode;
  161.     /** @var CacheLogger|null */
  162.     protected $cacheLogger;
  164.     /** @var int */
  165.     protected $lifetime = 0;
  167.     /**
  168.      * Initializes a new instance of a class derived from <tt>AbstractQuery</tt>.
  169.      */
  170.     public function __construct(EntityManagerInterface $em)
  171.     {
  172.         $this->_em        = $em;
  173.         $this->parameters = new ArrayCollection();
  174.         $this->_hints     = $em->getConfiguration()->getDefaultQueryHints();
  175.         $this->hasCache   = $this->_em->getConfiguration()->isSecondLevelCacheEnabled();
  177.         if ($this->hasCache) {
  178.             $this->cacheLogger = $em->getConfiguration()
  179.                 ->getSecondLevelCacheConfiguration()
  180.                 ->getCacheLogger();
  181.         }
  182.     }
  184.     /**
  185.      * Enable/disable second level query (result) caching for this query.
  186.      *
  187.      * @param bool $cacheable
  188.      *
  189.      * @return static This query instance.
  190.      */
  191.     public function setCacheable($cacheable)
  192.     {
  193.         $this->cacheable = (bool) $cacheable;
  195.         return $this;
  196.     }
  198.     /**
  199.      * @return bool TRUE if the query results are enable for second level cache, FALSE otherwise.
  200.      */
  201.     public function isCacheable()
  202.     {
  203.         return $this->cacheable;
  204.     }
  206.     /**
  207.      * @param string $cacheRegion
  208.      *
  209.      * @return static This query instance.
  210.      */
  211.     public function setCacheRegion($cacheRegion)
  212.     {
  213.         $this->cacheRegion = (string) $cacheRegion;
  215.         return $this;
  216.     }
  218.     /**
  219.      * Obtain the name of the second level query cache region in which query results will be stored
  220.      *
  221.      * @return string|null The cache region name; NULL indicates the default region.
  222.      */
  223.     public function getCacheRegion()
  224.     {
  225.         return $this->cacheRegion;
  226.     }
  228.     /**
  229.      * @return bool TRUE if the query cache and second level cache are enabled, FALSE otherwise.
  230.      */
  231.     protected function isCacheEnabled()
  232.     {
  233.         return $this->cacheable && $this->hasCache;
  234.     }
  236.     /**
  237.      * @return int
  238.      */
  239.     public function getLifetime()
  240.     {
  241.         return $this->lifetime;
  242.     }
  244.     /**
  245.      * Sets the life-time for this query into second level cache.
  246.      *
  247.      * @param int $lifetime
  248.      *
  249.      * @return static This query instance.
  250.      */
  251.     public function setLifetime($lifetime)
  252.     {
  253.         $this->lifetime = (int) $lifetime;
  255.         return $this;
  256.     }
  258.     /**
  259.      * @return int
  260.      */
  261.     public function getCacheMode()
  262.     {
  263.         return $this->cacheMode;
  264.     }
  266.     /**
  267.      * @param int $cacheMode
  268.      *
  269.      * @return static This query instance.
  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 static This query instance.
  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|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 static This query instance.
  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 static This query instance.
  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
  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 static This query instance.
  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 && ! $profile->getResultCacheDriver()) {
  543.             $resultCacheDriver = $this->_em->getConfiguration()->getHydrationCacheImpl();
  544.             $profile           = $profile->setResultCacheDriver($resultCacheDriver);
  545.         }
  547.         $this->_hydrationCacheProfile = $profile;
  549.         return $this;
  550.     }
  552.     /**
  553.      * @return QueryCacheProfile
  554.      */
  555.     public function getHydrationCacheProfile()
  556.     {
  557.         return $this->_hydrationCacheProfile;
  558.     }
  560.     /**
  561.      * Set a cache profile for the result cache.
  562.      *
  563.      * If no result cache driver is set in the QueryCacheProfile, the default
  564.      * result cache driver is used from the configuration.
  565.      *
  566.      * @return static This query instance.
  567.      */
  568.     public function setResultCacheProfile(?QueryCacheProfile $profile = null)
  569.     {
  570.         if ($profile !== null && ! $profile->getResultCacheDriver()) {
  571.             $resultCacheDriver = $this->_em->getConfiguration()->getResultCacheImpl();
  572.             $profile           = $profile->setResultCacheDriver($resultCacheDriver);
  573.         }
  575.         $this->_queryCacheProfile = $profile;
  577.         return $this;
  578.     }
  580.     /**
  581.      * Defines a cache driver to be used for caching result sets and implicitly enables caching.
  582.      *
  583.      * @param \Doctrine\Common\Cache\Cache|null $resultCacheDriver Cache driver
  584.      *
  585.      * @return static This query instance.
  586.      *
  587.      * @throws ORMException
  588.      */
  589.     public function setResultCacheDriver($resultCacheDriver = null)
  590.     {
  591.         /** @phpstan-ignore-next-line */
  592.         if ($resultCacheDriver !== null && ! ($resultCacheDriver instanceof \Doctrine\Common\Cache\Cache)) {
  593.             throw ORMException::invalidResultCacheDriver();
  594.         }
  596.         $this->_queryCacheProfile = $this->_queryCacheProfile
  597.             ? $this->_queryCacheProfile->setResultCacheDriver($resultCacheDriver)
  598.             : new QueryCacheProfile(0, null, $resultCacheDriver);
  600.         return $this;
  601.     }
  603.     /**
  604.      * Returns the cache driver used for caching result sets.
  605.      *
  606.      * @deprecated
  607.      *
  608.      * @return \Doctrine\Common\Cache\Cache Cache driver
  609.      */
  610.     public function getResultCacheDriver()
  611.     {
  612.         if ($this->_queryCacheProfile && $this->_queryCacheProfile->getResultCacheDriver()) {
  613.             return $this->_queryCacheProfile->getResultCacheDriver();
  614.         }
  616.         return $this->_em->getConfiguration()->getResultCacheImpl();
  617.     }
  619.     /**
  620.      * Set whether or not to cache the results of this query and if so, for
  621.      * how long and which ID to use for the cache entry.
  622.      *
  623.      * @deprecated 2.7 Use {@see enableResultCache} and {@see disableResultCache} instead.
  624.      *
  625.      * @param bool   $useCache
  626.      * @param int    $lifetime
  627.      * @param string $resultCacheId
  628.      *
  629.      * @return static This query instance.
  630.      */
  631.     public function useResultCache($useCache, $lifetime = null, $resultCacheId = null)
  632.     {
  633.         return $useCache
  634.             ? $this->enableResultCache($lifetime, $resultCacheId)
  635.             : $this->disableResultCache();
  636.     }
  638.     /**
  639.      * Enables caching of the results of this query, for given or default amount of seconds
  640.      * and optionally specifies which ID to use for the cache entry.
  641.      *
  642.      * @param int|null    $lifetime      How long the cache entry is valid, in seconds.
  643.      * @param string|null $resultCacheId ID to use for the cache entry.
  644.      *
  645.      * @return static This query instance.
  646.      */
  647.     public function enableResultCache(?int $lifetime = null, ?string $resultCacheId = null): self
  648.     {
  649.         $this->setResultCacheLifetime($lifetime);
  650.         $this->setResultCacheId($resultCacheId);
  652.         return $this;
  653.     }
  655.     /**
  656.      * Disables caching of the results of this query.
  657.      *
  658.      * @return static This query instance.
  659.      */
  660.     public function disableResultCache(): self
  661.     {
  662.         $this->_queryCacheProfile = null;
  664.         return $this;
  665.     }
  667.     /**
  668.      * Defines how long the result cache will be active before expire.
  669.      *
  670.      * @param int|null $lifetime How long the cache entry is valid.
  671.      *
  672.      * @return static This query instance.
  673.      */
  674.     public function setResultCacheLifetime($lifetime)
  675.     {
  676.         $lifetime = $lifetime !== null ? (int) $lifetime : 0;
  678.         $this->_queryCacheProfile = $this->_queryCacheProfile
  679.             ? $this->_queryCacheProfile->setLifetime($lifetime)
  680.             : new QueryCacheProfile($lifetime, null, $this->_em->getConfiguration()->getResultCacheImpl());
  682.         return $this;
  683.     }
  685.     /**
  686.      * Retrieves the lifetime of resultset cache.
  687.      *
  688.      * @deprecated
  689.      *
  690.      * @return int
  691.      */
  692.     public function getResultCacheLifetime()
  693.     {
  694.         return $this->_queryCacheProfile ? $this->_queryCacheProfile->getLifetime() : 0;
  695.     }
  697.     /**
  698.      * Defines if the result cache is active or not.
  699.      *
  700.      * @param bool $expire Whether or not to force resultset cache expiration.
  701.      *
  702.      * @return static This query instance.
  703.      */
  704.     public function expireResultCache($expire = true)
  705.     {
  706.         $this->_expireResultCache = $expire;
  708.         return $this;
  709.     }
  711.     /**
  712.      * Retrieves if the resultset cache is active or not.
  713.      *
  714.      * @return bool
  715.      */
  716.     public function getExpireResultCache()
  717.     {
  718.         return $this->_expireResultCache;
  719.     }
  721.     /**
  722.      * @return QueryCacheProfile|null
  723.      */
  724.     public function getQueryCacheProfile()
  725.     {
  726.         return $this->_queryCacheProfile;
  727.     }
  729.     /**
  730.      * Change the default fetch mode of an association for this query.
  731.      *
  732.      * $fetchMode can be one of ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY
  733.      *
  734.      * @param string $class
  735.      * @param string $assocName
  736.      * @param int    $fetchMode
  737.      *
  738.      * @return static This query instance.
  739.      */
  740.     public function setFetchMode($class, $assocName, $fetchMode)
  741.     {
  742.         if ($fetchMode !== Mapping\ClassMetadata::FETCH_EAGER) {
  743.             $fetchMode = Mapping\ClassMetadata::FETCH_LAZY;
  744.         }
  746.         $this->_hints['fetchMode'][$class][$assocName] = $fetchMode;
  748.         return $this;
  749.     }
  751.     /**
  752.      * Defines the processing mode to be used during hydration / result set transformation.
  753.      *
  754.      * @param string|int $hydrationMode Doctrine processing mode to be used during hydration process.
  755.      *                                  One of the Query::HYDRATE_* constants.
  756.      *
  757.      * @return static This query instance.
  758.      */
  759.     public function setHydrationMode($hydrationMode)
  760.     {
  761.         $this->_hydrationMode = $hydrationMode;
  763.         return $this;
  764.     }
  766.     /**
  767.      * Gets the hydration mode currently used by the query.
  768.      *
  769.      * @return string|int
  770.      */
  771.     public function getHydrationMode()
  772.     {
  773.         return $this->_hydrationMode;
  774.     }
  776.     /**
  777.      * Gets the list of results for the query.
  778.      *
  779.      * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).
  780.      *
  781.      * @param string|int $hydrationMode
  782.      *
  783.      * @return mixed
  784.      */
  785.     public function getResult($hydrationMode = self::HYDRATE_OBJECT)
  786.     {
  787.         return $this->execute(null, $hydrationMode);
  788.     }
  790.     /**
  791.      * Gets the array of results for the query.
  792.      *
  793.      * Alias for execute(null, HYDRATE_ARRAY).
  794.      *
  795.      * @return mixed[]
  796.      */
  797.     public function getArrayResult()
  798.     {
  799.         return $this->execute(null, self::HYDRATE_ARRAY);
  800.     }
  802.     /**
  803.      * Gets the scalar results for the query.
  804.      *
  805.      * Alias for execute(null, HYDRATE_SCALAR).
  806.      *
  807.      * @return mixed[]
  808.      */
  809.     public function getScalarResult()
  810.     {
  811.         return $this->execute(null, self::HYDRATE_SCALAR);
  812.     }
  814.     /**
  815.      * Get exactly one result or null.
  816.      *
  817.      * @param string|int $hydrationMode
  818.      *
  819.      * @return mixed
  820.      *
  821.      * @throws NonUniqueResultException
  822.      */
  823.     public function getOneOrNullResult($hydrationMode = null)
  824.     {
  825.         try {
  826.             $result = $this->execute(null, $hydrationMode);
  827.         } catch (NoResultException $e) {
  828.             return null;
  829.         }
  831.         if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  832.             return null;
  833.         }
  835.         if (! is_array($result)) {
  836.             return $result;
  837.         }
  839.         if (count($result) > 1) {
  840.             throw new NonUniqueResultException();
  841.         }
  843.         return array_shift($result);
  844.     }
  846.     /**
  847.      * Gets the single result of the query.
  848.      *
  849.      * Enforces the presence as well as the uniqueness of the result.
  850.      *
  851.      * If the result is not unique, a NonUniqueResultException is thrown.
  852.      * If there is no result, a NoResultException is thrown.
  853.      *
  854.      * @param string|int $hydrationMode
  855.      *
  856.      * @return mixed
  857.      *
  858.      * @throws NonUniqueResultException If the query result is not unique.
  859.      * @throws NoResultException        If the query returned no result and hydration mode is not HYDRATE_SINGLE_SCALAR.
  860.      */
  861.     public function getSingleResult($hydrationMode = null)
  862.     {
  863.         $result = $this->execute(null, $hydrationMode);
  865.         if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  866.             throw new NoResultException();
  867.         }
  869.         if (! is_array($result)) {
  870.             return $result;
  871.         }
  873.         if (count($result) > 1) {
  874.             throw new NonUniqueResultException();
  875.         }
  877.         return array_shift($result);
  878.     }
  880.     /**
  881.      * Gets the single scalar result of the query.
  882.      *
  883.      * Alias for getSingleResult(HYDRATE_SINGLE_SCALAR).
  884.      *
  885.      * @return mixed The scalar result.
  886.      *
  887.      * @throws NoResultException        If the query returned no result.
  888.      * @throws NonUniqueResultException If the query result is not unique.
  889.      */
  890.     public function getSingleScalarResult()
  891.     {
  892.         return $this->getSingleResult(self::HYDRATE_SINGLE_SCALAR);
  893.     }
  895.     /**
  896.      * Sets a query hint. If the hint name is not recognized, it is silently ignored.
  897.      *
  898.      * @param string $name  The name of the hint.
  899.      * @param mixed  $value The value of the hint.
  900.      *
  901.      * @return static This query instance.
  902.      */
  903.     public function setHint($name, $value)
  904.     {
  905.         $this->_hints[$name] = $value;
  907.         return $this;
  908.     }
  910.     /**
  911.      * Gets the value of a query hint. If the hint name is not recognized, FALSE is returned.
  912.      *
  913.      * @param string $name The name of the hint.
  914.      *
  915.      * @return mixed The value of the hint or FALSE, if the hint name is not recognized.
  916.      */
  917.     public function getHint($name)
  918.     {
  919.         return $this->_hints[$name] ?? false;
  920.     }
  922.     /**
  923.      * Check if the query has a hint
  924.      *
  925.      * @param string $name The name of the hint
  926.      *
  927.      * @return bool False if the query does not have any hint
  928.      */
  929.     public function hasHint($name)
  930.     {
  931.         return isset($this->_hints[$name]);
  932.     }
  934.     /**
  935.      * Return the key value map of query hints that are currently set.
  936.      *
  937.      * @return array<string,mixed>
  938.      */
  939.     public function getHints()
  940.     {
  941.         return $this->_hints;
  942.     }
  944.     /**
  945.      * Executes the query and returns an IterableResult that can be used to incrementally
  946.      * iterate over the result.
  947.      *
  948.      * @deprecated 2.8 Use {@see toIterable} instead. See https://github.com/doctrine/orm/issues/8463
  949.      *
  950.      * @param ArrayCollection|mixed[]|null $parameters    The query parameters.
  951.      * @param string|int|null              $hydrationMode The hydration mode to use.
  952.      *
  953.      * @return IterableResult
  954.      */
  955.     public function iterate($parameters = null, $hydrationMode = null)
  956.     {
  957.         Deprecation::trigger(
  958.             'doctrine/orm',
  959.             'https://github.com/doctrine/orm/issues/8463',
  960.             'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use toIterable() instead.',
  961.             __METHOD__
  962.         );
  964.         if ($hydrationMode !== null) {
  965.             $this->setHydrationMode($hydrationMode);
  966.         }
  968.         if (! empty($parameters)) {
  969.             $this->setParameters($parameters);
  970.         }
  972.         $rsm  = $this->getResultSetMapping();
  973.         $stmt = $this->_doExecute();
  975.         return $this->_em->newHydrator($this->_hydrationMode)->iterate($stmt, $rsm, $this->_hints);
  976.     }
  978.     /**
  979.      * Executes the query and returns an iterable that can be used to incrementally
  980.      * iterate over the result.
  981.      *
  982.      * @param ArrayCollection|array|mixed[] $parameters    The query parameters.
  983.      * @param string|int|null               $hydrationMode The hydration mode to use.
  984.      * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
  985.      *
  986.      * @return iterable<mixed>
  987.      */
  988.     public function toIterable(iterable $parameters = [], $hydrationMode = null): iterable
  989.     {
  990.         if ($hydrationMode !== null) {
  991.             $this->setHydrationMode($hydrationMode);
  992.         }
  994.         if (
  995.             ($this->isCountable($parameters) && count($parameters) !== 0)
  996.             || ($parameters instanceof Traversable && iterator_count($parameters) !== 0)
  997.         ) {
  998.             $this->setParameters($parameters);
  999.         }
  1001.         $rsm = $this->getResultSetMapping();
  1003.         if ($rsm->isMixed && count($rsm->scalarMappings) > 0) {
  1004.             throw QueryException::iterateWithMixedResultNotAllowed();
  1005.         }
  1007.         $stmt = $this->_doExecute();
  1009.         return $this->_em->newHydrator($this->_hydrationMode)->toIterable($stmt, $rsm, $this->_hints);
  1010.     }
  1012.     /**
  1013.      * Executes the query.
  1014.      *
  1015.      * @param ArrayCollection|mixed[]|null $parameters    Query parameters.
  1016.      * @param string|int|null              $hydrationMode Processing mode to be used during the hydration process.
  1017.      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1018.      *
  1019.      * @return mixed
  1020.      */
  1021.     public function execute($parameters = null, $hydrationMode = null)
  1022.     {
  1023.         if ($this->cacheable && $this->isCacheEnabled()) {
  1024.             return $this->executeUsingQueryCache($parameters, $hydrationMode);
  1025.         }
  1027.         return $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1028.     }
  1030.     /**
  1031.      * Execute query ignoring second level cache.
  1032.      *
  1033.      * @param ArrayCollection|mixed[]|null $parameters
  1034.      * @param string|int|null              $hydrationMode
  1035.      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1036.      *
  1037.      * @return mixed
  1038.      */
  1039.     private function executeIgnoreQueryCache($parameters = null, $hydrationMode = null)
  1040.     {
  1041.         if ($hydrationMode !== null) {
  1042.             $this->setHydrationMode($hydrationMode);
  1043.         }
  1045.         if (! empty($parameters)) {
  1046.             $this->setParameters($parameters);
  1047.         }
  1049.         $setCacheEntry = static function ($data): void {
  1050.         };
  1052.         if ($this->_hydrationCacheProfile !== null) {
  1053.             [$cacheKey, $realCacheKey] = $this->getHydrationCacheId();
  1055.             $queryCacheProfile = $this->getHydrationCacheProfile();
  1056.             $cache             = $queryCacheProfile->getResultCacheDriver();
  1057.             $result            = $cache->fetch($cacheKey);
  1059.             if (isset($result[$realCacheKey])) {
  1060.                 return $result[$realCacheKey];
  1061.             }
  1063.             if (! $result) {
  1064.                 $result = [];
  1065.             }
  1067.             $setCacheEntry = static function ($data) use ($cache, $result, $cacheKey, $realCacheKey, $queryCacheProfile): void {
  1068.                 $result[$realCacheKey] = $data;
  1070.                 $cache->save($cacheKey, $result, $queryCacheProfile->getLifetime());
  1071.             };
  1072.         }
  1074.         $stmt = $this->_doExecute();
  1076.         if (is_numeric($stmt)) {
  1077.             $setCacheEntry($stmt);
  1079.             return $stmt;
  1080.         }
  1082.         $rsm  = $this->getResultSetMapping();
  1083.         $data = $this->_em->newHydrator($this->_hydrationMode)->hydrateAll($stmt, $rsm, $this->_hints);
  1085.         $setCacheEntry($data);
  1087.         return $data;
  1088.     }
  1090.     /**
  1091.      * Load from second level cache or executes the query and put into cache.
  1092.      *
  1093.      * @param ArrayCollection|mixed[]|null $parameters
  1094.      * @param string|int|null              $hydrationMode
  1095.      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
  1096.      *
  1097.      * @return mixed
  1098.      */
  1099.     private function executeUsingQueryCache($parameters = null, $hydrationMode = null)
  1100.     {
  1101.         $rsm        = $this->getResultSetMapping();
  1102.         $queryCache = $this->_em->getCache()->getQueryCache($this->cacheRegion);
  1103.         $queryKey   = new QueryCacheKey(
  1104.             $this->getHash(),
  1105.             $this->lifetime,
  1106.             $this->cacheMode ?: Cache::MODE_NORMAL,
  1107.             $this->getTimestampKey()
  1108.         );
  1110.         $result = $queryCache->get($queryKey, $rsm, $this->_hints);
  1112.         if ($result !== null) {
  1113.             if ($this->cacheLogger) {
  1114.                 $this->cacheLogger->queryCacheHit($queryCache->getRegion()->getName(), $queryKey);
  1115.             }
  1117.             return $result;
  1118.         }
  1120.         $result = $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1121.         $cached = $queryCache->put($queryKey, $rsm, $result, $this->_hints);
  1123.         if ($this->cacheLogger) {
  1124.             $this->cacheLogger->queryCacheMiss($queryCache->getRegion()->getName(), $queryKey);
  1126.             if ($cached) {
  1127.                 $this->cacheLogger->queryCachePut($queryCache->getRegion()->getName(), $queryKey);
  1128.             }
  1129.         }
  1131.         return $result;
  1132.     }
  1134.     private function getTimestampKey(): ?TimestampCacheKey
  1135.     {
  1136.         $entityName = reset($this->_resultSetMapping->aliasMap);
  1138.         if (empty($entityName)) {
  1139.             return null;
  1140.         }
  1142.         $metadata = $this->_em->getClassMetadata($entityName);
  1144.         return new Cache\TimestampCacheKey($metadata->rootEntityName);
  1145.     }
  1147.     /**
  1148.      * Get the result cache id to use to store the result set cache entry.
  1149.      * Will return the configured id if it exists otherwise a hash will be
  1150.      * automatically generated for you.
  1151.      *
  1152.      * @return array<string, string> ($key, $hash)
  1153.      */
  1154.     protected function getHydrationCacheId()
  1155.     {
  1156.         $parameters = [];
  1158.         foreach ($this->getParameters() as $parameter) {
  1159.             $parameters[$parameter->getName()] = $this->processParameterValue($parameter->getValue());
  1160.         }
  1162.         $sql                    = $this->getSQL();
  1163.         $queryCacheProfile      = $this->getHydrationCacheProfile();
  1164.         $hints                  = $this->getHints();
  1165.         $hints['hydrationMode'] = $this->getHydrationMode();
  1167.         ksort($hints);
  1169.         return $queryCacheProfile->generateCacheKeys($sql, $parameters, $hints);
  1170.     }
  1172.     /**
  1173.      * Set the result cache id to use to store the result set cache entry.
  1174.      * If this is not explicitly set by the developer then a hash is automatically
  1175.      * generated for you.
  1176.      *
  1177.      * @param string $id
  1178.      *
  1179.      * @return static This query instance.
  1180.      */
  1181.     public function setResultCacheId($id)
  1182.     {
  1183.         $this->_queryCacheProfile = $this->_queryCacheProfile
  1184.             ? $this->_queryCacheProfile->setCacheKey($id)
  1185.             : new QueryCacheProfile(0, $id, $this->_em->getConfiguration()->getResultCacheImpl());
  1187.         return $this;
  1188.     }
  1190.     /**
  1191.      * Get the result cache id to use to store the result set cache entry if set.
  1192.      *
  1193.      * @deprecated
  1194.      *
  1195.      * @return string
  1196.      */
  1197.     public function getResultCacheId()
  1198.     {
  1199.         return $this->_queryCacheProfile ? $this->_queryCacheProfile->getCacheKey() : null;
  1200.     }
  1202.     /**
  1203.      * Executes the query and returns a the resulting Statement object.
  1204.      *
  1205.      * @return ResultStatement|int The executed database statement that holds
  1206.      *                             the results, or an integer indicating how
  1207.      *                             many rows were affected.
  1208.      */
  1209.     abstract protected function _doExecute();
  1211.     /**
  1212.      * Cleanup Query resource when clone is called.
  1213.      *
  1214.      * @return void
  1215.      */
  1216.     public function __clone()
  1217.     {
  1218.         $this->parameters = new ArrayCollection();
  1220.         $this->_hints = [];
  1221.         $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  1222.     }
  1224.     /**
  1225.      * Generates a string of currently query to use for the cache second level cache.
  1226.      *
  1227.      * @return string
  1228.      */
  1229.     protected function getHash()
  1230.     {
  1231.         $query  = $this->getSQL();
  1232.         $hints  = $this->getHints();
  1233.         $params = array_map(function (Parameter $parameter) {
  1234.             $value = $parameter->getValue();
  1236.             // Small optimization
  1237.             // Does not invoke processParameterValue for scalar value
  1238.             if (is_scalar($value)) {
  1239.                 return $value;
  1240.             }
  1242.             return $this->processParameterValue($value);
  1243.         }, $this->parameters->getValues());
  1245.         ksort($hints);
  1247.         return sha1($query . '-' . serialize($params) . '-' . serialize($hints));
  1248.     }
  1250.     /** @param iterable<mixed> $subject */
  1251.     private function isCountable(iterable $subject): bool
  1252.     {
  1253.         return $subject instanceof Countable || is_array($subject);
  1254.     }
  1255. }