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.
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>.
20 namespace Doctrine\ORM
;
22 use Doctrine\Common\Collections\ArrayCollection
;
23 use Doctrine\Common\Collections\Criteria
;
25 use Doctrine\ORM\Query\Expr
;
26 use Doctrine\ORM\Query\QueryExpressionVisitor
;
29 * This class is responsible for building DQL query strings via an object oriented
33 * @author Guilherme Blanco <guilhermeblanco@hotmail.com>
34 * @author Jonathan Wage <jonwage@gmail.com>
35 * @author Roman Borschel <roman@code-factory.org>
39 /* The query types. */
44 /* The builder states. */
45 const STATE_DIRTY
= 0;
46 const STATE_CLEAN
= 1;
49 * The EntityManager used by this QueryBuilder.
51 * @var EntityManagerInterface
56 * The array of DQL parts collected.
60 private $_dqlParts = array(
73 * The type of query this is. Can be select, update or delete.
77 private $_type = self
::SELECT
;
80 * The state of the query object. Can be dirty or clean.
84 private $_state = self
::STATE_CLEAN
;
87 * The complete DQL string for this query.
94 * The query parameters.
96 * @var \Doctrine\Common\Collections\ArrayCollection
101 * The index of the first result to retrieve.
105 private $_firstResult = null;
108 * The maximum number of results to retrieve.
112 private $_maxResults = null;
115 * Keeps root entity alias names for join entities.
119 private $joinRootAliases = array();
122 * Whether to use second level cache, if available.
126 protected $cacheable = false;
129 * Second level cache region name.
133 protected $cacheRegion;
136 * Second level query cache mode.
140 protected $cacheMode;
145 protected $lifetime = 0;
148 * Initializes a new <tt>QueryBuilder</tt> that uses the given <tt>EntityManager</tt>.
150 * @param EntityManagerInterface $em The EntityManager to use.
152 public function __construct(EntityManagerInterface
$em)
155 $this->parameters
= new ArrayCollection();
159 * Gets an ExpressionBuilder used for object-oriented construction of query expressions.
160 * This producer method is intended for convenient inline usage. Example:
163 * $qb = $em->createQueryBuilder();
166 * ->from('User', 'u')
167 * ->where($qb->expr()->eq('u.id', 1));
170 * For more complex expression construction, consider storing the expression
171 * builder object in a local variable.
175 public function expr()
177 return $this->_em
->getExpressionBuilder();
182 * Enable/disable second level query (result) caching for this query.
184 * @param boolean $cacheable
186 * @return \Doctrine\ORM\AbstractQuery This query instance.
188 public function setCacheable($cacheable)
190 $this->cacheable
= (boolean
) $cacheable;
196 * @return boolean TRUE if the query results are enable for second level cache, FALSE otherwise.
198 public function isCacheable()
200 return $this->cacheable
;
204 * @param string $cacheRegion
206 * @return \Doctrine\ORM\AbstractQuery This query instance.
208 public function setCacheRegion($cacheRegion)
210 $this->cacheRegion
= (string) $cacheRegion;
216 * Obtain the name of the second level query cache region in which query results will be stored
218 * @return The cache region name; NULL indicates the default region.
220 public function getCacheRegion()
222 return $this->cacheRegion
;
228 public function getLifetime()
230 return $this->lifetime
;
234 * Sets the life-time for this query into second level cache.
236 * @param integer $lifetime
237 * @return \Doctrine\ORM\AbstractQuery This query instance.
239 public function setLifetime($lifetime)
241 $this->lifetime
= (integer) $lifetime;
249 public function getCacheMode()
251 return $this->cacheMode
;
255 * @param integer $cacheMode
256 * @return \Doctrine\ORM\AbstractQuery This query instance.
258 public function setCacheMode($cacheMode)
260 $this->cacheMode
= (integer) $cacheMode;
266 * Gets the type of the currently built query.
270 public function getType()
276 * Gets the associated EntityManager for this query builder.
278 * @return EntityManager
280 public function getEntityManager()
286 * Gets the state of this query builder instance.
288 * @return integer Either QueryBuilder::STATE_DIRTY or QueryBuilder::STATE_CLEAN.
290 public function getState()
292 return $this->_state
;
296 * Gets the complete DQL string formed by the current specifications of this QueryBuilder.
299 * $qb = $em->createQueryBuilder()
301 * ->from('User', 'u');
302 * echo $qb->getDql(); // SELECT u FROM User u
305 * @return string The DQL query string.
307 public function getDQL()
309 if ($this->_dql
!== null && $this->_state
=== self
::STATE_CLEAN
) {
313 switch ($this->_type
) {
315 $dql = $this->_getDQLForDelete();
319 $dql = $this->_getDQLForUpdate();
324 $dql = $this->_getDQLForSelect();
328 $this->_state
= self
::STATE_CLEAN
;
335 * Constructs a Query instance from the current specifications of the builder.
338 * $qb = $em->createQueryBuilder()
340 * ->from('User', 'u');
341 * $q = $qb->getQuery();
342 * $results = $q->execute();
347 public function getQuery()
349 $parameters = clone $this->parameters
;
350 $query = $this->_em
->createQuery($this->getDQL())
351 ->setParameters($parameters)
352 ->setFirstResult($this->_firstResult
)
353 ->setMaxResults($this->_maxResults
);
355 if ($this->lifetime
) {
356 $query->setLifetime($this->lifetime
);
359 if ($this->cacheMode
) {
360 $query->setCacheMode($this->cacheMode
);
363 if ($this->cacheable
) {
364 $query->setCacheable($this->cacheable
);
367 if ($this->cacheRegion
) {
368 $query->setCacheRegion($this->cacheRegion
);
375 * Finds the root entity alias of the joined entity.
377 * @param string $alias The alias of the new join entity
378 * @param string $parentAlias The parent entity alias of the join relationship
382 private function findRootAlias($alias, $parentAlias)
386 if (in_array($parentAlias, $this->getRootAliases())) {
387 $rootAlias = $parentAlias;
388 } elseif (isset($this->joinRootAliases
[$parentAlias])) {
389 $rootAlias = $this->joinRootAliases
[$parentAlias];
391 // Should never happen with correct joining order. Might be
392 // thoughtful to throw exception instead.
393 $rootAlias = $this->getRootAlias();
396 $this->joinRootAliases
[$alias] = $rootAlias;
402 * Gets the FIRST root alias of the query. This is the first entity alias involved
403 * in the construction of the query.
406 * $qb = $em->createQueryBuilder()
408 * ->from('User', 'u');
410 * echo $qb->getRootAlias(); // u
413 * @deprecated Please use $qb->getRootAliases() instead.
414 * @throws RuntimeException
418 public function getRootAlias()
420 $aliases = $this->getRootAliases();
422 if ( ! isset($aliases[0])) {
423 throw new \
RuntimeException('No alias was set before invoking getRootAlias().');
430 * Gets the root aliases of the query. This is the entity aliases involved
431 * in the construction of the query.
434 * $qb = $em->createQueryBuilder()
436 * ->from('User', 'u');
438 * $qb->getRootAliases(); // array('u')
443 public function getRootAliases()
447 foreach ($this->_dqlParts
['from'] as &$fromClause) {
448 if (is_string($fromClause)) {
449 $spacePos = strrpos($fromClause, ' ');
450 $from = substr($fromClause, 0, $spacePos);
451 $alias = substr($fromClause, $spacePos +
1);
453 $fromClause = new Query\Expr\
From($from, $alias);
456 $aliases[] = $fromClause->getAlias();
463 * Gets all the aliases that have been used in the query.
464 * Including all select root aliases and join aliases
467 * $qb = $em->createQueryBuilder()
469 * ->from('User', 'u')
470 * ->join('u.articles','a';
472 * $qb->getAllAliases(); // array('u','a')
476 public function getAllAliases() {
477 return array_merge($this->getRootAliases(),array_keys($this->joinRootAliases
));
481 * Gets the root entities of the query. This is the entity aliases involved
482 * in the construction of the query.
485 * $qb = $em->createQueryBuilder()
487 * ->from('User', 'u');
489 * $qb->getRootEntities(); // array('User')
494 public function getRootEntities()
498 foreach ($this->_dqlParts
['from'] as &$fromClause) {
499 if (is_string($fromClause)) {
500 $spacePos = strrpos($fromClause, ' ');
501 $from = substr($fromClause, 0, $spacePos);
502 $alias = substr($fromClause, $spacePos +
1);
504 $fromClause = new Query\Expr\
From($from, $alias);
507 $entities[] = $fromClause->getFrom();
514 * Sets a query parameter for the query being constructed.
517 * $qb = $em->createQueryBuilder()
519 * ->from('User', 'u')
520 * ->where('u.id = :user_id')
521 * ->setParameter('user_id', 1);
524 * @param string|integer $key The parameter position or name.
525 * @param mixed $value The parameter value.
526 * @param string|null $type PDO::PARAM_* or \Doctrine\DBAL\Types\Type::* constant
528 * @return QueryBuilder This QueryBuilder instance.
530 public function setParameter($key, $value, $type = null)
532 $existingParameter = $this->getParameter($key);
534 if ($existingParameter !== null) {
535 $existingParameter->setValue($value, $type);
540 $this->parameters
->add(new Query\
Parameter($key, $value, $type));
546 * Sets a collection of query parameters for the query being constructed.
549 * $qb = $em->createQueryBuilder()
551 * ->from('User', 'u')
552 * ->where('u.id = :user_id1 OR u.id = :user_id2')
553 * ->setParameters(new ArrayCollection(array(
554 * new Parameter('user_id1', 1),
555 * new Parameter('user_id2', 2)
559 * @param \Doctrine\Common\Collections\ArrayCollection|array $parameters The query parameters to set.
561 * @return QueryBuilder This QueryBuilder instance.
563 public function setParameters($parameters)
565 // BC compatibility with 2.3-
566 if (is_array($parameters)) {
567 $parameterCollection = new ArrayCollection();
569 foreach ($parameters as $key => $value) {
570 $parameter = new Query\
Parameter($key, $value);
572 $parameterCollection->add($parameter);
575 $parameters = $parameterCollection;
578 $this->parameters
= $parameters;
584 * Gets all defined query parameters for the query being constructed.
586 * @return \Doctrine\Common\Collections\ArrayCollection The currently defined query parameters.
588 public function getParameters()
590 return $this->parameters
;
594 * Gets a (previously set) query parameter of the query being constructed.
596 * @param mixed $key The key (index or name) of the bound parameter.
598 * @return Query\Parameter|null The value of the bound parameter.
600 public function getParameter($key)
602 $filteredParameters = $this->parameters
->filter(
603 function (Query\Parameter
$parameter) use ($key) {
604 $parameterName = $parameter->getName();
606 return $key === $parameterName ||
(string) $key === (string) $parameterName;
610 return ! $filteredParameters->isEmpty() ?
$filteredParameters->first() : null;
614 * Sets the position of the first result to retrieve (the "offset").
616 * @param integer $firstResult The first result to return.
618 * @return QueryBuilder This QueryBuilder instance.
620 public function setFirstResult($firstResult)
622 $this->_firstResult
= $firstResult;
628 * Gets the position of the first result the query object was set to retrieve (the "offset").
629 * Returns NULL if {@link setFirstResult} was not applied to this QueryBuilder.
631 * @return integer The position of the first result.
633 public function getFirstResult()
635 return $this->_firstResult
;
639 * Sets the maximum number of results to retrieve (the "limit").
641 * @param integer $maxResults The maximum number of results to retrieve.
643 * @return QueryBuilder This QueryBuilder instance.
645 public function setMaxResults($maxResults)
647 $this->_maxResults
= $maxResults;
653 * Gets the maximum number of results the query object was set to retrieve (the "limit").
654 * Returns NULL if {@link setMaxResults} was not applied to this query builder.
656 * @return integer Maximum number of results.
658 public function getMaxResults()
660 return $this->_maxResults
;
664 * Either appends to or replaces a single, generic query part.
666 * The available parts are: 'select', 'from', 'join', 'set', 'where',
667 * 'groupBy', 'having' and 'orderBy'.
669 * @param string $dqlPartName
670 * @param Expr\Base $dqlPart
671 * @param bool $append
673 * @return QueryBuilder This QueryBuilder instance.
675 public function add($dqlPartName, $dqlPart, $append = false)
677 if ($append && ($dqlPartName === "where" ||
$dqlPartName === "having")) {
678 throw new \
InvalidArgumentException(
679 "Using \$append = true does not have an effect with 'where' or 'having' ".
680 "parts. See QueryBuilder#andWhere() for an example for correct usage."
684 $isMultiple = is_array($this->_dqlParts
[$dqlPartName])
685 && !($dqlPartName == 'join' && !$append);
687 // Allow adding any part retrieved from self::getDQLParts().
688 if (is_array($dqlPart) && $dqlPartName != 'join') {
689 $dqlPart = reset($dqlPart);
692 // This is introduced for backwards compatibility reasons.
693 // TODO: Remove for 3.0
694 if ($dqlPartName == 'join') {
695 $newDqlPart = array();
697 foreach ($dqlPart as $k => $v) {
698 $k = is_numeric($k) ?
$this->getRootAlias() : $k;
700 $newDqlPart[$k] = $v;
703 $dqlPart = $newDqlPart;
706 if ($append && $isMultiple) {
707 if (is_array($dqlPart)) {
708 $key = key($dqlPart);
710 $this->_dqlParts
[$dqlPartName][$key][] = $dqlPart[$key];
712 $this->_dqlParts
[$dqlPartName][] = $dqlPart;
715 $this->_dqlParts
[$dqlPartName] = ($isMultiple) ?
array($dqlPart) : $dqlPart;
718 $this->_state
= self
::STATE_DIRTY
;
724 * Specifies an item that is to be returned in the query result.
725 * Replaces any previously specified selections, if any.
728 * $qb = $em->createQueryBuilder()
730 * ->from('User', 'u')
731 * ->leftJoin('u.Phonenumbers', 'p');
734 * @param mixed $select The selection expressions.
736 * @return QueryBuilder This QueryBuilder instance.
738 public function select($select = null)
740 $this->_type
= self
::SELECT
;
742 if (empty($select)) {
746 $selects = is_array($select) ?
$select : func_get_args();
748 return $this->add('select', new Expr\
Select($selects), false);
752 * Adds a DISTINCT flag to this query.
755 * $qb = $em->createQueryBuilder()
758 * ->from('User', 'u');
763 * @return QueryBuilder
765 public function distinct($flag = true)
767 $this->_dqlParts
['distinct'] = (bool) $flag;
773 * Adds an item that is to be returned in the query result.
776 * $qb = $em->createQueryBuilder()
779 * ->from('User', 'u')
780 * ->leftJoin('u.Phonenumbers', 'p');
783 * @param mixed $select The selection expression.
785 * @return QueryBuilder This QueryBuilder instance.
787 public function addSelect($select = null)
789 $this->_type
= self
::SELECT
;
791 if (empty($select)) {
795 $selects = is_array($select) ?
$select : func_get_args();
797 return $this->add('select', new Expr\
Select($selects), true);
801 * Turns the query being built into a bulk delete query that ranges over
802 * a certain entity type.
805 * $qb = $em->createQueryBuilder()
806 * ->delete('User', 'u')
807 * ->where('u.id = :user_id')
808 * ->setParameter('user_id', 1);
811 * @param string $delete The class/type whose instances are subject to the deletion.
812 * @param string $alias The class/type alias used in the constructed query.
814 * @return QueryBuilder This QueryBuilder instance.
816 public function delete($delete = null, $alias = null)
818 $this->_type
= self
::DELETE
;
824 return $this->add('from', new Expr\
From($delete, $alias));
828 * Turns the query being built into a bulk update query that ranges over
829 * a certain entity type.
832 * $qb = $em->createQueryBuilder()
833 * ->update('User', 'u')
834 * ->set('u.password', md5('password'))
835 * ->where('u.id = ?');
838 * @param string $update The class/type whose instances are subject to the update.
839 * @param string $alias The class/type alias used in the constructed query.
841 * @return QueryBuilder This QueryBuilder instance.
843 public function update($update = null, $alias = null)
845 $this->_type
= self
::UPDATE
;
851 return $this->add('from', new Expr\
From($update, $alias));
855 * Creates and adds a query root corresponding to the entity identified by the given alias,
856 * forming a cartesian product with any existing query roots.
859 * $qb = $em->createQueryBuilder()
861 * ->from('User', 'u');
864 * @param string $from The class name.
865 * @param string $alias The alias of the class.
866 * @param string $indexBy The index for the from.
868 * @return QueryBuilder This QueryBuilder instance.
870 public function from($from, $alias, $indexBy = null)
872 return $this->add('from', new Expr\
From($from, $alias, $indexBy), true);
876 * Updates a query root corresponding to an entity setting its index by. This method is intended to be used with
877 * EntityRepository->createQueryBuilder(), which creates the initial FROM clause and do not allow you to update it
878 * setting an index by.
881 * $qb = $userRepository->createQueryBuilder('u')
882 * ->indexBy('u', 'u.id');
884 * // Is equivalent to...
886 * $qb = $em->createQueryBuilder()
888 * ->from('User', 'u', 'u.id');
891 * @param string $alias The root alias of the class.
892 * @param string $indexBy The index for the from.
894 * @return QueryBuilder This QueryBuilder instance.
896 * @throws Query\QueryException
898 public function indexBy($alias, $indexBy)
900 $rootAliases = $this->getRootAliases();
902 if (!in_array($alias, $rootAliases)) {
903 throw new Query\
QueryException(
904 sprintf('Specified root alias %s must be set before invoking indexBy().', $alias)
908 foreach ($this->_dqlParts
['from'] as &$fromClause) {
909 if ($fromClause->getAlias() !== $alias) {
913 $fromClause = new Expr\
From($fromClause->getFrom(), $fromClause->getAlias(), $indexBy);
920 * Creates and adds a join over an entity association to the query.
922 * The entities in the joined association will be fetched as part of the query
923 * result if the alias used for the joined association is placed in the select
927 * $qb = $em->createQueryBuilder()
929 * ->from('User', 'u')
930 * ->join('u.Phonenumbers', 'p', Expr\Join::WITH, 'p.is_primary = 1');
933 * @param string $join The relationship to join.
934 * @param string $alias The alias of the join.
935 * @param string|null $conditionType The condition type constant. Either ON or WITH.
936 * @param string|null $condition The condition for the join.
937 * @param string|null $indexBy The index for the join.
939 * @return QueryBuilder This QueryBuilder instance.
941 public function join($join, $alias, $conditionType = null, $condition = null, $indexBy = null)
943 return $this->innerJoin($join, $alias, $conditionType, $condition, $indexBy);
947 * Creates and adds a join over an entity association to the query.
949 * The entities in the joined association will be fetched as part of the query
950 * result if the alias used for the joined association is placed in the select
954 * $qb = $em->createQueryBuilder()
956 * ->from('User', 'u')
957 * ->innerJoin('u.Phonenumbers', 'p', Expr\Join::WITH, 'p.is_primary = 1');
959 * @param string $join The relationship to join.
960 * @param string $alias The alias of the join.
961 * @param string|null $conditionType The condition type constant. Either ON or WITH.
962 * @param string|null $condition The condition for the join.
963 * @param string|null $indexBy The index for the join.
965 * @return QueryBuilder This QueryBuilder instance.
967 public function innerJoin($join, $alias, $conditionType = null, $condition = null, $indexBy = null)
969 $parentAlias = substr($join, 0, strpos($join, '.'));
971 $rootAlias = $this->findRootAlias($alias, $parentAlias);
973 $join = new Expr\
Join(
974 Expr\Join
::INNER_JOIN
, $join, $alias, $conditionType, $condition, $indexBy
977 return $this->add('join', array($rootAlias => $join), true);
981 * Creates and adds a left join over an entity association to the query.
983 * The entities in the joined association will be fetched as part of the query
984 * result if the alias used for the joined association is placed in the select
988 * $qb = $em->createQueryBuilder()
990 * ->from('User', 'u')
991 * ->leftJoin('u.Phonenumbers', 'p', Expr\Join::WITH, 'p.is_primary = 1');
994 * @param string $join The relationship to join.
995 * @param string $alias The alias of the join.
996 * @param string|null $conditionType The condition type constant. Either ON or WITH.
997 * @param string|null $condition The condition for the join.
998 * @param string|null $indexBy The index for the join.
1000 * @return QueryBuilder This QueryBuilder instance.
1002 public function leftJoin($join, $alias, $conditionType = null, $condition = null, $indexBy = null)
1004 $parentAlias = substr($join, 0, strpos($join, '.'));
1006 $rootAlias = $this->findRootAlias($alias, $parentAlias);
1008 $join = new Expr\
Join(
1009 Expr\Join
::LEFT_JOIN
, $join, $alias, $conditionType, $condition, $indexBy
1012 return $this->add('join', array($rootAlias => $join), true);
1016 * Sets a new value for a field in a bulk update query.
1019 * $qb = $em->createQueryBuilder()
1020 * ->update('User', 'u')
1021 * ->set('u.password', md5('password'))
1022 * ->where('u.id = ?');
1025 * @param string $key The key/field to set.
1026 * @param string $value The value, expression, placeholder, etc.
1028 * @return QueryBuilder This QueryBuilder instance.
1030 public function set($key, $value)
1032 return $this->add('set', new Expr\
Comparison($key, Expr\Comparison
::EQ
, $value), true);
1036 * Specifies one or more restrictions to the query result.
1037 * Replaces any previously specified restrictions, if any.
1040 * $qb = $em->createQueryBuilder()
1042 * ->from('User', 'u')
1043 * ->where('u.id = ?');
1045 * // You can optionally programatically build and/or expressions
1046 * $qb = $em->createQueryBuilder();
1048 * $or = $qb->expr()->orx();
1049 * $or->add($qb->expr()->eq('u.id', 1));
1050 * $or->add($qb->expr()->eq('u.id', 2));
1052 * $qb->update('User', 'u')
1053 * ->set('u.password', md5('password'))
1057 * @param mixed $predicates The restriction predicates.
1059 * @return QueryBuilder This QueryBuilder instance.
1061 public function where($predicates)
1063 if ( ! (func_num_args() == 1 && $predicates instanceof Expr\Composite
)) {
1064 $predicates = new Expr\
Andx(func_get_args());
1067 return $this->add('where', $predicates);
1071 * Adds one or more restrictions to the query results, forming a logical
1072 * conjunction with any previously specified restrictions.
1075 * $qb = $em->createQueryBuilder()
1077 * ->from('User', 'u')
1078 * ->where('u.username LIKE ?')
1079 * ->andWhere('u.is_active = 1');
1082 * @param mixed $where The query restrictions.
1084 * @return QueryBuilder This QueryBuilder instance.
1088 public function andWhere()
1090 $args = func_get_args();
1091 $where = $this->getDQLPart('where');
1093 if ($where instanceof Expr\Andx
) {
1094 $where->addMultiple($args);
1096 array_unshift($args, $where);
1097 $where = new Expr\
Andx($args);
1100 return $this->add('where', $where);
1104 * Adds one or more restrictions to the query results, forming a logical
1105 * disjunction with any previously specified restrictions.
1108 * $qb = $em->createQueryBuilder()
1110 * ->from('User', 'u')
1111 * ->where('u.id = 1')
1112 * ->orWhere('u.id = 2');
1115 * @param mixed $where The WHERE statement.
1117 * @return QueryBuilder
1121 public function orWhere()
1123 $args = func_get_args();
1124 $where = $this->getDqlPart('where');
1126 if ($where instanceof Expr\Orx
) {
1127 $where->addMultiple($args);
1129 array_unshift($args, $where);
1130 $where = new Expr\
Orx($args);
1133 return $this->add('where', $where);
1137 * Specifies a grouping over the results of the query.
1138 * Replaces any previously specified groupings, if any.
1141 * $qb = $em->createQueryBuilder()
1143 * ->from('User', 'u')
1144 * ->groupBy('u.id');
1147 * @param string $groupBy The grouping expression.
1149 * @return QueryBuilder This QueryBuilder instance.
1151 public function groupBy($groupBy)
1153 return $this->add('groupBy', new Expr\
GroupBy(func_get_args()));
1157 * Adds a grouping expression to the query.
1160 * $qb = $em->createQueryBuilder()
1162 * ->from('User', 'u')
1163 * ->groupBy('u.lastLogin')
1164 * ->addGroupBy('u.createdAt');
1167 * @param string $groupBy The grouping expression.
1169 * @return QueryBuilder This QueryBuilder instance.
1171 public function addGroupBy($groupBy)
1173 return $this->add('groupBy', new Expr\
GroupBy(func_get_args()), true);
1177 * Specifies a restriction over the groups of the query.
1178 * Replaces any previous having restrictions, if any.
1180 * @param mixed $having The restriction over the groups.
1182 * @return QueryBuilder This QueryBuilder instance.
1184 public function having($having)
1186 if ( ! (func_num_args() == 1 && ($having instanceof Expr\Andx ||
$having instanceof Expr\Orx
))) {
1187 $having = new Expr\
Andx(func_get_args());
1190 return $this->add('having', $having);
1194 * Adds a restriction over the groups of the query, forming a logical
1195 * conjunction with any existing having restrictions.
1197 * @param mixed $having The restriction to append.
1199 * @return QueryBuilder This QueryBuilder instance.
1201 public function andHaving($having)
1203 $args = func_get_args();
1204 $having = $this->getDqlPart('having');
1206 if ($having instanceof Expr\Andx
) {
1207 $having->addMultiple($args);
1209 array_unshift($args, $having);
1210 $having = new Expr\
Andx($args);
1213 return $this->add('having', $having);
1217 * Adds a restriction over the groups of the query, forming a logical
1218 * disjunction with any existing having restrictions.
1220 * @param mixed $having The restriction to add.
1222 * @return QueryBuilder This QueryBuilder instance.
1224 public function orHaving($having)
1226 $args = func_get_args();
1227 $having = $this->getDqlPart('having');
1229 if ($having instanceof Expr\Orx
) {
1230 $having->addMultiple($args);
1232 array_unshift($args, $having);
1233 $having = new Expr\
Orx($args);
1236 return $this->add('having', $having);
1240 * Specifies an ordering for the query results.
1241 * Replaces any previously specified orderings, if any.
1243 * @param string|Expr\OrderBy $sort The ordering expression.
1244 * @param string $order The ordering direction.
1246 * @return QueryBuilder This QueryBuilder instance.
1248 public function orderBy($sort, $order = null)
1250 $orderBy = ($sort instanceof Expr\OrderBy
) ?
$sort : new Expr\
OrderBy($sort, $order);
1252 return $this->add('orderBy', $orderBy);
1256 * Adds an ordering to the query results.
1258 * @param string|Expr\OrderBy $sort The ordering expression.
1259 * @param string $order The ordering direction.
1261 * @return QueryBuilder This QueryBuilder instance.
1263 public function addOrderBy($sort, $order = null)
1265 $orderBy = ($sort instanceof Expr\OrderBy
) ?
$sort : new Expr\
OrderBy($sort, $order);
1267 return $this->add('orderBy', $orderBy, true);
1271 * Adds criteria to the query.
1273 * Adds where expressions with AND operator.
1275 * Overrides firstResult and maxResults if they're set.
1277 * @param Criteria $criteria
1278 * @return QueryBuilder
1279 * @throws Query\QueryException
1281 public function addCriteria(Criteria
$criteria)
1283 $allAliases = $this->getAllAliases();
1284 if ( ! isset($allAliases[0])) {
1285 throw new Query\
QueryException('No aliases are set before invoking addCriteria().');
1288 $visitor = new QueryExpressionVisitor($this->getAllAliases());
1290 if ($whereExpression = $criteria->getWhereExpression()) {
1291 $this->andWhere($visitor->dispatch($whereExpression));
1292 foreach ($visitor->getParameters() as $parameter) {
1293 $this->parameters
->add($parameter);
1297 if ($criteria->getOrderings()) {
1298 foreach ($criteria->getOrderings() as $sort => $order) {
1300 $hasValidAlias = false;
1301 foreach($allAliases as $alias) {
1302 if(strpos($sort . '.', $alias . '.') === 0) {
1303 $hasValidAlias = true;
1308 if(!$hasValidAlias) {
1309 $sort = $allAliases[0] . '.' . $sort;
1312 $this->addOrderBy($sort, $order);
1316 // Overwrite limits only if they was set in criteria
1317 if (($firstResult = $criteria->getFirstResult()) !== null) {
1318 $this->setFirstResult($firstResult);
1320 if (($maxResults = $criteria->getMaxResults()) !== null) {
1321 $this->setMaxResults($maxResults);
1328 * Gets a query part by its name.
1330 * @param string $queryPartName
1332 * @return mixed $queryPart
1334 * @todo Rename: getQueryPart (or remove?)
1336 public function getDQLPart($queryPartName)
1338 return $this->_dqlParts
[$queryPartName];
1342 * Gets all query parts.
1344 * @return array $dqlParts
1346 * @todo Rename: getQueryParts (or remove?)
1348 public function getDQLParts()
1350 return $this->_dqlParts
;
1356 private function _getDQLForDelete()
1359 . $this->_getReducedDQLQueryPart('from', array('pre' => ' ', 'separator' => ', '))
1360 . $this->_getReducedDQLQueryPart('where', array('pre' => ' WHERE '))
1361 . $this->_getReducedDQLQueryPart('orderBy', array('pre' => ' ORDER BY ', 'separator' => ', '));
1367 private function _getDQLForUpdate()
1370 . $this->_getReducedDQLQueryPart('from', array('pre' => ' ', 'separator' => ', '))
1371 . $this->_getReducedDQLQueryPart('set', array('pre' => ' SET ', 'separator' => ', '))
1372 . $this->_getReducedDQLQueryPart('where', array('pre' => ' WHERE '))
1373 . $this->_getReducedDQLQueryPart('orderBy', array('pre' => ' ORDER BY ', 'separator' => ', '));
1379 private function _getDQLForSelect()
1382 . ($this->_dqlParts
['distinct']===true ?
' DISTINCT' : '')
1383 . $this->_getReducedDQLQueryPart('select', array('pre' => ' ', 'separator' => ', '));
1385 $fromParts = $this->getDQLPart('from');
1386 $joinParts = $this->getDQLPart('join');
1387 $fromClauses = array();
1389 // Loop through all FROM clauses
1390 if ( ! empty($fromParts)) {
1393 foreach ($fromParts as $from) {
1394 $fromClause = (string) $from;
1396 if ($from instanceof Expr\From
&& isset($joinParts[$from->getAlias()])) {
1397 foreach ($joinParts[$from->getAlias()] as $join) {
1398 $fromClause .= ' ' . ((string) $join);
1402 $fromClauses[] = $fromClause;
1406 $dql .= implode(', ', $fromClauses)
1407 . $this->_getReducedDQLQueryPart('where', array('pre' => ' WHERE '))
1408 . $this->_getReducedDQLQueryPart('groupBy', array('pre' => ' GROUP BY ', 'separator' => ', '))
1409 . $this->_getReducedDQLQueryPart('having', array('pre' => ' HAVING '))
1410 . $this->_getReducedDQLQueryPart('orderBy', array('pre' => ' ORDER BY ', 'separator' => ', '));
1416 * @param string $queryPartName
1417 * @param array $options
1421 private function _getReducedDQLQueryPart($queryPartName, $options = array())
1423 $queryPart = $this->getDQLPart($queryPartName);
1425 if (empty($queryPart)) {
1426 return (isset($options['empty']) ?
$options['empty'] : '');
1429 return (isset($options['pre']) ?
$options['pre'] : '')
1430 . (is_array($queryPart) ?
implode($options['separator'], $queryPart) : $queryPart)
1431 . (isset($options['post']) ?
$options['post'] : '');
1437 * @param array|null $parts
1439 * @return QueryBuilder
1441 public function resetDQLParts($parts = null)
1443 if (is_null($parts)) {
1444 $parts = array_keys($this->_dqlParts
);
1447 foreach ($parts as $part) {
1448 $this->resetDQLPart($part);
1455 * Resets single DQL part.
1457 * @param string $part
1459 * @return QueryBuilder
1461 public function resetDQLPart($part)
1463 $this->_dqlParts
[$part] = is_array($this->_dqlParts
[$part]) ?
array() : null;
1464 $this->_state
= self
::STATE_DIRTY
;
1470 * Gets a string representation of this QueryBuilder which corresponds to
1471 * the final DQL query being constructed.
1473 * @return string The string representation of this QueryBuilder.
1475 public function __toString()
1477 return $this->getDQL();
1481 * Deep clones all expression objects in the DQL parts.
1485 public function __clone()
1487 foreach ($this->_dqlParts
as $part => $elements) {
1488 if (is_array($this->_dqlParts
[$part])) {
1489 foreach ($this->_dqlParts
[$part] as $idx => $element) {
1490 if (is_object($element)) {
1491 $this->_dqlParts
[$part][$idx] = clone $element;
1494 } else if (is_object($elements)) {
1495 $this->_dqlParts
[$part] = clone $elements;
1499 $parameters = array();
1501 foreach ($this->parameters
as $parameter) {
1502 $parameters[] = clone $parameter;
1505 $this->parameters
= new ArrayCollection($parameters);