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

Open in your IDE?
  1. <?php
  2. /*
  3.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  4.  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  5.  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  6.  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  7.  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  8.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  9.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  10.  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  11.  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  12.  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  13.  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14.  *
  15.  * This software consists of voluntary contributions made by many individuals
  16.  * and is licensed under the MIT license. For more information, see
  17.  * <http://www.doctrine-project.org>.
  18.  */
  20. namespace Doctrine\ORM;
  22. use Doctrine\Common\Util\ClassUtils;
  23. use Doctrine\Common\Collections\Collection;
  24. use Doctrine\Common\Collections\ArrayCollection;
  25. use Doctrine\DBAL\Cache\QueryCacheProfile;
  26. use Doctrine\ORM\Mapping\MappingException as ORMMappingException;
  27. use Doctrine\ORM\Query\Parameter;
  28. use Doctrine\ORM\Cache\QueryCacheKey;
  29. use Doctrine\Persistence\Mapping\MappingException;
  31. /**
  32.  * Base contract for ORM queries. Base class for Query and NativeQuery.
  33.  *
  34.  * @link    www.doctrine-project.org
  35.  * @since   2.0
  36.  * @author  Benjamin Eberlei <kontakt@beberlei.de>
  37.  * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
  38.  * @author  Jonathan Wage <jonwage@gmail.com>
  39.  * @author  Roman Borschel <roman@code-factory.org>
  40.  * @author  Konsta Vesterinen <kvesteri@cc.hut.fi>
  41.  */
  42. abstract class AbstractQuery
  43. {
  44.     /* Hydration mode constants */
  46.     /**
  47.      * Hydrates an object graph. This is the default behavior.
  48.      */
  49.     const HYDRATE_OBJECT = 1;
  51.     /**
  52.      * Hydrates an array graph.
  53.      */
  54.     const HYDRATE_ARRAY = 2;
  56.     /**
  57.      * Hydrates a flat, rectangular result set with scalar values.
  58.      */
  59.     const HYDRATE_SCALAR = 3;
  61.     /**
  62.      * Hydrates a single scalar value.
  63.      */
  64.     const HYDRATE_SINGLE_SCALAR = 4;
  66.     /**
  67.      * Very simple object hydrator (optimized for performance).
  68.      */
  69.     const HYDRATE_SIMPLEOBJECT = 5;
  71.     /**
  72.      * The parameter map of this query.
  73.      *
  74.      * @var ArrayCollection|Parameter[]
  75.      */
  76.     protected $parameters;
  78.     /**
  79.      * The user-specified ResultSetMapping to use.
  80.      *
  81.      * @var \Doctrine\ORM\Query\ResultSetMapping
  82.      */
  83.     protected $_resultSetMapping;
  85.     /**
  86.      * The entity manager used by this query object.
  87.      *
  88.      * @var EntityManagerInterface
  89.      */
  90.     protected $_em;
  92.     /**
  93.      * The map of query hints.
  94.      *
  95.      * @var array
  96.      */
  97.     protected $_hints = [];
  99.     /**
  100.      * The hydration mode.
  101.      *
  102.      * @var string|int
  103.      */
  104.     protected $_hydrationMode = self::HYDRATE_OBJECT;
  106.     /**
  107.      * @var \Doctrine\DBAL\Cache\QueryCacheProfile
  108.      */
  109.     protected $_queryCacheProfile;
  111.     /**
  112.      * Whether or not expire the result cache.
  113.      *
  114.      * @var boolean
  115.      */
  116.     protected $_expireResultCache = false;
  118.     /**
  119.      * @var \Doctrine\DBAL\Cache\QueryCacheProfile
  120.      */
  121.     protected $_hydrationCacheProfile;
  123.     /**
  124.      * Whether to use second level cache, if available.
  125.      *
  126.      * @var boolean
  127.      */
  128.     protected $cacheable = false;
  130.     /**
  131.      * @var boolean
  132.      */
  133.     protected $hasCache = false;
  135.     /**
  136.      * Second level cache region name.
  137.      *
  138.      * @var string|null
  139.      */
  140.     protected $cacheRegion;
  142.     /**
  143.      * Second level query cache mode.
  144.      *
  145.      * @var integer|null
  146.      */
  147.     protected $cacheMode;
  149.     /**
  150.      * @var \Doctrine\ORM\Cache\Logging\CacheLogger|null
  151.      */
  152.     protected $cacheLogger;
  154.     /**
  155.      * @var integer
  156.      */
  157.     protected $lifetime = 0;
  159.     /**
  160.      * Initializes a new instance of a class derived from <tt>AbstractQuery</tt>.
  161.      *
  162.      * @param \Doctrine\ORM\EntityManagerInterface $em
  163.      */
  164.     public function __construct(EntityManagerInterface $em)
  165.     {
  166.         $this->_em          = $em;
  167.         $this->parameters   = new ArrayCollection();
  168.         $this->_hints       = $em->getConfiguration()->getDefaultQueryHints();
  169.         $this->hasCache     = $this->_em->getConfiguration()->isSecondLevelCacheEnabled();
  171.         if ($this->hasCache) {
  172.             $this->cacheLogger = $em->getConfiguration()
  173.                 ->getSecondLevelCacheConfiguration()
  174.                 ->getCacheLogger();
  175.         }
  176.     }
  178.     /**
  179.      * Enable/disable second level query (result) caching for this query.
  180.      *
  181.      * @param boolean $cacheable
  182.      *
  183.      * @return static This query instance.
  184.      */
  185.     public function setCacheable($cacheable)
  186.     {
  187.         $this->cacheable = (boolean) $cacheable;
  189.         return $this;
  190.     }
  192.     /**
  193.      * @return boolean TRUE if the query results are enable for second level cache, FALSE otherwise.
  194.      */
  195.     public function isCacheable()
  196.     {
  197.         return $this->cacheable;
  198.     }
  200.     /**
  201.      * @param string $cacheRegion
  202.      *
  203.      * @return static This query instance.
  204.      */
  205.     public function setCacheRegion($cacheRegion)
  206.     {
  207.         $this->cacheRegion = (string) $cacheRegion;
  209.         return $this;
  210.     }
  212.     /**
  213.     * Obtain the name of the second level query cache region in which query results will be stored
  214.     *
  215.     * @return string|null The cache region name; NULL indicates the default region.
  216.     */
  217.     public function getCacheRegion()
  218.     {
  219.         return $this->cacheRegion;
  220.     }
  222.     /**
  223.      * @return boolean TRUE if the query cache and second level cache are enabled, FALSE otherwise.
  224.      */
  225.     protected function isCacheEnabled()
  226.     {
  227.         return $this->cacheable && $this->hasCache;
  228.     }
  230.     /**
  231.      * @return integer
  232.      */
  233.     public function getLifetime()
  234.     {
  235.         return $this->lifetime;
  236.     }
  238.     /**
  239.      * Sets the life-time for this query into second level cache.
  240.      *
  241.      * @param integer $lifetime
  242.      *
  243.      * @return \Doctrine\ORM\AbstractQuery This query instance.
  244.      */
  245.     public function setLifetime($lifetime)
  246.     {
  247.         $this->lifetime = (integer) $lifetime;
  249.         return $this;
  250.     }
  252.     /**
  253.      * @return integer
  254.      */
  255.     public function getCacheMode()
  256.     {
  257.         return $this->cacheMode;
  258.     }
  260.     /**
  261.      * @param integer $cacheMode
  262.      *
  263.      * @return \Doctrine\ORM\AbstractQuery This query instance.
  264.      */
  265.     public function setCacheMode($cacheMode)
  266.     {
  267.         $this->cacheMode = (integer) $cacheMode;
  269.         return $this;
  270.     }
  272.     /**
  273.      * Gets the SQL query that corresponds to this query object.
  274.      * The returned SQL syntax depends on the connection driver that is used
  275.      * by this query object at the time of this method call.
  276.      *
  277.      * @return string SQL query
  278.      */
  279.     abstract public function getSQL();
  281.     /**
  282.      * Retrieves the associated EntityManager of this Query instance.
  283.      *
  284.      * @return \Doctrine\ORM\EntityManager
  285.      */
  286.     public function getEntityManager()
  287.     {
  288.         return $this->_em;
  289.     }
  291.     /**
  292.      * Frees the resources used by the query object.
  293.      *
  294.      * Resets Parameters, Parameter Types and Query Hints.
  295.      *
  296.      * @return void
  297.      */
  298.     public function free()
  299.     {
  300.         $this->parameters = new ArrayCollection();
  302.         $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  303.     }
  305.     /**
  306.      * Get all defined parameters.
  307.      *
  308.      * @return ArrayCollection The defined query parameters.
  309.      */
  310.     public function getParameters()
  311.     {
  312.         return $this->parameters;
  313.     }
  315.     /**
  316.      * Gets a query parameter.
  317.      *
  318.      * @param mixed $key The key (index or name) of the bound parameter.
  319.      *
  320.      * @return Query\Parameter|null The value of the bound parameter, or NULL if not available.
  321.      */
  322.     public function getParameter($key)
  323.     {
  324.         $filteredParameters = $this->parameters->filter(
  325.             function (Query\Parameter $parameter) use ($key) : bool {
  326.                 $parameterName = $parameter->getName();
  328.                 return $key === $parameterName || (string) $key === (string) $parameterName;
  329.             }
  330.         );
  332.         return ! $filteredParameters->isEmpty() ? $filteredParameters->first() : null;
  333.     }
  335.     /**
  336.      * Sets a collection of query parameters.
  337.      *
  338.      * @param ArrayCollection|mixed[] $parameters
  339.      *
  340.      * @return static This query instance.
  341.      */
  342.     public function setParameters($parameters)
  343.     {
  344.         // BC compatibility with 2.3-
  345.         if (is_array($parameters)) {
  346.             $parameterCollection = new ArrayCollection();
  348.             foreach ($parameters as $key => $value) {
  349.                 $parameterCollection->add(new Parameter($key, $value));
  350.             }
  352.             $parameters = $parameterCollection;
  353.         }
  355.         $this->parameters = $parameters;
  357.         return $this;
  358.     }
  360.     /**
  361.      * Sets a query parameter.
  362.      *
  363.      * @param string|int  $key   The parameter position or name.
  364.      * @param mixed       $value The parameter value.
  365.      * @param string|null $type  The parameter type. If specified, the given value will be run through
  366.      *                           the type conversion of this type. This is usually not needed for
  367.      *                           strings and numeric types.
  368.      *
  369.      * @return static This query instance.
  370.      */
  371.     public function setParameter($key, $value, $type = null)
  372.     {
  373.         $existingParameter = $this->getParameter($key);
  375.         if ($existingParameter !== null) {
  376.             $existingParameter->setValue($value, $type);
  378.             return $this;
  379.         }
  381.         $this->parameters->add(new Parameter($key, $value, $type));
  383.         return $this;
  384.     }
  386.     /**
  387.      * Processes an individual parameter value.
  388.      *
  389.      * @param mixed $value
  390.      *
  391.      * @return array|string
  392.      *
  393.      * @throws \Doctrine\ORM\ORMInvalidArgumentException
  394.      */
  395.     public function processParameterValue($value)
  396.     {
  397.         if (is_scalar($value)) {
  398.             return $value;
  399.         }
  401.         if ($value instanceof Collection) {
  402.             $value = $value->toArray();
  403.         }
  405.         if (is_array($value)) {
  406.             foreach ($value as $key => $paramValue) {
  407.                 $paramValue  = $this->processParameterValue($paramValue);
  408.                 $value[$key] = is_array($paramValue) ? reset($paramValue) : $paramValue;
  409.             }
  411.             return $value;
  412.         }
  414.         if ($value instanceof Mapping\ClassMetadata) {
  415.             return $value->name;
  416.         }
  418.         if (! is_object($value)) {
  419.             return $value;
  420.         }
  422.         try {
  423.             $value = $this->_em->getUnitOfWork()->getSingleIdentifierValue($value);
  425.             if ($value === null) {
  426.                 throw ORMInvalidArgumentException::invalidIdentifierBindingEntity();
  427.             }
  428.         } catch (MappingException | ORMMappingException $e) {
  429.             // Silence any mapping exceptions. These can occur if the object in
  430.             // question is not a mapped entity, in which case we just don't do
  431.             // any preparation on the value.
  432.         }
  434.         return $value;
  435.     }
  437.     /**
  438.      * Sets the ResultSetMapping that should be used for hydration.
  439.      *
  440.      * @param \Doctrine\ORM\Query\ResultSetMapping $rsm
  441.      *
  442.      * @return static This query instance.
  443.      */
  444.     public function setResultSetMapping(Query\ResultSetMapping $rsm)
  445.     {
  446.         $this->translateNamespaces($rsm);
  447.         $this->_resultSetMapping = $rsm;
  449.         return $this;
  450.     }
  452.     /**
  453.      * Gets the ResultSetMapping used for hydration.
  454.      *
  455.      * @return \Doctrine\ORM\Query\ResultSetMapping
  456.      */
  457.     protected function getResultSetMapping()
  458.     {
  459.         return $this->_resultSetMapping;
  460.     }
  462.     /**
  463.      * Allows to translate entity namespaces to full qualified names.
  464.      *
  465.      * @param Query\ResultSetMapping $rsm
  466.      *
  467.      * @return void
  468.      */
  469.     private function translateNamespaces(Query\ResultSetMapping $rsm)
  470.     {
  471.         $translate = function ($alias) {
  472.             return $this->_em->getClassMetadata($alias)->getName();
  473.         };
  475.         $rsm->aliasMap = array_map($translate, $rsm->aliasMap);
  476.         $rsm->declaringClasses = array_map($translate, $rsm->declaringClasses);
  477.     }
  479.     /**
  480.      * Set a cache profile for hydration caching.
  481.      *
  482.      * If no result cache driver is set in the QueryCacheProfile, the default
  483.      * result cache driver is used from the configuration.
  484.      *
  485.      * Important: Hydration caching does NOT register entities in the
  486.      * UnitOfWork when retrieved from the cache. Never use result cached
  487.      * entities for requests that also flush the EntityManager. If you want
  488.      * some form of caching with UnitOfWork registration you should use
  489.      * {@see AbstractQuery::setResultCacheProfile()}.
  490.      *
  491.      * @example
  492.      * $lifetime = 100;
  493.      * $resultKey = "abc";
  494.      * $query->setHydrationCacheProfile(new QueryCacheProfile());
  495.      * $query->setHydrationCacheProfile(new QueryCacheProfile($lifetime, $resultKey));
  496.      *
  497.      * @param \Doctrine\DBAL\Cache\QueryCacheProfile $profile
  498.      *
  499.      * @return static This query instance.
  500.      */
  501.     public function setHydrationCacheProfile(QueryCacheProfile $profile = null)
  502.     {
  503.         if ($profile !== null && ! $profile->getResultCacheDriver()) {
  504.             $resultCacheDriver = $this->_em->getConfiguration()->getHydrationCacheImpl();
  505.             $profile = $profile->setResultCacheDriver($resultCacheDriver);
  506.         }
  508.         $this->_hydrationCacheProfile = $profile;
  510.         return $this;
  511.     }
  513.     /**
  514.      * @return \Doctrine\DBAL\Cache\QueryCacheProfile
  515.      */
  516.     public function getHydrationCacheProfile()
  517.     {
  518.         return $this->_hydrationCacheProfile;
  519.     }
  521.     /**
  522.      * Set a cache profile for the result cache.
  523.      *
  524.      * If no result cache driver is set in the QueryCacheProfile, the default
  525.      * result cache driver is used from the configuration.
  526.      *
  527.      * @param \Doctrine\DBAL\Cache\QueryCacheProfile $profile
  528.      *
  529.      * @return static This query instance.
  530.      */
  531.     public function setResultCacheProfile(QueryCacheProfile $profile = null)
  532.     {
  533.         if ($profile !== null && ! $profile->getResultCacheDriver()) {
  534.             $resultCacheDriver = $this->_em->getConfiguration()->getResultCacheImpl();
  535.             $profile = $profile->setResultCacheDriver($resultCacheDriver);
  536.         }
  538.         $this->_queryCacheProfile = $profile;
  540.         return $this;
  541.     }
  543.     /**
  544.      * Defines a cache driver to be used for caching result sets and implicitly enables caching.
  545.      *
  546.      * @param \Doctrine\Common\Cache\Cache|null $resultCacheDriver Cache driver
  547.      *
  548.      * @return static This query instance.
  549.      *
  550.      * @throws ORMException
  551.      */
  552.     public function setResultCacheDriver($resultCacheDriver = null)
  553.     {
  554.         if ($resultCacheDriver !== null && ! ($resultCacheDriver instanceof \Doctrine\Common\Cache\Cache)) {
  555.             throw ORMException::invalidResultCacheDriver();
  556.         }
  558.         $this->_queryCacheProfile = $this->_queryCacheProfile
  559.             ? $this->_queryCacheProfile->setResultCacheDriver($resultCacheDriver)
  560.             : new QueryCacheProfile(0, null, $resultCacheDriver);
  562.         return $this;
  563.     }
  565.     /**
  566.      * Returns the cache driver used for caching result sets.
  567.      *
  568.      * @deprecated
  569.      *
  570.      * @return \Doctrine\Common\Cache\Cache Cache driver
  571.      */
  572.     public function getResultCacheDriver()
  573.     {
  574.         if ($this->_queryCacheProfile && $this->_queryCacheProfile->getResultCacheDriver()) {
  575.             return $this->_queryCacheProfile->getResultCacheDriver();
  576.         }
  578.         return $this->_em->getConfiguration()->getResultCacheImpl();
  579.     }
  581.     /**
  582.      * Set whether or not to cache the results of this query and if so, for
  583.      * how long and which ID to use for the cache entry.
  584.      *
  585.      * @deprecated 2.7 Use {@see enableResultCache} and {@see disableResultCache} instead.
  586.      *
  587.      * @param bool   $useCache
  588.      * @param int    $lifetime
  589.      * @param string $resultCacheId
  590.      *
  591.      * @return static This query instance.
  592.      */
  593.     public function useResultCache($useCache, $lifetime = null, $resultCacheId = null)
  594.     {
  595.         return $useCache
  596.             ? $this->enableResultCache($lifetime, $resultCacheId)
  597.             : $this->disableResultCache();
  598.     }
  600.     /**
  601.      * Enables caching of the results of this query, for given or default amount of seconds
  602.      * and optionally specifies which ID to use for the cache entry.
  603.      *
  604.      * @param int|null    $lifetime      How long the cache entry is valid, in seconds.
  605.      * @param string|null $resultCacheId ID to use for the cache entry.
  606.      *
  607.      * @return static This query instance.
  608.      */
  609.     public function enableResultCache(?int $lifetime = null, ?string $resultCacheId = null) : self
  610.     {
  611.         $this->setResultCacheLifetime($lifetime);
  612.         $this->setResultCacheId($resultCacheId);
  614.         return $this;
  615.     }
  617.     /**
  618.      * Disables caching of the results of this query.
  619.      *
  620.      * @return static This query instance.
  621.      */
  622.     public function disableResultCache() : self
  623.     {
  624.         $this->_queryCacheProfile = null;
  626.         return $this;
  627.     }
  629.     /**
  630.      * Defines how long the result cache will be active before expire.
  631.      *
  632.      * @param integer $lifetime How long the cache entry is valid.
  633.      *
  634.      * @return static This query instance.
  635.      */
  636.     public function setResultCacheLifetime($lifetime)
  637.     {
  638.         $lifetime = ($lifetime !== null) ? (int) $lifetime : 0;
  640.         $this->_queryCacheProfile = $this->_queryCacheProfile
  641.             ? $this->_queryCacheProfile->setLifetime($lifetime)
  642.             : new QueryCacheProfile($lifetime, null, $this->_em->getConfiguration()->getResultCacheImpl());
  644.         return $this;
  645.     }
  647.     /**
  648.      * Retrieves the lifetime of resultset cache.
  649.      *
  650.      * @deprecated
  651.      *
  652.      * @return integer
  653.      */
  654.     public function getResultCacheLifetime()
  655.     {
  656.         return $this->_queryCacheProfile ? $this->_queryCacheProfile->getLifetime() : 0;
  657.     }
  659.     /**
  660.      * Defines if the result cache is active or not.
  661.      *
  662.      * @param boolean $expire Whether or not to force resultset cache expiration.
  663.      *
  664.      * @return static This query instance.
  665.      */
  666.     public function expireResultCache($expire = true)
  667.     {
  668.         $this->_expireResultCache = $expire;
  670.         return $this;
  671.     }
  673.     /**
  674.      * Retrieves if the resultset cache is active or not.
  675.      *
  676.      * @return boolean
  677.      */
  678.     public function getExpireResultCache()
  679.     {
  680.         return $this->_expireResultCache;
  681.     }
  683.     /**
  684.      * @return QueryCacheProfile
  685.      */
  686.     public function getQueryCacheProfile()
  687.     {
  688.         return $this->_queryCacheProfile;
  689.     }
  691.     /**
  692.      * Change the default fetch mode of an association for this query.
  693.      *
  694.      * $fetchMode can be one of ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY
  695.      *
  696.      * @param string $class
  697.      * @param string $assocName
  698.      * @param int    $fetchMode
  699.      *
  700.      * @return static This query instance.
  701.      */
  702.     public function setFetchMode($class, $assocName, $fetchMode)
  703.     {
  704.         if ($fetchMode !== Mapping\ClassMetadata::FETCH_EAGER) {
  705.             $fetchMode = Mapping\ClassMetadata::FETCH_LAZY;
  706.         }
  708.         $this->_hints['fetchMode'][$class][$assocName] = $fetchMode;
  710.         return $this;
  711.     }
  713.     /**
  714.      * Defines the processing mode to be used during hydration / result set transformation.
  715.      *
  716.      * @param string|int $hydrationMode Doctrine processing mode to be used during hydration process.
  717.      *                                  One of the Query::HYDRATE_* constants.
  718.      *
  719.      * @return static This query instance.
  720.      */
  721.     public function setHydrationMode($hydrationMode)
  722.     {
  723.         $this->_hydrationMode = $hydrationMode;
  725.         return $this;
  726.     }
  728.     /**
  729.      * Gets the hydration mode currently used by the query.
  730.      *
  731.      * @return string|int
  732.      */
  733.     public function getHydrationMode()
  734.     {
  735.         return $this->_hydrationMode;
  736.     }
  738.     /**
  739.      * Gets the list of results for the query.
  740.      *
  741.      * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).
  742.      *
  743.      * @param string|int $hydrationMode
  744.      *
  745.      * @return mixed
  746.      */
  747.     public function getResult($hydrationMode = self::HYDRATE_OBJECT)
  748.     {
  749.         return $this->execute(null, $hydrationMode);
  750.     }
  752.     /**
  753.      * Gets the array of results for the query.
  754.      *
  755.      * Alias for execute(null, HYDRATE_ARRAY).
  756.      *
  757.      * @return array
  758.      */
  759.     public function getArrayResult()
  760.     {
  761.         return $this->execute(null, self::HYDRATE_ARRAY);
  762.     }
  764.     /**
  765.      * Gets the scalar results for the query.
  766.      *
  767.      * Alias for execute(null, HYDRATE_SCALAR).
  768.      *
  769.      * @return array
  770.      */
  771.     public function getScalarResult()
  772.     {
  773.         return $this->execute(null, self::HYDRATE_SCALAR);
  774.     }
  776.     /**
  777.      * Get exactly one result or null.
  778.      *
  779.      * @param string|int $hydrationMode
  780.      *
  781.      * @return mixed
  782.      *
  783.      * @throws NonUniqueResultException
  784.      */
  785.     public function getOneOrNullResult($hydrationMode = null)
  786.     {
  787.         try {
  788.             $result = $this->execute(null, $hydrationMode);
  789.         } catch (NoResultException $e) {
  790.             return null;
  791.         }
  794.         if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  795.             return null;
  796.         }
  798.         if ( ! is_array($result)) {
  799.             return $result;
  800.         }
  802.         if (count($result) > 1) {
  803.             throw new NonUniqueResultException;
  804.         }
  806.         return array_shift($result);
  807.     }
  809.     /**
  810.      * Gets the single result of the query.
  811.      *
  812.      * Enforces the presence as well as the uniqueness of the result.
  813.      *
  814.      * If the result is not unique, a NonUniqueResultException is thrown.
  815.      * If there is no result, a NoResultException is thrown.
  816.      *
  817.      * @param string|int $hydrationMode
  818.      *
  819.      * @return mixed
  820.      *
  821.      * @throws NonUniqueResultException If the query result is not unique.
  822.      * @throws NoResultException        If the query returned no result and hydration mode is not HYDRATE_SINGLE_SCALAR.
  823.      */
  824.     public function getSingleResult($hydrationMode = null)
  825.     {
  826.         $result = $this->execute(null, $hydrationMode);
  828.         if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {
  829.             throw new NoResultException;
  830.         }
  832.         if ( ! is_array($result)) {
  833.             return $result;
  834.         }
  836.         if (count($result) > 1) {
  837.             throw new NonUniqueResultException;
  838.         }
  840.         return array_shift($result);
  841.     }
  843.     /**
  844.      * Gets the single scalar result of the query.
  845.      *
  846.      * Alias for getSingleResult(HYDRATE_SINGLE_SCALAR).
  847.      *
  848.      * @return mixed The scalar result.
  849.      *
  850.      * @throws NoResultException        If the query returned no result.
  851.      * @throws NonUniqueResultException If the query result is not unique.
  852.      */
  853.     public function getSingleScalarResult()
  854.     {
  855.         return $this->getSingleResult(self::HYDRATE_SINGLE_SCALAR);
  856.     }
  858.     /**
  859.      * Sets a query hint. If the hint name is not recognized, it is silently ignored.
  860.      *
  861.      * @param string $name  The name of the hint.
  862.      * @param mixed  $value The value of the hint.
  863.      *
  864.      * @return static This query instance.
  865.      */
  866.     public function setHint($name, $value)
  867.     {
  868.         $this->_hints[$name] = $value;
  870.         return $this;
  871.     }
  873.     /**
  874.      * Gets the value of a query hint. If the hint name is not recognized, FALSE is returned.
  875.      *
  876.      * @param string $name The name of the hint.
  877.      *
  878.      * @return mixed The value of the hint or FALSE, if the hint name is not recognized.
  879.      */
  880.     public function getHint($name)
  881.     {
  882.         return isset($this->_hints[$name]) ? $this->_hints[$name] : false;
  883.     }
  885.     /**
  886.      * Check if the query has a hint
  887.      *
  888.      * @param string $name The name of the hint
  889.      *
  890.      * @return bool False if the query does not have any hint
  891.      */
  892.     public function hasHint($name)
  893.     {
  894.         return isset($this->_hints[$name]);
  895.     }
  897.     /**
  898.      * Return the key value map of query hints that are currently set.
  899.      *
  900.      * @return array
  901.      */
  902.     public function getHints()
  903.     {
  904.         return $this->_hints;
  905.     }
  907.     /**
  908.      * Executes the query and returns an IterableResult that can be used to incrementally
  909.      * iterate over the result.
  910.      *
  911.      * @param ArrayCollection|array|null $parameters    The query parameters.
  912.      * @param string|int|null            $hydrationMode The hydration mode to use.
  913.      *
  914.      * @return \Doctrine\ORM\Internal\Hydration\IterableResult
  915.      */
  916.     public function iterate($parameters = null, $hydrationMode = null)
  917.     {
  918.         if ($hydrationMode !== null) {
  919.             $this->setHydrationMode($hydrationMode);
  920.         }
  922.         if ( ! empty($parameters)) {
  923.             $this->setParameters($parameters);
  924.         }
  926.         $rsm  = $this->getResultSetMapping();
  927.         $stmt = $this->_doExecute();
  929.         return $this->_em->newHydrator($this->_hydrationMode)->iterate($stmt, $rsm, $this->_hints);
  930.     }
  932.     /**
  933.      * Executes the query.
  934.      *
  935.      * @param ArrayCollection|array|null $parameters Query parameters.
  936.      * @param string|int|null            $hydrationMode Processing mode to be used during the hydration process.
  937.      *
  938.      * @return mixed
  939.      */
  940.     public function execute($parameters = null, $hydrationMode = null)
  941.     {
  942.         if ($this->cacheable && $this->isCacheEnabled()) {
  943.             return $this->executeUsingQueryCache($parameters, $hydrationMode);
  944.         }
  946.         return $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  947.     }
  949.     /**
  950.      * Execute query ignoring second level cache.
  951.      *
  952.      * @param ArrayCollection|array|null $parameters
  953.      * @param string|int|null            $hydrationMode
  954.      *
  955.      * @return mixed
  956.      */
  957.     private function executeIgnoreQueryCache($parameters = null, $hydrationMode = null)
  958.     {
  959.         if ($hydrationMode !== null) {
  960.             $this->setHydrationMode($hydrationMode);
  961.         }
  963.         if ( ! empty($parameters)) {
  964.             $this->setParameters($parameters);
  965.         }
  967.         $setCacheEntry = function() {};
  969.         if ($this->_hydrationCacheProfile !== null) {
  970.             list($cacheKey, $realCacheKey) = $this->getHydrationCacheId();
  972.             $queryCacheProfile = $this->getHydrationCacheProfile();
  973.             $cache             = $queryCacheProfile->getResultCacheDriver();
  974.             $result            = $cache->fetch($cacheKey);
  976.             if (isset($result[$realCacheKey])) {
  977.                 return $result[$realCacheKey];
  978.             }
  980.             if ( ! $result) {
  981.                 $result = [];
  982.             }
  984.             $setCacheEntry = function($data) use ($cache, $result, $cacheKey, $realCacheKey, $queryCacheProfile) {
  985.                 $result[$realCacheKey] = $data;
  987.                 $cache->save($cacheKey, $result, $queryCacheProfile->getLifetime());
  988.             };
  989.         }
  991.         $stmt = $this->_doExecute();
  993.         if (is_numeric($stmt)) {
  994.             $setCacheEntry($stmt);
  996.             return $stmt;
  997.         }
  999.         $rsm  = $this->getResultSetMapping();
  1000.         $data = $this->_em->newHydrator($this->_hydrationMode)->hydrateAll($stmt, $rsm, $this->_hints);
  1002.         $setCacheEntry($data);
  1004.         return $data;
  1005.     }
  1007.     /**
  1008.      * Load from second level cache or executes the query and put into cache.
  1009.      *
  1010.      * @param ArrayCollection|array|null $parameters
  1011.      * @param string|int|null            $hydrationMode
  1012.      *
  1013.      * @return mixed
  1014.      */
  1015.     private function executeUsingQueryCache($parameters = null, $hydrationMode = null)
  1016.     {
  1017.         $rsm        = $this->getResultSetMapping();
  1018.         $queryCache = $this->_em->getCache()->getQueryCache($this->cacheRegion);
  1019.         $queryKey   = new QueryCacheKey(
  1020.             $this->getHash(),
  1021.             $this->lifetime,
  1022.             $this->cacheMode ?: Cache::MODE_NORMAL,
  1023.             $this->getTimestampKey()
  1024.         );
  1026.         $result     = $queryCache->get($queryKey, $rsm, $this->_hints);
  1028.         if ($result !== null) {
  1029.             if ($this->cacheLogger) {
  1030.                 $this->cacheLogger->queryCacheHit($queryCache->getRegion()->getName(), $queryKey);
  1031.             }
  1033.             return $result;
  1034.         }
  1036.         $result = $this->executeIgnoreQueryCache($parameters, $hydrationMode);
  1037.         $cached = $queryCache->put($queryKey, $rsm, $result, $this->_hints);
  1039.         if ($this->cacheLogger) {
  1040.             $this->cacheLogger->queryCacheMiss($queryCache->getRegion()->getName(), $queryKey);
  1042.             if ($cached) {
  1043.                 $this->cacheLogger->queryCachePut($queryCache->getRegion()->getName(), $queryKey);
  1044.             }
  1045.         }
  1047.         return $result;
  1048.     }
  1050.     /**
  1051.      * @return \Doctrine\ORM\Cache\TimestampCacheKey|null
  1052.      */
  1053.     private function getTimestampKey()
  1054.     {
  1055.         $entityName = reset($this->_resultSetMapping->aliasMap);
  1057.         if (empty($entityName)) {
  1058.             return null;
  1059.         }
  1061.         $metadata = $this->_em->getClassMetadata($entityName);
  1063.         return new Cache\TimestampCacheKey($metadata->rootEntityName);
  1064.     }
  1066.     /**
  1067.      * Get the result cache id to use to store the result set cache entry.
  1068.      * Will return the configured id if it exists otherwise a hash will be
  1069.      * automatically generated for you.
  1070.      *
  1071.      * @return array ($key, $hash)
  1072.      */
  1073.     protected function getHydrationCacheId()
  1074.     {
  1075.         $parameters = [];
  1077.         foreach ($this->getParameters() as $parameter) {
  1078.             $parameters[$parameter->getName()] = $this->processParameterValue($parameter->getValue());
  1079.         }
  1081.         $sql                    = $this->getSQL();
  1082.         $queryCacheProfile      = $this->getHydrationCacheProfile();
  1083.         $hints                  = $this->getHints();
  1084.         $hints['hydrationMode'] = $this->getHydrationMode();
  1086.         ksort($hints);
  1088.         return $queryCacheProfile->generateCacheKeys($sql, $parameters, $hints);
  1089.     }
  1091.     /**
  1092.      * Set the result cache id to use to store the result set cache entry.
  1093.      * If this is not explicitly set by the developer then a hash is automatically
  1094.      * generated for you.
  1095.      *
  1096.      * @param string $id
  1097.      *
  1098.      * @return static This query instance.
  1099.      */
  1100.     public function setResultCacheId($id)
  1101.     {
  1102.         $this->_queryCacheProfile = $this->_queryCacheProfile
  1103.             ? $this->_queryCacheProfile->setCacheKey($id)
  1104.             : new QueryCacheProfile(0, $id, $this->_em->getConfiguration()->getResultCacheImpl());
  1106.         return $this;
  1107.     }
  1109.     /**
  1110.      * Get the result cache id to use to store the result set cache entry if set.
  1111.      *
  1112.      * @deprecated
  1113.      *
  1114.      * @return string
  1115.      */
  1116.     public function getResultCacheId()
  1117.     {
  1118.         return $this->_queryCacheProfile ? $this->_queryCacheProfile->getCacheKey() : null;
  1119.     }
  1121.     /**
  1122.      * Executes the query and returns a the resulting Statement object.
  1123.      *
  1124.      * @return \Doctrine\DBAL\Driver\Statement The executed database statement that holds the results.
  1125.      */
  1126.     abstract protected function _doExecute();
  1128.     /**
  1129.      * Cleanup Query resource when clone is called.
  1130.      *
  1131.      * @return void
  1132.      */
  1133.     public function __clone()
  1134.     {
  1135.         $this->parameters = new ArrayCollection();
  1137.         $this->_hints = [];
  1138.         $this->_hints = $this->_em->getConfiguration()->getDefaultQueryHints();
  1139.     }
  1141.     /**
  1142.      * Generates a string of currently query to use for the cache second level cache.
  1143.      *
  1144.      * @return string
  1145.      */
  1146.     protected function getHash()
  1147.     {
  1148.         $query  = $this->getSQL();
  1149.         $hints  = $this->getHints();
  1150.         $params = array_map(function(Parameter $parameter) {
  1151.             // Small optimization
  1152.             // Does not invoke processParameterValue for scalar values
  1153.             if (is_scalar($value = $parameter->getValue())) {
  1154.                 return $value;
  1155.             }
  1157.             return $this->processParameterValue($value);
  1158.         }, $this->parameters->getValues());
  1160.         ksort($hints);
  1162.         return sha1($query . '-' . serialize($params) . '-' . serialize($hints));
  1163.     }
  1164. }