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

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\Statement;
  28. use Doctrine\ORM\Cache\Logging\CacheLogger;
  29. use Doctrine\ORM\Cache\QueryCacheKey;
  30. use Doctrine\ORM\Cache\TimestampCacheKey;
  31. use Doctrine\ORM\Internal\Hydration\IterableResult;
  32. use Doctrine\ORM\Mapping\MappingException as ORMMappingException;
  33. use Doctrine\ORM\Query\Parameter;
  34. use Doctrine\ORM\Query\QueryException;
  35. use Doctrine\ORM\Query\ResultSetMapping;
  36. use Doctrine\Persistence\Mapping\MappingException;
  37. use Traversable;
  39. use function array_map;
  40. use function array_shift;
  41. use function count;
  42. use function is_array;
  43. use function is_numeric;
  44. use function is_object;
  45. use function is_scalar;
  46. use function iterator_count;
  47. use function iterator_to_array;
  48. use function ksort;
  49. use function reset;
  50. use function serialize;
  51. use function sha1;
  52. use function trigger_error;
  54. use const E_USER_DEPRECATED;
  56. /**
  57.  * Base contract for ORM queries. Base class for Query and NativeQuery.
  58.  *
  59.  * @link    www.doctrine-project.org
  60.  */
  61. abstract class AbstractQuery
  62. {
  63.     /* Hydration mode constants */
  65.     /**
  66.      * Hydrates an object graph. This is the default behavior.
  67.      */
  68.     public const HYDRATE_OBJECT = 1;
  70.     /**
  71.      * Hydrates an array graph.
  72.      */
  73.     public const HYDRATE_ARRAY = 2;
  75.     /**
  76.      * Hydrates a flat, rectangular result set with scalar values.
  77.      */
  78.     public const HYDRATE_SCALAR = 3;
  80.     /**
  81.      * Hydrates a single scalar value.
  82.      */
  83.     public const HYDRATE_SINGLE_SCALAR = 4;
  85.     /**
  86.      * Very simple object hydrator (optimized for performance).
  87.      */
  88.     public const HYDRATE_SIMPLEOBJECT = 5;
  90.     /**
  91.      * The parameter map of this query.
  92.      *
  93.      * @var ArrayCollection|Parameter[]
  94.      * @psalm-var ArrayCollection<int, Parameter>
  95.      */
  96.     protected $parameters;
  98.     /**
  99.      * The user-specified ResultSetMapping to use.
  100.      *
  101.      * @var ResultSetMapping
  102.      */
  103.     protected $_resultSetMapping;
  105.     /**
  106.      * The entity manager used by this query object.
  107.      *
  108.      * @var EntityManagerInterface
  109.      */
  110.     protected $_em;
  112.     /**
  113.      * The map of query hints.
  114.      *
  115.      * @psalm-var array<string, mixed>
  116.      */
  117.     protected $_hints = [];
  119.     /**
  120.      * The hydration mode.
  121.      *
  122.      * @var string|int
  123.      */
  124.     protected $_hydrationMode = self::HYDRATE_OBJECT;
  126.     /** @var QueryCacheProfile */
  127.     protected $_queryCacheProfile;
  129.     /**
  130.      * Whether or not expire the result cache.
  131.      *
  132.      * @var bool
  133.      */
  134.     protected $_expireResultCache = false;
  136.     /** @var QueryCacheProfile */
  137.     protected $_hydrationCacheProfile;
  139.     /**
  140.      * Whether to use second level cache, if available.
  141.      *
  142.      * @var bool
  143.      */
  144.     protected $cacheable = false;
  146.     /** @var bool */
  147.     protected $hasCache = false;
  149.     /**
  150.      * Second level cache region name.
  151.      *
  152.      * @var string|null
  153.      */
  154.     protected $cacheRegion;
  156.     /**
  157.      * Second level query cache mode.
  158.      *
  159.      * @var int|null
  160.      */
  161.     protected $cacheMode;
  163.     /** @var CacheLogger|null */
  164.     protected $cacheLogger;
  166.     /** @var int */
  167.     protected $lifetime = 0;
  169.     /**
  170.      * Initializes a new instance of a class derived from <tt>AbstractQuery</tt>.
  171.      */
  172.     public function __construct(EntityManagerInterface $em)
  173.     {
  174.         $this->_em        = $em;
  175.         $this->parameters = new ArrayCollection();
  176.         $this->_hints     = $em->getConfiguration()->getDefaultQueryHints();
  177.         $this->hasCache   = $this->_em->getConfiguration()->isSecondLevelCacheEnabled();
  179.         if ($this->hasCache) {
  180.             $this->cacheLogger = $em->getConfiguration()
  181.                 ->getSecondLevelCacheConfiguration()
  182.                 ->getCacheLogger();
  183.         }
  184.     }
  186.     /**
  187.      * Enable/disable second level query (result) caching for this query.
  188.      *
  189.      * @param bool $cacheable
  190.      *
  191.      * @return static This query instance.
  192.      */
  193.     public function setCacheable($cacheable)
  194.     {
  195.         $this->cacheable = (bool) $cacheable;
  197.         return $this;
  198.     }
  200.     /**
  201.      * @return bool TRUE if the query results are enable for second level cache, FALSE otherwise.
  202.      */
  203.     public function isCacheable()
  204.     {
  205.         return $this->cacheable;
  206.     }
  208.     /**
  209.      * @param string $cacheRegion
  210.      *
  211.      * @return static This query instance.
  212.      */
  213.     public function setCacheRegion($cacheRegion)
  214.     {
  215.         $this->cacheRegion = (string) $cacheRegion;
  217.         return $this;
  218.     }
  220.     /**
  221.      * Obtain the name of the second level query cache region in which query results will be stored
  222.      *
  223.      * @return string|null The cache region name; NULL indicates the default region.
  224.      */
  225.     public function getCacheRegion()
  226.     {
  227.         return $this->cacheRegion;
  228.     }
  230.     /**
  231.      * @return bool TRUE if the query cache and second level cache are enabled, FALSE otherwise.
  232.      */
  233.     protected function isCacheEnabled()
  234.     {
  235.         return $this->cacheable && $this->hasCache;
  236.     }
  238.     /**
  239.      * @return int
  240.      */
  241.     public function getLifetime()
  242.     {
  243.         return $this->lifetime;
  244.     }
  246.     /**
  247.      * Sets the life-time for this query into second level cache.
  248.      *
  249.      * @param int $lifetime
  250.      *
  251.      * @return static This query instance.
  252.      */
  253.     public function setLifetime($lifetime)
  254.     {
  255.         $this->lifetime = (int) $lifetime;
  257.         return $this;
  258.     }
  260.     /**
  261.      * @return int
  262.      */
  263.     public function getCacheMode()
  264.     {
  265.         return $this->cacheMode;
  266.     }
  268.     /**
  269.      * @param int $cacheMode
  270.      *
  271.      * @return static This query instance.
  272.      */
  273.     public function setCacheMode($cacheMode)
  274.     {
  275.         $this->cacheMode = (int) $cacheMode;
  277.         return $this;
  278.     }
  280.     /**
  281.      * Gets the SQL query that corresponds to this query object.
  282.      * The returned SQL syntax depends on the connection driver that is used
  283.      * by this query object at the time of this method call.
  284.      *
  285.      * @return string SQL query
  286.      */
  287.     abstract public function getSQL();
  289.     /**
  290.      * Retrieves the associated EntityManager of this Query instance.
  291.      *
  292.      * @return EntityManager
  293.      */
  294.     public function getEntityManager()
  295.     {
  296.         return $this->_em;
  297.     }
  299.     /**
  300.      * Frees the resources used by the query object.
  301.      *
  302.      * Resets Parameters, Parameter Types and Query Hints.
  303.      *
  304.      * @return void
  305.      */
  306.     public function free()
  307.     {
  308.         $this->parameters = new ArrayCollection();
  310.         $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  311.     }
  313.     /**
  314.      * Get all defined parameters.
  315.      *
  316.      * @return ArrayCollection The defined query parameters.
  317.      */
  318.     public function getParameters()
  319.     {
  320.         return $this->parameters;
  321.     }
  323.     /**
  324.      * Gets a query parameter.
  325.      *
  326.      * @param mixed $key The key (index or name) of the bound parameter.
  327.      *
  328.      * @return Query\Parameter|null The value of the bound parameter, or NULL if not available.
  329.      */
  330.     public function getParameter($key)
  331.     {
  332.         $key = Query\Parameter::normalizeName($key);
  334.         $filteredParameters = $this->parameters->filter(
  335.             static function (Query\Parameter $parameter) use ($key): bool {
  336.                 $parameterName = $parameter->getName();
  338.                 return $key === $parameterName;
  339.             }
  340.         );
  342.         return ! $filteredParameters->isEmpty() ? $filteredParameters->first() : null;
  343.     }
  345.     /**
  346.      * Sets a collection of query parameters.
  347.      *
  348.      * @param ArrayCollection|mixed[] $parameters
  349.      *
  350.      * @return static This query instance.
  351.      *
  352.      * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
  353.      */
  354.     public function setParameters($parameters)
  355.     {
  356.         // BC compatibility with 2.3-
  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|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 static This query instance.
  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
  405.      *
  406.      * @throws ORMInvalidArgumentException
  407.      *
  408.      * @psalm-return array|scalar
  409.      */
  410.     public function processParameterValue($value)
  411.     {
  412.         if (is_scalar($value)) {
  413.             return $value;
  414.         }
  416.         if ($value instanceof Collection) {
  417.             $value = iterator_to_array($value);
  418.         }
  420.         if (is_array($value)) {
  421.             $value = $this->processArrayParameterValue($value);
  423.             return $value;
  424.         }
  426.         if ($value instanceof Mapping\ClassMetadata) {
  427.             return $value->name;
  428.         }
  430.         if (! is_object($value)) {
  431.             return $value;
  432.         }
  434.         try {
  435.             $value = $this->_em->getUnitOfWork()->getSingleIdentifierValue($value);
  437.             if ($value === null) {
  438.                 throw ORMInvalidArgumentException::invalidIdentifierBindingEntity();
  439.             }
  440.         } catch (MappingException | ORMMappingException $e) {
  441.             /* Silence any mapping exceptions. These can occur if the object in
  442.                question is not a mapped entity, in which case we just don't do
  443.                any preparation on the value.
  444.                Depending on MappingDriver, either MappingException or
  445.                ORMMappingException is thrown. */
  447.             $value = $this->potentiallyProcessIterable($value);
  448.         }
  450.         return $value;
  451.     }
  453.     /**
  454.      * If no mapping is detected, trying to resolve the value as a Traversable
  455.      *
  456.      * @param mixed $value
  457.      *
  458.      * @return mixed
  459.      */
  460.     private function potentiallyProcessIterable($value)
  461.     {
  462.         if ($value instanceof Traversable) {
  463.             $value = iterator_to_array($value);
  464.             $value = $this->processArrayParameterValue($value);
  465.         }
  467.         return $value;
  468.     }
  470.     /**
  471.      * Process a parameter value which was previously identified as an array
  472.      *
  473.      * @param mixed[] $value
  474.      *
  475.      * @return mixed[]
  476.      */
  477.     private function processArrayParameterValue(array $value): array
  478.     {
  479.         foreach ($value as $key => $paramValue) {
  480.             $paramValue  = $this->processParameterValue($paramValue);
  481.             $value[$key] = is_array($paramValue) ? reset($paramValue) : $paramValue;
  482.         }
  484.         return $value;
  485.     }
  487.     /**
  488.      * Sets the ResultSetMapping that should be used for hydration.
  489.      *
  490.      * @return static This query instance.
  491.      */
  492.     public function setResultSetMapping(Query\ResultSetMapping $rsm)
  493.     {
  494.         $this->translateNamespaces($rsm);
  495.         $this->_resultSetMapping = $rsm;
  497.         return $this;
  498.     }
  500.     /**
  501.      * Gets the ResultSetMapping used for hydration.
  502.      *
  503.      * @return ResultSetMapping
  504.      */
  505.     protected function getResultSetMapping()
  506.     {
  507.         return $this->_resultSetMapping;
  508.     }
  510.     /**
  511.      * Allows to translate entity namespaces to full qualified names.
  512.      *
  513.      * @return void
  514.      */
  515.     private function translateNamespaces(Query\ResultSetMapping $rsm)
  516.     {
  517.         $translate = function ($alias): string {
  518.             return $this->_em->getClassMetadata($alias)->getName();
  519.         };
  521.         $rsm->aliasMap         = array_map($translate, $rsm->aliasMap);
  522.         $rsm->declaringClasses = array_map($translate, $rsm->declaringClasses);
  523.     }
  525.     /**
  526.      * Set a cache profile for hydration caching.
  527.      *
  528.      * If no result cache driver is set in the QueryCacheProfile, the default
  529.      * result cache driver is used from the configuration.
  530.      *
  531.      * Important: Hydration caching does NOT register entities in the
  532.      * UnitOfWork when retrieved from the cache. Never use result cached
  533.      * entities for requests that also flush the EntityManager. If you want
  534.      * some form of caching with UnitOfWork registration you should use
  535.      * {@see AbstractQuery::setResultCacheProfile()}.
  536.      *
  537.      * @return static This query instance.
  538.      *
  539.      * @example
  540.      * $lifetime = 100;
  541.      * $resultKey = "abc";
  542.      * $query->setHydrationCacheProfile(new QueryCacheProfile());
  543.      * $query->setHydrationCacheProfile(new QueryCacheProfile($lifetime, $resultKey));
  544.      */
  545.     public function setHydrationCacheProfile(?QueryCacheProfile $profile = null)
  546.     {
  547.         if ($profile !== null && ! $profile->getResultCacheDriver()) {
  548.             $resultCacheDriver = $this->_em->getConfiguration()->getHydrationCacheImpl();
  549.             $profile           = $profile->setResultCacheDriver($resultCacheDriver);
  550.         }
  552.         $this->_hydrationCacheProfile = $profile;
  554.         return $this;
  555.     }
  557.     /**
  558.      * @return QueryCacheProfile
  559.      */
  560.     public function getHydrationCacheProfile()
  561.     {
  562.         return $this->_hydrationCacheProfile;
  563.     }
  565.     /**
  566.      * Set a cache profile for the result cache.
  567.      *
  568.      * If no result cache driver is set in the QueryCacheProfile, the default
  569.      * result cache driver is used from the configuration.
  570.      *
  571.      * @return static This query instance.
  572.      */
  573.     public function setResultCacheProfile(?QueryCacheProfile $profile = null)
  574.     {
  575.         if ($profile !== null && ! $profile->getResultCacheDriver()) {
  576.             $resultCacheDriver = $this->_em->getConfiguration()->getResultCacheImpl();
  577.             $profile           = $profile->setResultCacheDriver($resultCacheDriver);
  578.         }
  580.         $this->_queryCacheProfile = $profile;
  582.         return $this;
  583.     }
  585.     /**
  586.      * Defines a cache driver to be used for caching result sets and implicitly enables caching.
  587.      *
  588.      * @param \Doctrine\Common\Cache\Cache|null $resultCacheDriver Cache driver
  589.      *
  590.      * @return static This query instance.
  591.      *
  592.      * @throws ORMException
  593.      */
  594.     public function setResultCacheDriver($resultCacheDriver = null)
  595.     {
  596.         if ($resultCacheDriver !== null && ! ($resultCacheDriver instanceof \Doctrine\Common\Cache\Cache)) {
  597.             throw ORMException::invalidResultCacheDriver();
  598.         }
  600.         $this->_queryCacheProfile = $this->_queryCacheProfile
  601.             ? $this->_queryCacheProfile->setResultCacheDriver($resultCacheDriver)
  602.             : new QueryCacheProfile(0, null, $resultCacheDriver);
  604.         return $this;
  605.     }
  607.     /**
  608.      * Returns the cache driver used for caching result sets.
  609.      *
  610.      * @deprecated
  611.      *
  612.      * @return \Doctrine\Common\Cache\Cache Cache driver
  613.      */
  614.     public function getResultCacheDriver()
  615.     {
  616.         if ($this->_queryCacheProfile && $this->_queryCacheProfile->getResultCacheDriver()) {
  617.             return $this->_queryCacheProfile->getResultCacheDriver();
  618.         }
  620.         return $this->_em->getConfiguration()->getResultCacheImpl();
  621.     }
  623.     /**
  624.      * Set whether or not to cache the results of this query and if so, for
  625.      * how long and which ID to use for the cache entry.
  626.      *
  627.      * @deprecated 2.7 Use {@see enableResultCache} and {@see disableResultCache} instead.
  628.      *
  629.      * @param bool   $useCache
  630.      * @param int    $lifetime
  631.      * @param string $resultCacheId
  632.      *
  633.      * @return static This query instance.
  634.      */
  635.     public function useResultCache($useCache, $lifetime = null, $resultCacheId = null)
  636.     {
  637.         return $useCache
  638.             ? $this->enableResultCache($lifetime, $resultCacheId)
  639.             : $this->disableResultCache();
  640.     }
  642.     /**
  643.      * Enables caching of the results of this query, for given or default amount of seconds
  644.      * and optionally specifies which ID to use for the cache entry.
  645.      *
  646.      * @param int|null    $lifetime      How long the cache entry is valid, in seconds.
  647.      * @param string|null $resultCacheId ID to use for the cache entry.
  648.      *
  649.      * @return static This query instance.
  650.      */
  651.     public function enableResultCache(?int $lifetime = null, ?string $resultCacheId = null): self
  652.     {
  653.         $this->setResultCacheLifetime($lifetime);
  654.         $this->setResultCacheId($resultCacheId);
  656.         return $this;
  657.     }
  659.     /**
  660.      * Disables caching of the results of this query.
  661.      *
  662.      * @return static This query instance.
  663.      */
  664.     public function disableResultCache(): self
  665.     {
  666.         $this->_queryCacheProfile = null;
  668.         return $this;
  669.     }
  671.     /**
  672.      * Defines how long the result cache will be active before expire.
  673.      *
  674.      * @param int|null $lifetime How long the cache entry is valid.
  675.      *
  676.      * @return static This query instance.
  677.      */
  678.     public function setResultCacheLifetime($lifetime)
  679.     {
  680.         $lifetime = $lifetime !== null ? (int) $lifetime : 0;
  682.         $this->_queryCacheProfile = $this->_queryCacheProfile
  683.             ? $this->_queryCacheProfile->setLifetime($lifetime)
  684.             : new QueryCacheProfile($lifetime, null, $this->_em->getConfiguration()->getResultCacheImpl());
  686.         return $this;
  687.     }
  689.     /**
  690.      * Retrieves the lifetime of resultset cache.
  691.      *
  692.      * @deprecated
  693.      *
  694.      * @return int
  695.      */
  696.     public function getResultCacheLifetime()
  697.     {
  698.         return $this->_queryCacheProfile ? $this->_queryCacheProfile->getLifetime() : 0;
  699.     }
  701.     /**
  702.      * Defines if the result cache is active or not.
  703.      *
  704.      * @param bool $expire Whether or not to force resultset cache expiration.
  705.      *
  706.      * @return static This query instance.
  707.      */
  708.     public function expireResultCache($expire = true)
  709.     {
  710.         $this->_expireResultCache = $expire;
  712.         return $this;
  713.     }
  715.     /**
  716.      * Retrieves if the resultset cache is active or not.
  717.      *
  718.      * @return bool
  719.      */
  720.     public function getExpireResultCache()
  721.     {
  722.         return $this->_expireResultCache;
  723.     }
  725.     /**
  726.      * @return QueryCacheProfile
  727.      */
  728.     public function getQueryCacheProfile()
  729.     {
  730.         return $this->_queryCacheProfile;
  731.     }
  733.     /**
  734.      * Change the default fetch mode of an association for this query.
  735.      *
  736.      * $fetchMode can be one of ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY
  737.      *
  738.      * @param string $class
  739.      * @param string $assocName
  740.      * @param int    $fetchMode
  741.      *
  742.      * @return static This query instance.
  743.      */
  744.     public function setFetchMode($class, $assocName, $fetchMode)
  745.     {
  746.         if ($fetchMode !== Mapping\ClassMetadata::FETCH_EAGER) {
  747.             $fetchMode = Mapping\ClassMetadata::FETCH_LAZY;
  748.         }
  750.         $this->_hints['fetchMode'][$class][$assocName] = $fetchMode;
  752.         return $this;
  753.     }
  755.     /**
  756.      * Defines the processing mode to be used during hydration / result set transformation.
  757.      *
  758.      * @param string|int $hydrationMode Doctrine processing mode to be used during hydration process.
  759.      *                                  One of the Query::HYDRATE_* constants.
  760.      *
  761.      * @return static This query instance.
  762.      */
  763.     public function setHydrationMode($hydrationMode)
  764.     {
  765.         $this->_hydrationMode = $hydrationMode;
  767.         return $this;
  768.     }
  770.     /**
  771.      * Gets the hydration mode currently used by the query.
  772.      *
  773.      * @return string|int
  774.      */
  775.     public function getHydrationMode()
  776.     {
  777.         return $this->_hydrationMode;
  778.     }
  780.     /**
  781.      * Gets the list of results for the query.
  782.      *
  783.      * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).
  784.      *
  785.      * @param string|int $hydrationMode
  786.      *
  787.      * @return mixed
  788.      */
  789.     public function getResult($hydrationMode = self::HYDRATE_OBJECT)
  790.     {
  791.         return $this->execute(null, $hydrationMode);
  792.     }
  794.     /**
  795.      * Gets the array of results for the query.
  796.      *
  797.      * Alias for execute(null, HYDRATE_ARRAY).
  798.      *
  799.      * @return mixed[]
  800.      */
  801.     public function getArrayResult()
  802.     {
  803.         return $this->execute(null, self::HYDRATE_ARRAY);
  804.     }
  806.     /**
  807.      * Gets the scalar results for the query.
  808.      *
  809.      * Alias for execute(null, HYDRATE_SCALAR).
  810.      *
  811.      * @return mixed[]
  812.      */
  813.     public function getScalarResult()
  814.     {
  815.         return $this->execute(null, self::HYDRATE_SCALAR);
  816.     }
  818.     /**
  819.      * Get exactly one result or null.
  820.      *
  821.      * @param string|int $hydrationMode
  822.      *
  823.      * @return mixed
  824.      *
  825.      * @throws NonUniqueResultException
  826.      */
  827.     public function getOneOrNullResult($hydrationMode = null)
  828.     {
  829.         try {
  830.             $result = $this->execute(null, $hydrationMode);
  831.         } catch (NoResultException $e) {
  832.             return null;
  833.         }
  835.         if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  836.             return null;
  837.         }
  839.         if (! is_array($result)) {
  840.             return $result;
  841.         }
  843.         if (count($result) > 1) {
  844.             throw new NonUniqueResultException();
  845.         }
  847.         return array_shift($result);
  848.     }
  850.     /**
  851.      * Gets the single result of the query.
  852.      *
  853.      * Enforces the presence as well as the uniqueness of the result.
  854.      *
  855.      * If the result is not unique, a NonUniqueResultException is thrown.
  856.      * If there is no result, a NoResultException is thrown.
  857.      *
  858.      * @param string|int $hydrationMode
  859.      *
  860.      * @return mixed
  861.      *
  862.      * @throws NonUniqueResultException If the query result is not unique.
  863.      * @throws NoResultException        If the query returned no result and hydration mode is not HYDRATE_SINGLE_SCALAR.
  864.      */
  865.     public function getSingleResult($hydrationMode = null)
  866.     {
  867.         $result = $this->execute(null, $hydrationMode);
  869.         if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  870.             throw new NoResultException();
  871.         }
  873.         if (! is_array($result)) {
  874.             return $result;
  875.         }
  877.         if (count($result) > 1) {
  878.             throw new NonUniqueResultException();
  879.         }
  881.         return array_shift($result);
  882.     }
  884.     /**
  885.      * Gets the single scalar result of the query.
  886.      *
  887.      * Alias for getSingleResult(HYDRATE_SINGLE_SCALAR).
  888.      *
  889.      * @return mixed The scalar result.
  890.      *
  891.      * @throws NoResultException        If the query returned no result.
  892.      * @throws NonUniqueResultException If the query result is not unique.
  893.      */
  894.     public function getSingleScalarResult()
  895.     {
  896.         return $this->getSingleResult(self::HYDRATE_SINGLE_SCALAR);
  897.     }
  899.     /**
  900.      * Sets a query hint. If the hint name is not recognized, it is silently ignored.
  901.      *
  902.      * @param string $name  The name of the hint.
  903.      * @param mixed  $value The value of the hint.
  904.      *
  905.      * @return static This query instance.
  906.      */
  907.     public function setHint($name, $value)
  908.     {
  909.         $this->_hints[$name] = $value;
  911.         return $this;
  912.     }
  914.     /**
  915.      * Gets the value of a query hint. If the hint name is not recognized, FALSE is returned.
  916.      *
  917.      * @param string $name The name of the hint.
  918.      *
  919.      * @return mixed The value of the hint or FALSE, if the hint name is not recognized.
  920.      */
  921.     public function getHint($name)
  922.     {
  923.         return $this->_hints[$name] ?? false;
  924.     }
  926.     /**
  927.      * Check if the query has a hint
  928.      *
  929.      * @param string $name The name of the hint
  930.      *
  931.      * @return bool False if the query does not have any hint
  932.      */
  933.     public function hasHint($name)
  934.     {
  935.         return isset($this->_hints[$name]);
  936.     }
  938.     /**
  939.      * Return the key value map of query hints that are currently set.
  940.      *
  941.      * @return array<string,mixed>
  942.      */
  943.     public function getHints()
  944.     {
  945.         return $this->_hints;
  946.     }
  948.     /**
  949.      * Executes the query and returns an IterableResult that can be used to incrementally
  950.      * iterate over the result.
  951.      *
  952.      * @deprecated
  953.      *
  954.      * @param ArrayCollection|mixed[]|null $parameters    The query parameters.
  955.      * @param string|int|null              $hydrationMode The hydration mode to use.
  956.      *
  957.      * @return IterableResult
  958.      */
  959.     public function iterate($parameters = null, $hydrationMode = null)
  960.     {
  961.         @trigger_error(
  962.             'Method ' . __METHOD__ . '() is deprecated and will be removed in Doctrine ORM 3.0. Use toIterable() instead.',
  963.             E_USER_DEPRECATED
  964.         );
  966.         if ($hydrationMode !== null) {
  967.             $this->setHydrationMode($hydrationMode);
  968.         }
  970.         if (! empty($parameters)) {
  971.             $this->setParameters($parameters);
  972.         }
  974.         $rsm  = $this->getResultSetMapping();
  975.         $stmt = $this->_doExecute();
  977.         return $this->_em->newHydrator($this->_hydrationMode)->iterate($stmt, $rsm, $this->_hints);
  978.     }
  980.     /**
  981.      * Executes the query and returns an iterable that can be used to incrementally
  982.      * iterate over the result.
  983.      *
  984.      * @param ArrayCollection|mixed[] $parameters    The query parameters.
  985.      * @param string|int|null         $hydrationMode The hydration mode to use.
  986.      *
  987.      * @return iterable<mixed>
  988.      */
  989.     public function toIterable(iterable $parameters = [], $hydrationMode = null): iterable
  990.     {
  991.         if ($hydrationMode !== null) {
  992.             $this->setHydrationMode($hydrationMode);
  993.         }
  995.         if (
  996.             ($this->isCountable($parameters) && count($parameters) !== 0)
  997.             || ($parameters instanceof Traversable && iterator_count($parameters) !== 0)
  998.         ) {
  999.             $this->setParameters($parameters);
  1000.         }
  1002.         $rsm = $this->getResultSetMapping();
  1004.         if ($rsm->isMixed && count($rsm->scalarMappings) > 0) {
  1005.             throw QueryException::iterateWithMixedResultNotAllowed();
  1006.         }
  1008.         $stmt = $this->_doExecute();
  1010.         return $this->_em->newHydrator($this->_hydrationMode)->toIterable($stmt, $rsm, $this->_hints);
  1011.     }
  1013.     /**
  1014.      * Executes the query.
  1015.      *
  1016.      * @param ArrayCollection|mixed[]|null $parameters    Query parameters.
  1017.      * @param string|int|null              $hydrationMode Processing mode to be used during the hydration process.
  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.      *
  1036.      * @return mixed
  1037.      */
  1038.     private function executeIgnoreQueryCache($parameters = null, $hydrationMode = null)
  1039.     {
  1040.         if ($hydrationMode !== null) {
  1041.             $this->setHydrationMode($hydrationMode);
  1042.         }
  1044.         if (! empty($parameters)) {
  1045.             $this->setParameters($parameters);
  1046.         }
  1048.         $setCacheEntry = static function (): void {
  1049.         };
  1051.         if ($this->_hydrationCacheProfile !== null) {
  1052.             [$cacheKey, $realCacheKey] = $this->getHydrationCacheId();
  1054.             $queryCacheProfile = $this->getHydrationCacheProfile();
  1055.             $cache             = $queryCacheProfile->getResultCacheDriver();
  1056.             $result            = $cache->fetch($cacheKey);
  1058.             if (isset($result[$realCacheKey])) {
  1059.                 return $result[$realCacheKey];
  1060.             }
  1062.             if (! $result) {
  1063.                 $result = [];
  1064.             }
  1066.             $setCacheEntry = static function ($data) use ($cache, $result, $cacheKey, $realCacheKey, $queryCacheProfile): void {
  1067.                 $result[$realCacheKey] = $data;
  1069.                 $cache->save($cacheKey, $result, $queryCacheProfile->getLifetime());
  1070.             };
  1071.         }
  1073.         $stmt = $this->_doExecute();
  1075.         if (is_numeric($stmt)) {
  1076.             $setCacheEntry($stmt);
  1078.             return $stmt;
  1079.         }
  1081.         $rsm  = $this->getResultSetMapping();
  1082.         $data = $this->_em->newHydrator($this->_hydrationMode)->hydrateAll($stmt, $rsm, $this->_hints);
  1084.         $setCacheEntry($data);
  1086.         return $data;
  1087.     }
  1089.     /**
  1090.      * Load from second level cache or executes the query and put into cache.
  1091.      *
  1092.      * @param ArrayCollection|mixed[]|null $parameters
  1093.      * @param string|int|null              $hydrationMode
  1094.      *
  1095.      * @return mixed
  1096.      */
  1097.     private function executeUsingQueryCache($parameters = null, $hydrationMode = null)
  1098.     {
  1099.         $rsm        = $this->getResultSetMapping();
  1100.         $queryCache = $this->_em->getCache()->getQueryCache($this->cacheRegion);
  1101.         $queryKey   = new QueryCacheKey(
  1102.             $this->getHash(),
  1103.             $this->lifetime,
  1104.             $this->cacheMode ?: Cache::MODE_NORMAL,
  1105.             $this->getTimestampKey()
  1106.         );
  1108.         $result = $queryCache->get($queryKey, $rsm, $this->_hints);
  1110.         if ($result !== null) {
  1111.             if ($this->cacheLogger) {
  1112.                 $this->cacheLogger->queryCacheHit($queryCache->getRegion()->getName(), $queryKey);
  1113.             }
  1115.             return $result;
  1116.         }
  1118.         $result = $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1119.         $cached = $queryCache->put($queryKey, $rsm, $result, $this->_hints);
  1121.         if ($this->cacheLogger) {
  1122.             $this->cacheLogger->queryCacheMiss($queryCache->getRegion()->getName(), $queryKey);
  1124.             if ($cached) {
  1125.                 $this->cacheLogger->queryCachePut($queryCache->getRegion()->getName(), $queryKey);
  1126.             }
  1127.         }
  1129.         return $result;
  1130.     }
  1132.     /**
  1133.      * @return TimestampCacheKey|null
  1134.      */
  1135.     private function getTimestampKey()
  1136.     {
  1137.         $entityName = reset($this->_resultSetMapping->aliasMap);
  1139.         if (empty($entityName)) {
  1140.             return null;
  1141.         }
  1143.         $metadata = $this->_em->getClassMetadata($entityName);
  1145.         return new Cache\TimestampCacheKey($metadata->rootEntityName);
  1146.     }
  1148.     /**
  1149.      * Get the result cache id to use to store the result set cache entry.
  1150.      * Will return the configured id if it exists otherwise a hash will be
  1151.      * automatically generated for you.
  1152.      *
  1153.      * @return array<string, string> ($key, $hash)
  1154.      */
  1155.     protected function getHydrationCacheId()
  1156.     {
  1157.         $parameters = [];
  1159.         foreach ($this->getParameters() as $parameter) {
  1160.             $parameters[$parameter->getName()] = $this->processParameterValue($parameter->getValue());
  1161.         }
  1163.         $sql                    = $this->getSQL();
  1164.         $queryCacheProfile      = $this->getHydrationCacheProfile();
  1165.         $hints                  = $this->getHints();
  1166.         $hints['hydrationMode'] = $this->getHydrationMode();
  1168.         ksort($hints);
  1170.         return $queryCacheProfile->generateCacheKeys($sql, $parameters, $hints);
  1171.     }
  1173.     /**
  1174.      * Set the result cache id to use to store the result set cache entry.
  1175.      * If this is not explicitly set by the developer then a hash is automatically
  1176.      * generated for you.
  1177.      *
  1178.      * @param string $id
  1179.      *
  1180.      * @return static This query instance.
  1181.      */
  1182.     public function setResultCacheId($id)
  1183.     {
  1184.         $this->_queryCacheProfile = $this->_queryCacheProfile
  1185.             ? $this->_queryCacheProfile->setCacheKey($id)
  1186.             : new QueryCacheProfile(0, $id, $this->_em->getConfiguration()->getResultCacheImpl());
  1188.         return $this;
  1189.     }
  1191.     /**
  1192.      * Get the result cache id to use to store the result set cache entry if set.
  1193.      *
  1194.      * @deprecated
  1195.      *
  1196.      * @return string
  1197.      */
  1198.     public function getResultCacheId()
  1199.     {
  1200.         return $this->_queryCacheProfile ? $this->_queryCacheProfile->getCacheKey() : null;
  1201.     }
  1203.     /**
  1204.      * Executes the query and returns a the resulting Statement object.
  1205.      *
  1206.      * @return Statement The executed database statement that holds the results.
  1207.      */
  1208.     abstract protected function _doExecute();
  1210.     /**
  1211.      * Cleanup Query resource when clone is called.
  1212.      *
  1213.      * @return void
  1214.      */
  1215.     public function __clone()
  1216.     {
  1217.         $this->parameters = new ArrayCollection();
  1219.         $this->_hints = [];
  1220.         $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  1221.     }
  1223.     /**
  1224.      * Generates a string of currently query to use for the cache second level cache.
  1225.      *
  1226.      * @return string
  1227.      */
  1228.     protected function getHash()
  1229.     {
  1230.         $query  = $this->getSQL();
  1231.         $hints  = $this->getHints();
  1232.         $params = array_map(function (Parameter $parameter) {
  1233.             $value = $parameter->getValue();
  1235.             // Small optimization
  1236.             // Does not invoke processParameterValue for scalar value
  1237.             if (is_scalar($value)) {
  1238.                 return $value;
  1239.             }
  1241.             return $this->processParameterValue($value);
  1242.         }, $this->parameters->getValues());
  1244.         ksort($hints);
  1246.         return sha1($query . '-' . serialize($params) . '-' . serialize($hints));
  1247.     }
  1249.     /** @param iterable<mixed> $subject */
  1250.     private function isCountable(iterable $subject): bool
  1251.     {
  1252.         return $subject instanceof Countable || is_array($subject);
  1253.     }
  1254. }