vendor/doctrine/orm/src/QueryBuilder.php line 42

Open in your IDE?
  1. <?php
  3. declare(strict_types=1);
  5. namespace Doctrine\ORM;
  7. use Doctrine\Common\Collections\ArrayCollection;
  8. use Doctrine\Common\Collections\Criteria;
  9. use Doctrine\DBAL\ArrayParameterType;
  10. use Doctrine\DBAL\ParameterType;
  11. use Doctrine\Deprecations\Deprecation;
  12. use Doctrine\ORM\Internal\NoUnknownNamedArguments;
  13. use Doctrine\ORM\Query\Expr;
  14. use Doctrine\ORM\Query\Parameter;
  15. use Doctrine\ORM\Query\QueryExpressionVisitor;
  16. use InvalidArgumentException;
  17. use RuntimeException;
  18. use Stringable;
  20. use function array_keys;
  21. use function array_unshift;
  22. use function assert;
  23. use function count;
  24. use function implode;
  25. use function in_array;
  26. use function is_array;
  27. use function is_numeric;
  28. use function is_object;
  29. use function is_string;
  30. use function key;
  31. use function reset;
  32. use function sprintf;
  33. use function str_starts_with;
  34. use function strpos;
  35. use function strrpos;
  36. use function substr;
  38. /**
  39. * This class is responsible for building DQL query strings via an object oriented
  40. * PHP interface.
  41. */
  42. class QueryBuilder implements Stringable
  43. {
  44. use NoUnknownNamedArguments;
  46. /**
  47. * The array of DQL parts collected.
  48. *
  49. * @phpstan-var array<string, mixed>
  50. */
  51. private array $dqlParts = [
  52. 'distinct' => false,
  53. 'select' => [],
  54. 'from' => [],
  55. 'join' => [],
  56. 'set' => [],
  57. 'where' => null,
  58. 'groupBy' => [],
  59. 'having' => null,
  60. 'orderBy' => [],
  61. ];
  63. private QueryType $type = QueryType::Select;
  65. /**
  66. * The complete DQL string for this query.
  67. */
  68. private string|null $dql = null;
  70. /**
  71. * The query parameters.
  72. *
  73. * @phpstan-var ArrayCollection<int, Parameter>
  74. */
  75. private ArrayCollection $parameters;
  77. /**
  78. * The index of the first result to retrieve.
  79. */
  80. private int $firstResult = 0;
  82. /**
  83. * The maximum number of results to retrieve.
  84. */
  85. private int|null $maxResults = null;
  87. /**
  88. * Keeps root entity alias names for join entities.
  89. *
  90. * @phpstan-var array<string, string>
  91. */
  92. private array $joinRootAliases = [];
  94. /**
  95. * Whether to use second level cache, if available.
  96. */
  97. protected bool $cacheable = false;
  99. /**
  100. * Second level cache region name.
  101. */
  102. protected string|null $cacheRegion = null;
  104. /**
  105. * Second level query cache mode.
  106. *
  107. * @phpstan-var Cache::MODE_*|null
  108. */
  109. protected int|null $cacheMode = null;
  111. protected int $lifetime = 0;
  113. /**
  114. * The counter of bound parameters.
  115. *
  116. * @var int<0, max>
  117. */
  118. private int $boundCounter = 0;
  120. /**
  121. * The hints to set on the query.
  122. *
  123. * @var array<string, string|int|bool|iterable<mixed>|object>
  124. */
  125. private array $hints = [];
  127. /**
  128. * Initializes a new <tt>QueryBuilder</tt> that uses the given <tt>EntityManager</tt>.
  129. *
  130. * @param EntityManagerInterface $em The EntityManager to use.
  131. */
  132. public function __construct(
  133. private readonly EntityManagerInterface $em,
  134. ) {
  135. $this->parameters = new ArrayCollection();
  136. }
  138. final protected function getType(): QueryType
  139. {
  140. return $this->type;
  141. }
  143. /**
  144. * Gets an ExpressionBuilder used for object-oriented construction of query expressions.
  145. * This producer method is intended for convenient inline usage. Example:
  146. *
  147. * <code>
  148. * $qb = $em->createQueryBuilder();
  149. * $qb
  150. * ->select('u')
  151. * ->from('User', 'u')
  152. * ->where($qb->expr()->eq('u.id', 1));
  153. * </code>
  154. *
  155. * For more complex expression construction, consider storing the expression
  156. * builder object in a local variable.
  157. */
  158. public function expr(): Expr
  159. {
  160. return $this->em->getExpressionBuilder();
  161. }
  163. /**
  164. * Enable/disable second level query (result) caching for this query.
  165. *
  166. * @return $this
  167. */
  168. public function setCacheable(bool $cacheable): static
  169. {
  170. $this->cacheable = $cacheable;
  172. return $this;
  173. }
  175. /**
  176. * Are the query results enabled for second level cache?
  177. */
  178. public function isCacheable(): bool
  179. {
  180. return $this->cacheable;
  181. }
  183. /** @return $this */
  184. public function setCacheRegion(string $cacheRegion): static
  185. {
  186. $this->cacheRegion = $cacheRegion;
  188. return $this;
  189. }
  191. /**
  192. * Obtain the name of the second level query cache region in which query results will be stored
  193. *
  194. * @return string|null The cache region name; NULL indicates the default region.
  195. */
  196. public function getCacheRegion(): string|null
  197. {
  198. return $this->cacheRegion;
  199. }
  201. public function getLifetime(): int
  202. {
  203. return $this->lifetime;
  204. }
  206. /**
  207. * Sets the life-time for this query into second level cache.
  208. *
  209. * @return $this
  210. */
  211. public function setLifetime(int $lifetime): static
  212. {
  213. $this->lifetime = $lifetime;
  215. return $this;
  216. }
  218. /** @return array<string, string|int|bool|iterable<mixed>|object> */
  219. public function getHints(): array
  220. {
  221. return $this->hints;
  222. }
  224. /**
  225. * Gets the value of a query hint. If the hint name is not recognized, FALSE is returned.
  226. *
  227. * @return mixed The value of the hint or FALSE, if the hint name is not recognized.
  228. */
  229. public function getHint(string $name): mixed
  230. {
  231. return $this->hints[$name] ?? false;
  232. }
  234. public function hasHint(string $name): bool
  235. {
  236. return isset($this->hints[$name]);
  237. }
  239. /**
  240. * Adds hints for the query.
  241. *
  242. * @return $this
  243. */
  244. public function setHint(string $name, mixed $value): static
  245. {
  246. $this->hints[$name] = $value;
  248. return $this;
  249. }
  251. /** @phpstan-return Cache::MODE_*|null */
  252. public function getCacheMode(): int|null
  253. {
  254. return $this->cacheMode;
  255. }
  257. /**
  258. * @phpstan-param Cache::MODE_* $cacheMode
  259. *
  260. * @return $this
  261. */
  262. public function setCacheMode(int $cacheMode): static
  263. {
  264. $this->cacheMode = $cacheMode;
  266. return $this;
  267. }
  269. /**
  270. * Gets the associated EntityManager for this query builder.
  271. */
  272. public function getEntityManager(): EntityManagerInterface
  273. {
  274. return $this->em;
  275. }
  277. /**
  278. * Gets the complete DQL string formed by the current specifications of this QueryBuilder.
  279. *
  280. * <code>
  281. * $qb = $em->createQueryBuilder()
  282. * ->select('u')
  283. * ->from('User', 'u');
  284. * echo $qb->getDql(); // SELECT u FROM User u
  285. * </code>
  286. */
  287. public function getDQL(): string
  288. {
  289. return $this->dql ??= match ($this->type) {
  290. QueryType::Select => $this->getDQLForSelect(),
  291. QueryType::Delete => $this->getDQLForDelete(),
  292. QueryType::Update => $this->getDQLForUpdate(),
  293. };
  294. }
  296. /**
  297. * Constructs a Query instance from the current specifications of the builder.
  298. *
  299. * <code>
  300. * $qb = $em->createQueryBuilder()
  301. * ->select('u')
  302. * ->from('User', 'u');
  303. * $q = $qb->getQuery();
  304. * $results = $q->execute();
  305. * </code>
  306. */
  307. public function getQuery(): Query
  308. {
  309. $parameters = clone $this->parameters;
  310. $query = $this->em->createQuery($this->getDQL())
  311. ->setParameters($parameters)
  312. ->setFirstResult($this->firstResult)
  313. ->setMaxResults($this->maxResults);
  315. if ($this->lifetime) {
  316. $query->setLifetime($this->lifetime);
  317. }
  319. if ($this->cacheMode) {
  320. $query->setCacheMode($this->cacheMode);
  321. }
  323. if ($this->cacheable) {
  324. $query->setCacheable($this->cacheable);
  325. }
  327. if ($this->cacheRegion) {
  328. $query->setCacheRegion($this->cacheRegion);
  329. }
  331. foreach ($this->hints as $name => $value) {
  332. $query->setHint($name, $value);
  333. }
  335. return $query;
  336. }
  338. /**
  339. * Finds the root entity alias of the joined entity.
  340. *
  341. * @param string $alias The alias of the new join entity
  342. * @param string $parentAlias The parent entity alias of the join relationship
  343. */
  344. private function findRootAlias(string $alias, string $parentAlias): string
  345. {
  346. if (in_array($parentAlias, $this->getRootAliases(), true)) {
  347. $rootAlias = $parentAlias;
  348. } elseif (isset($this->joinRootAliases[$parentAlias])) {
  349. $rootAlias = $this->joinRootAliases[$parentAlias];
  350. } else {
  351. // Should never happen with correct joining order. Might be
  352. // thoughtful to throw exception instead.
  353. $aliases = $this->getRootAliases();
  355. if (! isset($aliases[0])) {
  356. throw new RuntimeException('No alias was set before invoking getRootAlias().');
  357. }
  359. $rootAlias = $aliases[0];
  360. }
  362. $this->joinRootAliases[$alias] = $rootAlias;
  364. return $rootAlias;
  365. }
  367. /**
  368. * Gets the FIRST root alias of the query. This is the first entity alias involved
  369. * in the construction of the query.
  370. *
  371. * <code>
  372. * $qb = $em->createQueryBuilder()
  373. * ->select('u')
  374. * ->from('User', 'u');
  375. *
  376. * echo $qb->getRootAlias(); // u
  377. * </code>
  378. *
  379. * @deprecated Please use $qb->getRootAliases() instead.
  380. *
  381. * @throws RuntimeException
  382. */
  383. public function getRootAlias(): string
  384. {
  385. $aliases = $this->getRootAliases();
  387. if (! isset($aliases[0])) {
  388. throw new RuntimeException('No alias was set before invoking getRootAlias().');
  389. }
  391. return $aliases[0];
  392. }
  394. /**
  395. * Gets the root aliases of the query. This is the entity aliases involved
  396. * in the construction of the query.
  397. *
  398. * <code>
  399. * $qb = $em->createQueryBuilder()
  400. * ->select('u')
  401. * ->from('User', 'u');
  402. *
  403. * $qb->getRootAliases(); // array('u')
  404. * </code>
  405. *
  406. * @return string[]
  407. * @phpstan-return list<string>
  408. */
  409. public function getRootAliases(): array
  410. {
  411. $aliases = [];
  413. foreach ($this->dqlParts['from'] as &$fromClause) {
  414. if (is_string($fromClause)) {
  415. $spacePos = strrpos($fromClause, ' ');
  417. /** @phpstan-var class-string $from */
  418. $from = substr($fromClause, 0, $spacePos);
  419. $alias = substr($fromClause, $spacePos + 1);
  421. $fromClause = new Query\Expr\From($from, $alias);
  422. }
  424. $aliases[] = $fromClause->getAlias();
  425. }
  427. return $aliases;
  428. }
  430. /**
  431. * Gets all the aliases that have been used in the query.
  432. * Including all select root aliases and join aliases
  433. *
  434. * <code>
  435. * $qb = $em->createQueryBuilder()
  436. * ->select('u')
  437. * ->from('User', 'u')
  438. * ->join('u.articles','a');
  439. *
  440. * $qb->getAllAliases(); // array('u','a')
  441. * </code>
  442. *
  443. * @return string[]
  444. * @phpstan-return list<string>
  445. */
  446. public function getAllAliases(): array
  447. {
  448. return [...$this->getRootAliases(), ...array_keys($this->joinRootAliases)];
  449. }
  451. /**
  452. * Gets the root entities of the query. This is the entity classes involved
  453. * in the construction of the query.
  454. *
  455. * <code>
  456. * $qb = $em->createQueryBuilder()
  457. * ->select('u')
  458. * ->from('User', 'u');
  459. *
  460. * $qb->getRootEntities(); // array('User')
  461. * </code>
  462. *
  463. * @return string[]
  464. * @phpstan-return list<class-string>
  465. */
  466. public function getRootEntities(): array
  467. {
  468. $entities = [];
  470. foreach ($this->dqlParts['from'] as &$fromClause) {
  471. if (is_string($fromClause)) {
  472. $spacePos = strrpos($fromClause, ' ');
  474. /** @phpstan-var class-string $from */
  475. $from = substr($fromClause, 0, $spacePos);
  476. $alias = substr($fromClause, $spacePos + 1);
  478. $fromClause = new Query\Expr\From($from, $alias);
  479. }
  481. $entities[] = $fromClause->getFrom();
  482. }
  484. return $entities;
  485. }
  487. /**
  488. * Sets a query parameter for the query being constructed.
  489. *
  490. * <code>
  491. * $qb = $em->createQueryBuilder()
  492. * ->select('u')
  493. * ->from('User', 'u')
  494. * ->where('u.id = :user_id')
  495. * ->setParameter('user_id', 1);
  496. * </code>
  497. *
  498. * @param string|int $key The parameter position or name.
  499. * @param ParameterType|ArrayParameterType|string|int|null $type ParameterType::*, ArrayParameterType::* or \Doctrine\DBAL\Types\Type::* constant
  500. *
  501. * @return $this
  502. */
  503. public function setParameter(string|int $key, mixed $value, ParameterType|ArrayParameterType|string|int|null $type = null): static
  504. {
  505. $existingParameter = $this->getParameter($key);
  507. if ($existingParameter !== null) {
  508. $existingParameter->setValue($value, $type);
  510. return $this;
  511. }
  513. $this->parameters->add(new Parameter($key, $value, $type));
  515. return $this;
  516. }
  518. /**
  519. * Sets a collection of query parameters for the query being constructed.
  520. *
  521. * <code>
  522. * $qb = $em->createQueryBuilder()
  523. * ->select('u')
  524. * ->from('User', 'u')
  525. * ->where('u.id = :user_id1 OR u.id = :user_id2')
  526. * ->setParameters(new ArrayCollection(array(
  527. * new Parameter('user_id1', 1),
  528. * new Parameter('user_id2', 2)
  529. * )));
  530. * </code>
  531. *
  532. * @phpstan-param ArrayCollection<int, Parameter> $parameters
  533. *
  534. * @return $this
  535. */
  536. public function setParameters(ArrayCollection $parameters): static
  537. {
  538. $this->parameters = $parameters;
  540. return $this;
  541. }
  543. /**
  544. * Gets all defined query parameters for the query being constructed.
  545. *
  546. * @phpstan-return ArrayCollection<int, Parameter>
  547. */
  548. public function getParameters(): ArrayCollection
  549. {
  550. return $this->parameters;
  551. }
  553. /**
  554. * Gets a (previously set) query parameter of the query being constructed.
  555. */
  556. public function getParameter(string|int $key): Parameter|null
  557. {
  558. $key = Parameter::normalizeName($key);
  560. $filteredParameters = $this->parameters->filter(
  561. static fn (Parameter $parameter): bool => $key === $parameter->getName(),
  562. );
  564. return ! $filteredParameters->isEmpty() ? $filteredParameters->first() : null;
  565. }
  567. /**
  568. * Sets the position of the first result to retrieve (the "offset").
  569. *
  570. * @return $this
  571. */
  572. public function setFirstResult(int|null $firstResult): static
  573. {
  574. $this->firstResult = (int) $firstResult;
  576. return $this;
  577. }
  579. /**
  580. * Gets the position of the first result the query object was set to retrieve (the "offset").
  581. */
  582. public function getFirstResult(): int
  583. {
  584. return $this->firstResult;
  585. }
  587. /**
  588. * Sets the maximum number of results to retrieve (the "limit").
  589. *
  590. * @return $this
  591. */
  592. public function setMaxResults(int|null $maxResults): static
  593. {
  594. if ($this->type === QueryType::Delete || $this->type === QueryType::Update) {
  595. throw new RuntimeException('Setting a limit is not supported for delete or update queries.');
  596. }
  598. $this->maxResults = $maxResults;
  600. return $this;
  601. }
  603. /**
  604. * Gets the maximum number of results the query object was set to retrieve (the "limit").
  605. * Returns NULL if {@link setMaxResults} was not applied to this query builder.
  606. */
  607. public function getMaxResults(): int|null
  608. {
  609. return $this->maxResults;
  610. }
  612. /**
  613. * Either appends to or replaces a single, generic query part.
  614. *
  615. * The available parts are: 'select', 'from', 'join', 'set', 'where',
  616. * 'groupBy', 'having' and 'orderBy'.
  617. *
  618. * @phpstan-param string|object|list<string>|array{join: array<int|string, object>} $dqlPart
  619. *
  620. * @return $this
  621. */
  622. public function add(string $dqlPartName, string|object|array $dqlPart, bool $append = false): static
  623. {
  624. if ($append && ($dqlPartName === 'where' || $dqlPartName === 'having')) {
  625. throw new InvalidArgumentException(
  626. "Using \$append = true does not have an effect with 'where' or 'having' " .
  627. 'parts. See QueryBuilder#andWhere() for an example for correct usage.',
  628. );
  629. }
  631. $isMultiple = is_array($this->dqlParts[$dqlPartName])
  632. && ! ($dqlPartName === 'join' && ! $append);
  634. // Allow adding any part retrieved from self::getDQLParts().
  635. if (is_array($dqlPart) && $dqlPartName !== 'join') {
  636. $dqlPart = reset($dqlPart);
  637. }
  639. if ($dqlPartName === 'join') {
  640. $newDqlPart = [];
  642. foreach ($dqlPart as $k => $v) {
  643. if (is_numeric($k)) {
  644. Deprecation::trigger(
  645. 'doctrine/orm',
  646. 'https://github.com/doctrine/orm/pull/12051',
  647. 'Using numeric keys in %s for join parts is deprecated and will not be supported in 4.0. Use an associative array with the root alias as key instead.',
  648. __METHOD__,
  649. );
  650. $aliases = $this->getRootAliases();
  652. if (! isset($aliases[0])) {
  653. throw new RuntimeException('No alias was set before invoking add().');
  654. }
  656. $k = $aliases[0];
  657. }
  659. $newDqlPart[$k] = $v;
  660. }
  662. $dqlPart = $newDqlPart;
  663. }
  665. if ($append && $isMultiple) {
  666. if (is_array($dqlPart)) {
  667. $key = key($dqlPart);
  669. $this->dqlParts[$dqlPartName][$key][] = $dqlPart[$key];
  670. } else {
  671. $this->dqlParts[$dqlPartName][] = $dqlPart;
  672. }
  673. } else {
  674. $this->dqlParts[$dqlPartName] = $isMultiple ? [$dqlPart] : $dqlPart;
  675. }
  677. $this->dql = null;
  679. return $this;
  680. }
  682. /**
  683. * Specifies an item that is to be returned in the query result.
  684. * Replaces any previously specified selections, if any.
  685. *
  686. * <code>
  687. * $qb = $em->createQueryBuilder()
  688. * ->select('u', 'p')
  689. * ->from('User', 'u')
  690. * ->leftJoin('u.Phonenumbers', 'p');
  691. * </code>
  692. *
  693. * @return $this
  694. */
  695. public function select(mixed ...$select): static
  696. {
  697. self::validateVariadicParameter($select);
  699. $this->type = QueryType::Select;
  701. if ($select === []) {
  702. return $this;
  703. }
  705. return $this->add('select', new Expr\Select($select), false);
  706. }
  708. /**
  709. * Adds a DISTINCT flag to this query.
  710. *
  711. * <code>
  712. * $qb = $em->createQueryBuilder()
  713. * ->select('u')
  714. * ->distinct()
  715. * ->from('User', 'u');
  716. * </code>
  717. *
  718. * @return $this
  719. */
  720. public function distinct(bool $flag = true): static
  721. {
  722. if ($this->dqlParts['distinct'] !== $flag) {
  723. $this->dqlParts['distinct'] = $flag;
  724. $this->dql = null;
  725. }
  727. return $this;
  728. }
  730. /**
  731. * Adds an item that is to be returned in the query result.
  732. *
  733. * <code>
  734. * $qb = $em->createQueryBuilder()
  735. * ->select('u')
  736. * ->addSelect('p')
  737. * ->from('User', 'u')
  738. * ->leftJoin('u.Phonenumbers', 'p');
  739. * </code>
  740. *
  741. * @return $this
  742. */
  743. public function addSelect(mixed ...$select): static
  744. {
  745. self::validateVariadicParameter($select);
  747. $this->type = QueryType::Select;
  749. if ($select === []) {
  750. return $this;
  751. }
  753. return $this->add('select', new Expr\Select($select), true);
  754. }
  756. /**
  757. * Turns the query being built into a bulk delete query that ranges over
  758. * a certain entity type.
  759. *
  760. * <code>
  761. * $qb = $em->createQueryBuilder()
  762. * ->delete('User', 'u')
  763. * ->where('u.id = :user_id')
  764. * ->setParameter('user_id', 1);
  765. * </code>
  766. *
  767. * @param class-string|null $delete The class/type whose instances are subject to the deletion.
  768. * @param string|null $alias The class/type alias used in the constructed query.
  769. *
  770. * @return $this
  771. */
  772. public function delete(string|null $delete = null, string|null $alias = null): static
  773. {
  774. $this->type = QueryType::Delete;
  776. if (! $delete) {
  777. return $this;
  778. }
  780. if (! $alias) {
  781. throw new InvalidArgumentException(sprintf(
  782. '%s(): The alias for entity %s must not be omitted.',
  783. __METHOD__,
  784. $delete,
  785. ));
  786. }
  788. return $this->add('from', new Expr\From($delete, $alias));
  789. }
  791. /**
  792. * Turns the query being built into a bulk update query that ranges over
  793. * a certain entity type.
  794. *
  795. * <code>
  796. * $qb = $em->createQueryBuilder()
  797. * ->update('User', 'u')
  798. * ->set('u.password', '?1')
  799. * ->where('u.id = ?2');
  800. * </code>
  801. *
  802. * @param class-string|null $update The class/type whose instances are subject to the update.
  803. * @param string|null $alias The class/type alias used in the constructed query.
  804. *
  805. * @return $this
  806. */
  807. public function update(string|null $update = null, string|null $alias = null): static
  808. {
  809. $this->type = QueryType::Update;
  811. if (! $update) {
  812. return $this;
  813. }
  815. if (! $alias) {
  816. throw new InvalidArgumentException(sprintf(
  817. '%s(): The alias for entity %s must not be omitted.',
  818. __METHOD__,
  819. $update,
  820. ));
  821. }
  823. return $this->add('from', new Expr\From($update, $alias));
  824. }
  826. /**
  827. * Creates and adds a query root corresponding to the entity identified by the given alias,
  828. * forming a cartesian product with any existing query roots.
  829. *
  830. * <code>
  831. * $qb = $em->createQueryBuilder()
  832. * ->select('u')
  833. * ->from('User', 'u');
  834. * </code>
  835. *
  836. * @param class-string $from The class name.
  837. * @param string $alias The alias of the class.
  838. * @param string|null $indexBy The index for the from.
  839. *
  840. * @return $this
  841. */
  842. public function from(string $from, string $alias, string|null $indexBy = null): static
  843. {
  844. return $this->add('from', new Expr\From($from, $alias, $indexBy), true);
  845. }
  847. /**
  848. * Updates a query root corresponding to an entity setting its index by. This method is intended to be used with
  849. * EntityRepository->createQueryBuilder(), which creates the initial FROM clause and do not allow you to update it
  850. * setting an index by.
  851. *
  852. * <code>
  853. * $qb = $userRepository->createQueryBuilder('u')
  854. * ->indexBy('u', 'u.id');
  855. *
  856. * // Is equivalent to...
  857. *
  858. * $qb = $em->createQueryBuilder()
  859. * ->select('u')
  860. * ->from('User', 'u', 'u.id');
  861. * </code>
  862. *
  863. * @return $this
  864. *
  865. * @throws Query\QueryException
  866. */
  867. public function indexBy(string $alias, string $indexBy): static
  868. {
  869. $rootAliases = $this->getRootAliases();
  871. if (! in_array($alias, $rootAliases, true)) {
  872. throw new Query\QueryException(
  873. sprintf('Specified root alias %s must be set before invoking indexBy().', $alias),
  874. );
  875. }
  877. foreach ($this->dqlParts['from'] as &$fromClause) {
  878. assert($fromClause instanceof Expr\From);
  879. if ($fromClause->getAlias() !== $alias) {
  880. continue;
  881. }
  883. $fromClause = new Expr\From($fromClause->getFrom(), $fromClause->getAlias(), $indexBy);
  884. }
  886. return $this;
  887. }
  889. /**
  890. * Creates and adds a join over an entity association to the query.
  891. *
  892. * The entities in the joined association will be fetched as part of the query
  893. * result if the alias used for the joined association is placed in the select
  894. * expressions.
  895. *
  896. * <code>
  897. * $qb = $em->createQueryBuilder()
  898. * ->select('u')
  899. * ->from('User', 'u')
  900. * ->join('u.Phonenumbers', 'p', Expr\Join::WITH, 'p.is_primary = 1');
  901. * </code>
  902. *
  903. * @phpstan-param Expr\Join::ON|Expr\Join::WITH|null $conditionType
  904. *
  905. * @return $this
  906. */
  907. public function join(
  908. string $join,
  909. string $alias,
  910. string|null $conditionType = null,
  911. string|Expr\Composite|Expr\Comparison|Expr\Func|null $condition = null,
  912. string|null $indexBy = null,
  913. ): static {
  914. return $this->innerJoin($join, $alias, $conditionType, $condition, $indexBy);
  915. }
  917. /**
  918. * Creates and adds a join over an entity association to the query.
  919. *
  920. * The entities in the joined association will be fetched as part of the query
  921. * result if the alias used for the joined association is placed in the select
  922. * expressions.
  923. *
  924. * [php]
  925. * $qb = $em->createQueryBuilder()
  926. * ->select('u')
  927. * ->from('User', 'u')
  928. * ->innerJoin('u.Phonenumbers', 'p', Expr\Join::WITH, 'p.is_primary = 1');
  929. *
  930. * @phpstan-param Expr\Join::ON|Expr\Join::WITH|null $conditionType
  931. *
  932. * @return $this
  933. */
  934. public function innerJoin(
  935. string $join,
  936. string $alias,
  937. string|null $conditionType = null,
  938. string|Expr\Composite|Expr\Comparison|Expr\Func|null $condition = null,
  939. string|null $indexBy = null,
  940. ): static {
  941. $parentAlias = substr($join, 0, (int) strpos($join, '.'));
  943. $rootAlias = $this->findRootAlias($alias, $parentAlias);
  945. $join = new Expr\Join(
  946. Expr\Join::INNER_JOIN,
  947. $join,
  948. $alias,
  949. $conditionType,
  950. $condition,
  951. $indexBy,
  952. );
  954. return $this->add('join', [$rootAlias => $join], true);
  955. }
  957. /**
  958. * Creates and adds a left join over an entity association to the query.
  959. *
  960. * The entities in the joined association will be fetched as part of the query
  961. * result if the alias used for the joined association is placed in the select
  962. * expressions.
  963. *
  964. * <code>
  965. * $qb = $em->createQueryBuilder()
  966. * ->select('u')
  967. * ->from('User', 'u')
  968. * ->leftJoin('u.Phonenumbers', 'p', Expr\Join::WITH, 'p.is_primary = 1');
  969. * </code>
  970. *
  971. * @phpstan-param Expr\Join::ON|Expr\Join::WITH|null $conditionType
  972. *
  973. * @return $this
  974. */
  975. public function leftJoin(
  976. string $join,
  977. string $alias,
  978. string|null $conditionType = null,
  979. string|Expr\Composite|Expr\Comparison|Expr\Func|null $condition = null,
  980. string|null $indexBy = null,
  981. ): static {
  982. $parentAlias = substr($join, 0, (int) strpos($join, '.'));
  984. $rootAlias = $this->findRootAlias($alias, $parentAlias);
  986. $join = new Expr\Join(
  987. Expr\Join::LEFT_JOIN,
  988. $join,
  989. $alias,
  990. $conditionType,
  991. $condition,
  992. $indexBy,
  993. );
  995. return $this->add('join', [$rootAlias => $join], true);
  996. }
  998. /**
  999. * Sets a new value for a field in a bulk update query.
  1000. *
  1001. * <code>
  1002. * $qb = $em->createQueryBuilder()
  1003. * ->update('User', 'u')
  1004. * ->set('u.password', '?1')
  1005. * ->where('u.id = ?2');
  1006. * </code>
  1007. *
  1008. * @return $this
  1009. */
  1010. public function set(string $key, mixed $value): static
  1011. {
  1012. return $this->add('set', new Expr\Comparison($key, Expr\Comparison::EQ, $value), true);
  1013. }
  1015. /**
  1016. * Specifies one or more restrictions to the query result.
  1017. * Replaces any previously specified restrictions, if any.
  1018. *
  1019. * <code>
  1020. * $qb = $em->createQueryBuilder()
  1021. * ->select('u')
  1022. * ->from('User', 'u')
  1023. * ->where('u.id = ?');
  1024. *
  1025. * // You can optionally programmatically build and/or expressions
  1026. * $qb = $em->createQueryBuilder();
  1027. *
  1028. * $or = $qb->expr()->orX();
  1029. * $or->add($qb->expr()->eq('u.id', 1));
  1030. * $or->add($qb->expr()->eq('u.id', 2));
  1031. *
  1032. * $qb->update('User', 'u')
  1033. * ->set('u.password', '?')
  1034. * ->where($or);
  1035. * </code>
  1036. *
  1037. * @return $this
  1038. */
  1039. public function where(mixed ...$predicates): static
  1040. {
  1041. self::validateVariadicParameter($predicates);
  1043. if (! (count($predicates) === 1 && $predicates[0] instanceof Expr\Composite)) {
  1044. $predicates = new Expr\Andx($predicates);
  1045. }
  1047. return $this->add('where', $predicates);
  1048. }
  1050. /**
  1051. * Adds one or more restrictions to the query results, forming a logical
  1052. * conjunction with any previously specified restrictions.
  1053. *
  1054. * <code>
  1055. * $qb = $em->createQueryBuilder()
  1056. * ->select('u')
  1057. * ->from('User', 'u')
  1058. * ->where('u.username LIKE ?')
  1059. * ->andWhere('u.is_active = 1');
  1060. * </code>
  1061. *
  1062. * @see where()
  1063. *
  1064. * @return $this
  1065. */
  1066. public function andWhere(mixed ...$where): static
  1067. {
  1068. self::validateVariadicParameter($where);
  1070. $dql = $this->getDQLPart('where');
  1072. if ($dql instanceof Expr\Andx) {
  1073. $dql->addMultiple($where);
  1074. } else {
  1075. array_unshift($where, $dql);
  1076. $dql = new Expr\Andx($where);
  1077. }
  1079. return $this->add('where', $dql);
  1080. }
  1082. /**
  1083. * Adds one or more restrictions to the query results, forming a logical
  1084. * disjunction with any previously specified restrictions.
  1085. *
  1086. * <code>
  1087. * $qb = $em->createQueryBuilder()
  1088. * ->select('u')
  1089. * ->from('User', 'u')
  1090. * ->where('u.id = 1')
  1091. * ->orWhere('u.id = 2');
  1092. * </code>
  1093. *
  1094. * @see where()
  1095. *
  1096. * @return $this
  1097. */
  1098. public function orWhere(mixed ...$where): static
  1099. {
  1100. self::validateVariadicParameter($where);
  1102. $dql = $this->getDQLPart('where');
  1104. if ($dql instanceof Expr\Orx) {
  1105. $dql->addMultiple($where);
  1106. } else {
  1107. array_unshift($where, $dql);
  1108. $dql = new Expr\Orx($where);
  1109. }
  1111. return $this->add('where', $dql);
  1112. }
  1114. /**
  1115. * Specifies a grouping over the results of the query.
  1116. * Replaces any previously specified groupings, if any.
  1117. *
  1118. * <code>
  1119. * $qb = $em->createQueryBuilder()
  1120. * ->select('u')
  1121. * ->from('User', 'u')
  1122. * ->groupBy('u.id');
  1123. * </code>
  1124. *
  1125. * @return $this
  1126. */
  1127. public function groupBy(string ...$groupBy): static
  1128. {
  1129. self::validateVariadicParameter($groupBy);
  1131. return $this->add('groupBy', new Expr\GroupBy($groupBy));
  1132. }
  1134. /**
  1135. * Adds a grouping expression to the query.
  1136. *
  1137. * <code>
  1138. * $qb = $em->createQueryBuilder()
  1139. * ->select('u')
  1140. * ->from('User', 'u')
  1141. * ->groupBy('u.lastLogin')
  1142. * ->addGroupBy('u.createdAt');
  1143. * </code>
  1144. *
  1145. * @return $this
  1146. */
  1147. public function addGroupBy(string ...$groupBy): static
  1148. {
  1149. self::validateVariadicParameter($groupBy);
  1151. return $this->add('groupBy', new Expr\GroupBy($groupBy), true);
  1152. }
  1154. /**
  1155. * Specifies a restriction over the groups of the query.
  1156. * Replaces any previous having restrictions, if any.
  1157. *
  1158. * @return $this
  1159. */
  1160. public function having(mixed ...$having): static
  1161. {
  1162. self::validateVariadicParameter($having);
  1164. if (! (count($having) === 1 && ($having[0] instanceof Expr\Andx || $having[0] instanceof Expr\Orx))) {
  1165. $having = new Expr\Andx($having);
  1166. }
  1168. return $this->add('having', $having);
  1169. }
  1171. /**
  1172. * Adds a restriction over the groups of the query, forming a logical
  1173. * conjunction with any existing having restrictions.
  1174. *
  1175. * @return $this
  1176. */
  1177. public function andHaving(mixed ...$having): static
  1178. {
  1179. self::validateVariadicParameter($having);
  1181. $dql = $this->getDQLPart('having');
  1183. if ($dql instanceof Expr\Andx) {
  1184. $dql->addMultiple($having);
  1185. } else {
  1186. array_unshift($having, $dql);
  1187. $dql = new Expr\Andx($having);
  1188. }
  1190. return $this->add('having', $dql);
  1191. }
  1193. /**
  1194. * Adds a restriction over the groups of the query, forming a logical
  1195. * disjunction with any existing having restrictions.
  1196. *
  1197. * @return $this
  1198. */
  1199. public function orHaving(mixed ...$having): static
  1200. {
  1201. self::validateVariadicParameter($having);
  1203. $dql = $this->getDQLPart('having');
  1205. if ($dql instanceof Expr\Orx) {
  1206. $dql->addMultiple($having);
  1207. } else {
  1208. array_unshift($having, $dql);
  1209. $dql = new Expr\Orx($having);
  1210. }
  1212. return $this->add('having', $dql);
  1213. }
  1215. /**
  1216. * Specifies an ordering for the query results.
  1217. * Replaces any previously specified orderings, if any.
  1218. *
  1219. * @return $this
  1220. */
  1221. public function orderBy(string|Expr\OrderBy $sort, string|null $order = null): static
  1222. {
  1223. $orderBy = $sort instanceof Expr\OrderBy ? $sort : new Expr\OrderBy($sort, $order);
  1225. return $this->add('orderBy', $orderBy);
  1226. }
  1228. /**
  1229. * Adds an ordering to the query results.
  1230. *
  1231. * @return $this
  1232. */
  1233. public function addOrderBy(string|Expr\OrderBy $sort, string|null $order = null): static
  1234. {
  1235. $orderBy = $sort instanceof Expr\OrderBy ? $sort : new Expr\OrderBy($sort, $order);
  1237. return $this->add('orderBy', $orderBy, true);
  1238. }
  1240. /**
  1241. * Adds criteria to the query.
  1242. *
  1243. * Adds where expressions with AND operator.
  1244. * Adds orderings.
  1245. * Overrides firstResult and maxResults if they're set.
  1246. *
  1247. * @return $this
  1248. *
  1249. * @throws Query\QueryException
  1250. */
  1251. public function addCriteria(Criteria $criteria): static
  1252. {
  1253. $allAliases = $this->getAllAliases();
  1254. if (! isset($allAliases[0])) {
  1255. throw new Query\QueryException('No aliases are set before invoking addCriteria().');
  1256. }
  1258. $visitor = new QueryExpressionVisitor($this->getAllAliases());
  1260. $whereExpression = $criteria->getWhereExpression();
  1261. if ($whereExpression) {
  1262. $this->andWhere($visitor->dispatch($whereExpression));
  1263. foreach ($visitor->getParameters() as $parameter) {
  1264. $this->parameters->add($parameter);
  1265. }
  1266. }
  1268. foreach ($criteria->orderings() as $sort => $order) {
  1269. $hasValidAlias = false;
  1270. foreach ($allAliases as $alias) {
  1271. if (str_starts_with($sort . '.', $alias . '.')) {
  1272. $hasValidAlias = true;
  1273. break;
  1274. }
  1275. }
  1277. if (! $hasValidAlias) {
  1278. $sort = $allAliases[0] . '.' . $sort;
  1279. }
  1281. $this->addOrderBy($sort, $order->value);
  1282. }
  1284. // Overwrite limits only if they was set in criteria
  1285. $firstResult = $criteria->getFirstResult();
  1286. if ($firstResult > 0) {
  1287. $this->setFirstResult($firstResult);
  1288. }
  1290. $maxResults = $criteria->getMaxResults();
  1291. if ($maxResults !== null) {
  1292. $this->setMaxResults($maxResults);
  1293. }
  1295. return $this;
  1296. }
  1298. /**
  1299. * Gets a query part by its name.
  1300. */
  1301. public function getDQLPart(string $queryPartName): mixed
  1302. {
  1303. return $this->dqlParts[$queryPartName];
  1304. }
  1306. /**
  1307. * Gets all query parts.
  1308. *
  1309. * @phpstan-return array<string, mixed> $dqlParts
  1310. */
  1311. public function getDQLParts(): array
  1312. {
  1313. return $this->dqlParts;
  1314. }
  1316. private function getDQLForDelete(): string
  1317. {
  1318. return 'DELETE'
  1319. . $this->getReducedDQLQueryPart('from', ['pre' => ' ', 'separator' => ', '])
  1320. . $this->getReducedDQLQueryPart('where', ['pre' => ' WHERE '])
  1321. . $this->getReducedDQLQueryPart('orderBy', ['pre' => ' ORDER BY ', 'separator' => ', ']);
  1322. }
  1324. private function getDQLForUpdate(): string
  1325. {
  1326. return 'UPDATE'
  1327. . $this->getReducedDQLQueryPart('from', ['pre' => ' ', 'separator' => ', '])
  1328. . $this->getReducedDQLQueryPart('set', ['pre' => ' SET ', 'separator' => ', '])
  1329. . $this->getReducedDQLQueryPart('where', ['pre' => ' WHERE '])
  1330. . $this->getReducedDQLQueryPart('orderBy', ['pre' => ' ORDER BY ', 'separator' => ', ']);
  1331. }
  1333. private function getDQLForSelect(): string
  1334. {
  1335. $dql = 'SELECT'
  1336. . ($this->dqlParts['distinct'] === true ? ' DISTINCT' : '')
  1337. . $this->getReducedDQLQueryPart('select', ['pre' => ' ', 'separator' => ', ']);
  1339. $fromParts = $this->getDQLPart('from');
  1340. $joinParts = $this->getDQLPart('join');
  1341. $fromClauses = [];
  1343. // Loop through all FROM clauses
  1344. if (! empty($fromParts)) {
  1345. $dql .= ' FROM ';
  1347. foreach ($fromParts as $from) {
  1348. $fromClause = (string) $from;
  1350. if ($from instanceof Expr\From && isset($joinParts[$from->getAlias()])) {
  1351. foreach ($joinParts[$from->getAlias()] as $join) {
  1352. $fromClause .= ' ' . ((string) $join);
  1353. }
  1354. }
  1356. $fromClauses[] = $fromClause;
  1357. }
  1358. }
  1360. $dql .= implode(', ', $fromClauses)
  1361. . $this->getReducedDQLQueryPart('where', ['pre' => ' WHERE '])
  1362. . $this->getReducedDQLQueryPart('groupBy', ['pre' => ' GROUP BY ', 'separator' => ', '])
  1363. . $this->getReducedDQLQueryPart('having', ['pre' => ' HAVING '])
  1364. . $this->getReducedDQLQueryPart('orderBy', ['pre' => ' ORDER BY ', 'separator' => ', ']);
  1366. return $dql;
  1367. }
  1369. /** @phpstan-param array<string, mixed> $options */
  1370. private function getReducedDQLQueryPart(string $queryPartName, array $options = []): string
  1371. {
  1372. $queryPart = $this->getDQLPart($queryPartName);
  1374. if (empty($queryPart)) {
  1375. return $options['empty'] ?? '';
  1376. }
  1378. return ($options['pre'] ?? '')
  1379. . (is_array($queryPart) ? implode($options['separator'], $queryPart) : $queryPart)
  1380. . ($options['post'] ?? '');
  1381. }
  1383. /**
  1384. * Resets DQL parts.
  1385. *
  1386. * @param string[]|null $parts
  1387. * @phpstan-param list<string>|null $parts
  1388. *
  1389. * @return $this
  1390. */
  1391. public function resetDQLParts(array|null $parts = null): static
  1392. {
  1393. if ($parts === null) {
  1394. $parts = array_keys($this->dqlParts);
  1395. }
  1397. foreach ($parts as $part) {
  1398. $this->resetDQLPart($part);
  1399. }
  1401. return $this;
  1402. }
  1404. /**
  1405. * Resets single DQL part.
  1406. *
  1407. * @return $this
  1408. */
  1409. public function resetDQLPart(string $part): static
  1410. {
  1411. $this->dqlParts[$part] = is_array($this->dqlParts[$part]) ? [] : null;
  1412. $this->dql = null;
  1414. return $this;
  1415. }
  1417. /**
  1418. * Creates a new named parameter and bind the value $value to it.
  1419. *
  1420. * The parameter $value specifies the value that you want to bind. If
  1421. * $placeholder is not provided createNamedParameter() will automatically
  1422. * create a placeholder for you. An automatic placeholder will be of the
  1423. * name ':dcValue1', ':dcValue2' etc.
  1424. *
  1425. * Example:
  1426. * <code>
  1427. * $qb = $em->createQueryBuilder();
  1428. * $qb
  1429. * ->select('u')
  1430. * ->from('User', 'u')
  1431. * ->where('u.username = ' . $qb->createNamedParameter('Foo', Types::STRING))
  1432. * ->orWhere('u.username = ' . $qb->createNamedParameter('Bar', Types::STRING))
  1433. * </code>
  1434. *
  1435. * @param ParameterType|ArrayParameterType|string|int|null $type ParameterType::*, ArrayParameterType::* or \Doctrine\DBAL\Types\Type::* constant
  1436. * @param non-empty-string|null $placeholder The name to bind with. The string must start with a colon ':'.
  1437. *
  1438. * @return non-empty-string the placeholder name used.
  1439. */
  1440. public function createNamedParameter(mixed $value, ParameterType|ArrayParameterType|string|int|null $type = null, string|null $placeholder = null): string
  1441. {
  1442. if ($placeholder === null) {
  1443. $this->boundCounter++;
  1444. $placeholder = ':dcValue' . $this->boundCounter;
  1445. }
  1447. $this->setParameter(substr($placeholder, 1), $value, $type);
  1449. return $placeholder;
  1450. }
  1452. /**
  1453. * Gets a string representation of this QueryBuilder which corresponds to
  1454. * the final DQL query being constructed.
  1455. */
  1456. public function __toString(): string
  1457. {
  1458. return $this->getDQL();
  1459. }
  1461. /**
  1462. * Deep clones all expression objects in the DQL parts.
  1463. *
  1464. * @return void
  1465. */
  1466. public function __clone()
  1467. {
  1468. foreach ($this->dqlParts as $part => $elements) {
  1469. if (is_array($this->dqlParts[$part])) {
  1470. foreach ($this->dqlParts[$part] as $idx => $element) {
  1471. if (is_object($element)) {
  1472. $this->dqlParts[$part][$idx] = clone $element;
  1473. }
  1474. }
  1475. } elseif (is_object($elements)) {
  1476. $this->dqlParts[$part] = clone $elements;
  1477. }
  1478. }
  1480. $parameters = [];
  1482. foreach ($this->parameters as $parameter) {
  1483. $parameters[] = clone $parameter;
  1484. }
  1486. $this->parameters = new ArrayCollection($parameters);
  1487. }
  1488. }