vendor/shopware/core/Framework/Adapter/Doctrine/Patch/QueryBuilder.php line 249

Open in your IDE?
  1. <?php declare(strict_types=1);
  3. /**
  4.  * @package core
  5.  * Forward compatibility adaption to add `executeQuery` and `executeStatement` methods to the Query Builder
  6.  */
  8. namespace Doctrine\DBAL\Query;
  10. use Doctrine\DBAL\Connection;
  11. use Doctrine\DBAL\Exception;
  12. use Doctrine\DBAL\ForwardCompatibility;
  13. use Doctrine\DBAL\ParameterType;
  14. use Doctrine\DBAL\Query\Expression\CompositeExpression;
  15. use Doctrine\DBAL\Query\Expression\ExpressionBuilder;
  16. use Doctrine\DBAL\Result;
  17. use Doctrine\DBAL\Types\Type;
  18. use Doctrine\Deprecations\Deprecation;
  19. use function array_filter;
  20. use function array_keys;
  21. use function array_unshift;
  22. use function implode;
  23. use function key;
  24. use function strtoupper;
  25. use function substr;
  27. /**
  28.  * @package core
  29.  * QueryBuilder class is responsible to dynamically create SQL queries.
  30.  *
  31.  * Important: Verify that every feature you use will work with your database vendor.
  32.  * SQL Query Builder does not attempt to validate the generated SQL at all.
  33.  *
  34.  * The query builder does no validation whatsoever if certain features even work with the
  35.  * underlying database vendor. Limit queries and joins are NOT applied to UPDATE and DELETE statements
  36.  * even if some vendors such as MySQL support it.
  37.  */
  38. class QueryBuilder
  39. {
  40.     /*
  41.      * The query types.
  42.      */
  43.     public const SELECT = 0;
  44.     public const DELETE = 1;
  45.     public const UPDATE = 2;
  46.     public const INSERT = 3;
  48.     /*
  49.      * The builder states.
  50.      */
  51.     public const STATE_DIRTY = 0;
  52.     public const STATE_CLEAN = 1;
  54.     /*
  55.      * The default values of SQL parts collection
  56.      */
  57.     private const SQL_PARTS_DEFAULTS = [
  58.         'select' => [],
  59.         'distinct' => false,
  60.         'from' => [],
  61.         'join' => [],
  62.         'set' => [],
  63.         'where' => null,
  64.         'groupBy' => [],
  65.         'having' => null,
  66.         'orderBy' => [],
  67.         'values' => [],
  68.     ];
  70.     /**
  71.      * The DBAL Connection.
  72.      *
  73.      * @var Connection
  74.      */
  75.     private $connection;
  77.     /**
  78.      * The array of SQL parts collected.
  79.      *
  80.      * @var mixed[]
  81.      */
  82.     private $sqlParts = self::SQL_PARTS_DEFAULTS;
  84.     /**
  85.      * The complete SQL string for this query.
  86.      *
  87.      * @var string|null
  88.      */
  89.     private $sql;
  91.     /**
  92.      * The query parameters.
  93.      *
  94.      * @var array<int, mixed>|array<string, mixed>
  95.      */
  96.     private $params = [];
  98.     /**
  99.      * The parameter type map of this query.
  100.      *
  101.      * @var array<int, int|string|Type|null>|array<string, int|string|Type|null>
  102.      */
  103.     private $paramTypes = [];
  105.     /**
  106.      * The type of query this is. Can be select, update or delete.
  107.      *
  108.      * @var int
  109.      */
  110.     private $type = self::SELECT;
  112.     /**
  113.      * The state of the query object. Can be dirty or clean.
  114.      *
  115.      * @var int
  116.      */
  117.     private $state = self::STATE_CLEAN;
  119.     /**
  120.      * The index of the first result to retrieve.
  121.      *
  122.      * @var int
  123.      */
  124.     private $firstResult = 0;
  126.     /**
  127.      * The maximum number of results to retrieve or NULL to retrieve all results.
  128.      *
  129.      * @var int|null
  130.      */
  131.     private $maxResults;
  133.     /**
  134.      * The counter of bound parameters used with {@see bindValue).
  135.      *
  136.      * @var int
  137.      */
  138.     private $boundCounter = 0;
  140.     /**
  141.      * Initializes a new <tt>QueryBuilder</tt>.
  142.      *
  143.      * @param Connection $connection The DBAL Connection.
  144.      */
  145.     public function __construct(Connection $connection)
  146.     {
  147.         $this->connection = $connection;
  148.     }
  150.     /**
  151.      * Gets a string representation of this QueryBuilder which corresponds to
  152.      * the final SQL query being constructed.
  153.      *
  154.      * @return string The string representation of this QueryBuilder.
  155.      */
  156.     public function __toString()
  157.     {
  158.         return $this->getSQL();
  159.     }
  161.     /**
  162.      * Deep clone of all expression objects in the SQL parts.
  163.      *
  164.      * @return void
  165.      */
  166.     public function __clone()
  167.     {
  168.         foreach ($this->sqlParts as $part => $elements) {
  169.             if (\is_array($this->sqlParts[$part])) {
  170.                 foreach ($this->sqlParts[$part] as $idx => $element) {
  171.                     if (!\is_object($element)) {
  172.                         continue;
  173.                     }
  175.                     $this->sqlParts[$part][$idx] = clone $element;
  176.                 }
  177.             } elseif (\is_object($elements)) {
  178.                 $this->sqlParts[$part] = clone $elements;
  179.             }
  180.         }
  182.         foreach ($this->params as $name => $param) {
  183.             if (!\is_object($param)) {
  184.                 continue;
  185.             }
  187.             $this->params[$name] = clone $param;
  188.         }
  189.     }
  191.     /**
  192.      * Gets an ExpressionBuilder used for object-oriented construction of query expressions.
  193.      * This producer method is intended for convenient inline usage. Example:
  194.      *
  195.      * <code>
  196.      *     $qb = $conn->createQueryBuilder()
  197.      *         ->select('u')
  198.      *         ->from('users', 'u')
  199.      *         ->where($qb->expr()->eq('u.id', 1));
  200.      * </code>
  201.      *
  202.      * For more complex expression construction, consider storing the expression
  203.      * builder object in a local variable.
  204.      *
  205.      * @return ExpressionBuilder
  206.      */
  207.     public function expr()
  208.     {
  209.         return $this->connection->getExpressionBuilder();
  210.     }
  212.     /**
  213.      * Gets the type of the currently built query.
  214.      *
  215.      * @return int
  216.      */
  217.     public function getType()
  218.     {
  219.         return $this->type;
  220.     }
  222.     /**
  223.      * Gets the associated DBAL Connection for this query builder.
  224.      *
  225.      * @return Connection
  226.      */
  227.     public function getConnection()
  228.     {
  229.         return $this->connection;
  230.     }
  232.     /**
  233.      * Gets the state of this query builder instance.
  234.      *
  235.      * @return int Either QueryBuilder::STATE_DIRTY or QueryBuilder::STATE_CLEAN.
  236.      */
  237.     public function getState()
  238.     {
  239.         return $this->state;
  240.     }
  242.     /**
  243.      * Executes an SQL query (SELECT) and returns a Result.
  244.      *
  245.      * @throws Exception
  246.      */
  247.     public function executeQuery(): Result
  248.     {
  249.         return $this->connection->executeQuery(
  250.             $this->getSQL(),
  251.             $this->params,
  252.             $this->paramTypes
  253.         );
  254.     }
  256.     /**
  257.      * Executes an SQL statement and returns the number of affected rows.
  258.      *
  259.      * Should be used for INSERT, UPDATE and DELETE
  260.      *
  261.      * @throws Exception
  262.      *
  263.      * @return int The number of affected rows.
  264.      */
  265.     public function executeStatement(): int
  266.     {
  267.         return (int) $this->connection->executeStatement($this->getSQL(), $this->params, $this->paramTypes);
  268.     }
  270.     /**
  271.      * Executes this query using the bound parameters and their types.
  272.      *
  273.      * @throws Exception
  274.      *
  275.      * @return ForwardCompatibility\Result<mixed>|int|string
  276.      */
  277.     public function execute()
  278.     {
  279.         if ($this->type === self::SELECT) {
  280.             return ForwardCompatibility\Result::ensure(
  281.                 $this->connection->executeQuery($this->getSQL(), $this->params, $this->paramTypes)
  282.             );
  283.         }
  285.         return $this->connection->executeStatement($this->getSQL(), $this->params, $this->paramTypes);
  286.     }
  288.     /**
  289.      * Gets the complete SQL string formed by the current specifications of this QueryBuilder.
  290.      *
  291.      * <code>
  292.      *     $qb = $em->createQueryBuilder()
  293.      *         ->select('u')
  294.      *         ->from('User', 'u')
  295.      *     echo $qb->getSQL(); // SELECT u FROM User u
  296.      * </code>
  297.      *
  298.      * @return string The SQL query string.
  299.      */
  300.     public function getSQL()
  301.     {
  302.         if ($this->sql !== null && $this->state === self::STATE_CLEAN) {
  303.             return $this->sql;
  304.         }
  306.         switch ($this->type) {
  307.             case self::INSERT:
  308.                 $sql = $this->getSQLForInsert();
  310.                 break;
  312.             case self::DELETE:
  313.                 $sql = $this->getSQLForDelete();
  315.                 break;
  317.             case self::UPDATE:
  318.                 $sql = $this->getSQLForUpdate();
  320.                 break;
  322.             case self::SELECT:
  323.             default:
  324.                 $sql = $this->getSQLForSelect();
  326.                 break;
  327.         }
  329.         $this->state = self::STATE_CLEAN;
  330.         $this->sql = $sql;
  332.         return $sql;
  333.     }
  335.     /**
  336.      * Sets a query parameter for the query being constructed.
  337.      *
  338.      * <code>
  339.      *     $qb = $conn->createQueryBuilder()
  340.      *         ->select('u')
  341.      *         ->from('users', 'u')
  342.      *         ->where('u.id = :user_id')
  343.      *         ->setParameter(':user_id', 1);
  344.      * </code>
  345.      *
  346.      * @param int|string           $key   Parameter position or name
  347.      * @param mixed                $value Parameter value
  348.      * @param int|string|Type|null $type  Parameter type
  349.      *
  350.      * @return $this This QueryBuilder instance.
  351.      */
  352.     public function setParameter($key, $value, $type = null)
  353.     {
  354.         if ($type !== null) {
  355.             $this->paramTypes[$key] = $type;
  356.         }
  358.         $this->params[$key] = $value;
  360.         return $this;
  361.     }
  363.     /**
  364.      * Sets a collection of query parameters for the query being constructed.
  365.      *
  366.      * <code>
  367.      *     $qb = $conn->createQueryBuilder()
  368.      *         ->select('u')
  369.      *         ->from('users', 'u')
  370.      *         ->where('u.id = :user_id1 OR u.id = :user_id2')
  371.      *         ->setParameters(array(
  372.      *             ':user_id1' => 1,
  373.      *             ':user_id2' => 2
  374.      *         ));
  375.      * </code>
  376.      *
  377.      * @param array<int, mixed>|array<string, mixed>                               $params Parameters to set
  378.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  379.      *
  380.      * @return $this This QueryBuilder instance.
  381.      */
  382.     public function setParameters(array $params, array $types = [])
  383.     {
  384.         $this->paramTypes = $types;
  385.         $this->params = $params;
  387.         return $this;
  388.     }
  390.     /**
  391.      * Gets all defined query parameters for the query being constructed indexed by parameter index or name.
  392.      *
  393.      * @return array<int, mixed>|array<string, mixed> The currently defined query parameters
  394.      */
  395.     public function getParameters()
  396.     {
  397.         return $this->params;
  398.     }
  400.     /**
  401.      * Gets a (previously set) query parameter of the query being constructed.
  402.      *
  403.      * @param mixed $key The key (index or name) of the bound parameter.
  404.      *
  405.      * @return mixed The value of the bound parameter.
  406.      */
  407.     public function getParameter($key)
  408.     {
  409.         return $this->params[$key] ?? null;
  410.     }
  412.     /**
  413.      * Gets all defined query parameter types for the query being constructed indexed by parameter index or name.
  414.      *
  415.      * @return array<int, int|string|Type|null>|array<string, int|string|Type|null> The currently defined
  416.      *                                                                              query parameter types
  417.      */
  418.     public function getParameterTypes()
  419.     {
  420.         return $this->paramTypes;
  421.     }
  423.     /**
  424.      * Gets a (previously set) query parameter type of the query being constructed.
  425.      *
  426.      * @param int|string $key The key of the bound parameter type
  427.      *
  428.      * @return int|string|Type|null The value of the bound parameter type
  429.      */
  430.     public function getParameterType($key)
  431.     {
  432.         return $this->paramTypes[$key] ?? null;
  433.     }
  435.     /**
  436.      * Sets the position of the first result to retrieve (the "offset").
  437.      *
  438.      * @param int $firstResult The first result to return.
  439.      *
  440.      * @return $this This QueryBuilder instance.
  441.      */
  442.     public function setFirstResult($firstResult)
  443.     {
  444.         $this->state = self::STATE_DIRTY;
  445.         $this->firstResult = $firstResult;
  447.         return $this;
  448.     }
  450.     /**
  451.      * Gets the position of the first result the query object was set to retrieve (the "offset").
  452.      *
  453.      * @return int The position of the first result.
  454.      */
  455.     public function getFirstResult()
  456.     {
  457.         return $this->firstResult;
  458.     }
  460.     /**
  461.      * Sets the maximum number of results to retrieve (the "limit").
  462.      *
  463.      * @param int|null $maxResults The maximum number of results to retrieve or NULL to retrieve all results.
  464.      *
  465.      * @return $this This QueryBuilder instance.
  466.      */
  467.     public function setMaxResults($maxResults)
  468.     {
  469.         $this->state = self::STATE_DIRTY;
  470.         $this->maxResults = $maxResults;
  472.         return $this;
  473.     }
  475.     /**
  476.      * Gets the maximum number of results the query object was set to retrieve (the "limit").
  477.      * Returns NULL if all results will be returned.
  478.      *
  479.      * @return int|null The maximum number of results.
  480.      */
  481.     public function getMaxResults()
  482.     {
  483.         return $this->maxResults;
  484.     }
  486.     /**
  487.      * Either appends to or replaces a single, generic query part.
  488.      *
  489.      * The available parts are: 'select', 'from', 'set', 'where',
  490.      * 'groupBy', 'having' and 'orderBy'.
  491.      *
  492.      * @param string $sqlPartName
  493.      * @param mixed  $sqlPart
  494.      * @param bool   $append
  495.      *
  496.      * @return $this This QueryBuilder instance.
  497.      */
  498.     public function add($sqlPartName, $sqlPart, $append = false)
  499.     {
  500.         $isArray = \is_array($sqlPart);
  501.         $isMultiple = \is_array($this->sqlParts[$sqlPartName]);
  503.         if ($isMultiple && !$isArray) {
  504.             $sqlPart = [$sqlPart];
  505.         }
  507.         $this->state = self::STATE_DIRTY;
  509.         if ($append) {
  510.             if (
  511.                 $sqlPartName === 'orderBy'
  512.                 || $sqlPartName === 'groupBy'
  513.                 || $sqlPartName === 'select'
  514.                 || $sqlPartName === 'set'
  515.             ) {
  516.                 foreach ($sqlPart as $part) {
  517.                     $this->sqlParts[$sqlPartName][] = $part;
  518.                 }
  519.             } elseif ($isArray && \is_array($sqlPart[key($sqlPart)])) {
  520.                 $key = key($sqlPart);
  521.                 $this->sqlParts[$sqlPartName][$key][] = $sqlPart[$key];
  522.             } elseif ($isMultiple) {
  523.                 $this->sqlParts[$sqlPartName][] = $sqlPart;
  524.             } else {
  525.                 $this->sqlParts[$sqlPartName] = $sqlPart;
  526.             }
  528.             return $this;
  529.         }
  531.         $this->sqlParts[$sqlPartName] = $sqlPart;
  533.         return $this;
  534.     }
  536.     /**
  537.      * Specifies an item that is to be returned in the query result.
  538.      * Replaces any previously specified selections, if any.
  539.      *
  540.      * USING AN ARRAY ARGUMENT IS DEPRECATED. Pass each value as an individual argument.
  541.      *
  542.      * <code>
  543.      *     $qb = $conn->createQueryBuilder()
  544.      *         ->select('u.id', 'p.id')
  545.      *         ->from('users', 'u')
  546.      *         ->leftJoin('u', 'phonenumbers', 'p', 'u.id = p.user_id');
  547.      * </code>
  548.      *
  549.      * @param string|string[]|null $select The selection expression. USING AN ARRAY OR NULL IS DEPRECATED.
  550.      *                                     Pass each value as an individual argument.
  551.      *
  552.      * @return $this This QueryBuilder instance.
  553.      */
  554.     public function select($select = null/*, string ...$selects*/)
  555.     {
  556.         $this->type = self::SELECT;
  558.         if (empty($select)) {
  559.             return $this;
  560.         }
  562.         if (\is_array($select)) {
  563.             Deprecation::trigger(
  564.                 'doctrine/dbal',
  565.                 'https://github.com/doctrine/dbal/issues/3837',
  566.                 'Passing an array for the first argument to QueryBuilder::select is deprecated, '
  567.                 . 'pass each value as an individual variadic argument instead.'
  568.             );
  569.         }
  571.         $selects = \is_array($select) ? $select : \func_get_args();
  573.         return $this->add('select', $selects);
  574.     }
  576.     /**
  577.      * Adds DISTINCT to the query.
  578.      *
  579.      * <code>
  580.      *     $qb = $conn->createQueryBuilder()
  581.      *         ->select('u.id')
  582.      *         ->distinct()
  583.      *         ->from('users', 'u')
  584.      * </code>
  585.      *
  586.      * @return $this This QueryBuilder instance.
  587.      */
  588.     public function distinct(): self
  589.     {
  590.         $this->sqlParts['distinct'] = true;
  592.         return $this;
  593.     }
  595.     /**
  596.      * Adds an item that is to be returned in the query result.
  597.      *
  598.      * USING AN ARRAY ARGUMENT IS DEPRECATED. Pass each value as an individual argument.
  599.      *
  600.      * <code>
  601.      *     $qb = $conn->createQueryBuilder()
  602.      *         ->select('u.id')
  603.      *         ->addSelect('p.id')
  604.      *         ->from('users', 'u')
  605.      *         ->leftJoin('u', 'phonenumbers', 'u.id = p.user_id');
  606.      * </code>
  607.      *
  608.      * @param string|string[]|null $select The selection expression. USING AN ARRAY OR NULL IS DEPRECATED.
  609.      *                                     Pass each value as an individual argument.
  610.      *
  611.      * @return $this This QueryBuilder instance.
  612.      */
  613.     public function addSelect($select = null/*, string ...$selects*/)
  614.     {
  615.         $this->type = self::SELECT;
  617.         if (empty($select)) {
  618.             return $this;
  619.         }
  621.         if (\is_array($select)) {
  622.             Deprecation::trigger(
  623.                 'doctrine/dbal',
  624.                 'https://github.com/doctrine/dbal/issues/3837',
  625.                 'Passing an array for the first argument to QueryBuilder::addSelect is deprecated, '
  626.                 . 'pass each value as an individual variadic argument instead.'
  627.             );
  628.         }
  630.         $selects = \is_array($select) ? $select : \func_get_args();
  632.         return $this->add('select', $selects, true);
  633.     }
  635.     /**
  636.      * Turns the query being built into a bulk delete query that ranges over
  637.      * a certain table.
  638.      *
  639.      * <code>
  640.      *     $qb = $conn->createQueryBuilder()
  641.      *         ->delete('users', 'u')
  642.      *         ->where('u.id = :user_id')
  643.      *         ->setParameter(':user_id', 1);
  644.      * </code>
  645.      *
  646.      * @param string $delete The table whose rows are subject to the deletion.
  647.      * @param string $alias  The table alias used in the constructed query.
  648.      *
  649.      * @return $this This QueryBuilder instance.
  650.      */
  651.     public function delete($delete = null, $alias = null)
  652.     {
  653.         $this->type = self::DELETE;
  655.         if (!$delete) {
  656.             return $this;
  657.         }
  659.         return $this->add('from', [
  660.             'table' => $delete,
  661.             'alias' => $alias,
  662.         ]);
  663.     }
  665.     /**
  666.      * Turns the query being built into a bulk update query that ranges over
  667.      * a certain table
  668.      *
  669.      * <code>
  670.      *     $qb = $conn->createQueryBuilder()
  671.      *         ->update('counters', 'c')
  672.      *         ->set('c.value', 'c.value + 1')
  673.      *         ->where('c.id = ?');
  674.      * </code>
  675.      *
  676.      * @param string $update The table whose rows are subject to the update.
  677.      * @param string $alias  The table alias used in the constructed query.
  678.      *
  679.      * @return $this This QueryBuilder instance.
  680.      */
  681.     public function update($update = null, $alias = null)
  682.     {
  683.         $this->type = self::UPDATE;
  685.         if (!$update) {
  686.             return $this;
  687.         }
  689.         return $this->add('from', [
  690.             'table' => $update,
  691.             'alias' => $alias,
  692.         ]);
  693.     }
  695.     /**
  696.      * Turns the query being built into an insert query that inserts into
  697.      * a certain table
  698.      *
  699.      * <code>
  700.      *     $qb = $conn->createQueryBuilder()
  701.      *         ->insert('users')
  702.      *         ->values(
  703.      *             array(
  704.      *                 'name' => '?',
  705.      *                 'password' => '?'
  706.      *             )
  707.      *         );
  708.      * </code>
  709.      *
  710.      * @param string $insert The table into which the rows should be inserted.
  711.      *
  712.      * @return $this This QueryBuilder instance.
  713.      */
  714.     public function insert($insert = null)
  715.     {
  716.         $this->type = self::INSERT;
  718.         if (!$insert) {
  719.             return $this;
  720.         }
  722.         return $this->add('from', ['table' => $insert]);
  723.     }
  725.     /**
  726.      * Creates and adds a query root corresponding to the table identified by the
  727.      * given alias, forming a cartesian product with any existing query roots.
  728.      *
  729.      * <code>
  730.      *     $qb = $conn->createQueryBuilder()
  731.      *         ->select('u.id')
  732.      *         ->from('users', 'u')
  733.      * </code>
  734.      *
  735.      * @param string      $from  The table.
  736.      * @param string|null $alias The alias of the table.
  737.      *
  738.      * @return $this This QueryBuilder instance.
  739.      */
  740.     public function from($from, $alias = null)
  741.     {
  742.         return $this->add('from', [
  743.             'table' => $from,
  744.             'alias' => $alias,
  745.         ], true);
  746.     }
  748.     /**
  749.      * Creates and adds a join to the query.
  750.      *
  751.      * <code>
  752.      *     $qb = $conn->createQueryBuilder()
  753.      *         ->select('u.name')
  754.      *         ->from('users', 'u')
  755.      *         ->join('u', 'phonenumbers', 'p', 'p.is_primary = 1');
  756.      * </code>
  757.      *
  758.      * @param string $fromAlias The alias that points to a from clause.
  759.      * @param string $join      The table name to join.
  760.      * @param string $alias     The alias of the join table.
  761.      * @param string $condition The condition for the join.
  762.      *
  763.      * @return $this This QueryBuilder instance.
  764.      */
  765.     public function join($fromAlias, $join, $alias, $condition = null)
  766.     {
  767.         return $this->innerJoin($fromAlias, $join, $alias, $condition);
  768.     }
  770.     /**
  771.      * Creates and adds a join to the query.
  772.      *
  773.      * <code>
  774.      *     $qb = $conn->createQueryBuilder()
  775.      *         ->select('u.name')
  776.      *         ->from('users', 'u')
  777.      *         ->innerJoin('u', 'phonenumbers', 'p', 'p.is_primary = 1');
  778.      * </code>
  779.      *
  780.      * @param string $fromAlias The alias that points to a from clause.
  781.      * @param string $join      The table name to join.
  782.      * @param string $alias     The alias of the join table.
  783.      * @param string $condition The condition for the join.
  784.      *
  785.      * @return $this This QueryBuilder instance.
  786.      */
  787.     public function innerJoin($fromAlias, $join, $alias, $condition = null)
  788.     {
  789.         return $this->add('join', [
  790.             $fromAlias => [
  791.                 'joinType' => 'inner',
  792.                 'joinTable' => $join,
  793.                 'joinAlias' => $alias,
  794.                 'joinCondition' => $condition,
  795.             ],
  796.         ], true);
  797.     }
  799.     /**
  800.      * Creates and adds a left join to the query.
  801.      *
  802.      * <code>
  803.      *     $qb = $conn->createQueryBuilder()
  804.      *         ->select('u.name')
  805.      *         ->from('users', 'u')
  806.      *         ->leftJoin('u', 'phonenumbers', 'p', 'p.is_primary = 1');
  807.      * </code>
  808.      *
  809.      * @param string $fromAlias The alias that points to a from clause.
  810.      * @param string $join      The table name to join.
  811.      * @param string $alias     The alias of the join table.
  812.      * @param string $condition The condition for the join.
  813.      *
  814.      * @return $this This QueryBuilder instance.
  815.      */
  816.     public function leftJoin($fromAlias, $join, $alias, $condition = null)
  817.     {
  818.         return $this->add('join', [
  819.             $fromAlias => [
  820.                 'joinType' => 'left',
  821.                 'joinTable' => $join,
  822.                 'joinAlias' => $alias,
  823.                 'joinCondition' => $condition,
  824.             ],
  825.         ], true);
  826.     }
  828.     /**
  829.      * Creates and adds a right join to the query.
  830.      *
  831.      * <code>
  832.      *     $qb = $conn->createQueryBuilder()
  833.      *         ->select('u.name')
  834.      *         ->from('users', 'u')
  835.      *         ->rightJoin('u', 'phonenumbers', 'p', 'p.is_primary = 1');
  836.      * </code>
  837.      *
  838.      * @param string $fromAlias The alias that points to a from clause.
  839.      * @param string $join      The table name to join.
  840.      * @param string $alias     The alias of the join table.
  841.      * @param string $condition The condition for the join.
  842.      *
  843.      * @return $this This QueryBuilder instance.
  844.      */
  845.     public function rightJoin($fromAlias, $join, $alias, $condition = null)
  846.     {
  847.         return $this->add('join', [
  848.             $fromAlias => [
  849.                 'joinType' => 'right',
  850.                 'joinTable' => $join,
  851.                 'joinAlias' => $alias,
  852.                 'joinCondition' => $condition,
  853.             ],
  854.         ], true);
  855.     }
  857.     /**
  858.      * Sets a new value for a column in a bulk update query.
  859.      *
  860.      * <code>
  861.      *     $qb = $conn->createQueryBuilder()
  862.      *         ->update('counters', 'c')
  863.      *         ->set('c.value', 'c.value + 1')
  864.      *         ->where('c.id = ?');
  865.      * </code>
  866.      *
  867.      * @param string $key   The column to set.
  868.      * @param string $value The value, expression, placeholder, etc.
  869.      *
  870.      * @return $this This QueryBuilder instance.
  871.      */
  872.     public function set($key, $value)
  873.     {
  874.         return $this->add('set', $key . ' = ' . $value, true);
  875.     }
  877.     /**
  878.      * Specifies one or more restrictions to the query result.
  879.      * Replaces any previously specified restrictions, if any.
  880.      *
  881.      * <code>
  882.      *     $qb = $conn->createQueryBuilder()
  883.      *         ->select('c.value')
  884.      *         ->from('counters', 'c')
  885.      *         ->where('c.id = ?');
  886.      *
  887.      *     // You can optionally programatically build and/or expressions
  888.      *     $qb = $conn->createQueryBuilder();
  889.      *
  890.      *     $or = $qb->expr()->orx();
  891.      *     $or->add($qb->expr()->eq('c.id', 1));
  892.      *     $or->add($qb->expr()->eq('c.id', 2));
  893.      *
  894.      *     $qb->update('counters', 'c')
  895.      *         ->set('c.value', 'c.value + 1')
  896.      *         ->where($or);
  897.      * </code>
  898.      *
  899.      * @param mixed $predicates The restriction predicates.
  900.      *
  901.      * @return $this This QueryBuilder instance.
  902.      */
  903.     public function where($predicates)
  904.     {
  905.         if (!(\func_num_args() === 1 && $predicates instanceof CompositeExpression)) {
  906.             $predicates = CompositeExpression::and(...\func_get_args());
  907.         }
  909.         return $this->add('where', $predicates);
  910.     }
  912.     /**
  913.      * Adds one or more restrictions to the query results, forming a logical
  914.      * conjunction with any previously specified restrictions.
  915.      *
  916.      * <code>
  917.      *     $qb = $conn->createQueryBuilder()
  918.      *         ->select('u')
  919.      *         ->from('users', 'u')
  920.      *         ->where('u.username LIKE ?')
  921.      *         ->andWhere('u.is_active = 1');
  922.      * </code>
  923.      *
  924.      * @see where()
  925.      *
  926.      * @param mixed $where The query restrictions.
  927.      *
  928.      * @return $this This QueryBuilder instance.
  929.      */
  930.     public function andWhere($where)
  931.     {
  932.         $args = \func_get_args();
  933.         $args = array_filter($args); // https://github.com/doctrine/dbal/issues/4282
  934.         $where = $this->getQueryPart('where');
  936.         if ($where instanceof CompositeExpression && $where->getType() === CompositeExpression::TYPE_AND) {
  937.             if (\count($args) > 0) {
  938.                 $where = $where->with(...$args);
  939.             }
  940.         } else {
  941.             array_unshift($args, $where);
  942.             $where = CompositeExpression::and(...$args);
  943.         }
  945.         return $this->add('where', $where, true);
  946.     }
  948.     /**
  949.      * Adds one or more restrictions to the query results, forming a logical
  950.      * disjunction with any previously specified restrictions.
  951.      *
  952.      * <code>
  953.      *     $qb = $em->createQueryBuilder()
  954.      *         ->select('u.name')
  955.      *         ->from('users', 'u')
  956.      *         ->where('u.id = 1')
  957.      *         ->orWhere('u.id = 2');
  958.      * </code>
  959.      *
  960.      * @see where()
  961.      *
  962.      * @param mixed $where The WHERE statement.
  963.      *
  964.      * @return $this This QueryBuilder instance.
  965.      */
  966.     public function orWhere($where)
  967.     {
  968.         $args = \func_get_args();
  969.         $args = array_filter($args); // https://github.com/doctrine/dbal/issues/4282
  970.         $where = $this->getQueryPart('where');
  972.         if ($where instanceof CompositeExpression && $where->getType() === CompositeExpression::TYPE_OR) {
  973.             if (\count($args) > 0) {
  974.                 $where = $where->with(...$args);
  975.             }
  976.         } else {
  977.             array_unshift($args, $where);
  978.             $where = CompositeExpression::or(...$args);
  979.         }
  981.         return $this->add('where', $where, true);
  982.     }
  984.     /**
  985.      * Specifies a grouping over the results of the query.
  986.      * Replaces any previously specified groupings, if any.
  987.      *
  988.      * USING AN ARRAY ARGUMENT IS DEPRECATED. Pass each value as an individual argument.
  989.      *
  990.      * <code>
  991.      *     $qb = $conn->createQueryBuilder()
  992.      *         ->select('u.name')
  993.      *         ->from('users', 'u')
  994.      *         ->groupBy('u.id');
  995.      * </code>
  996.      *
  997.      * @param string|string[] $groupBy The grouping expression. USING AN ARRAY IS DEPRECATED.
  998.      *                                 Pass each value as an individual argument.
  999.      *
  1000.      * @return $this This QueryBuilder instance.
  1001.      */
  1002.     public function groupBy($groupBy/*, string ...$groupBys*/)
  1003.     {
  1004.         if (empty($groupBy)) {
  1005.             return $this;
  1006.         }
  1008.         if (\is_array($groupBy)) {
  1009.             Deprecation::trigger(
  1010.                 'doctrine/dbal',
  1011.                 'https://github.com/doctrine/dbal/issues/3837',
  1012.                 'Passing an array for the first argument to QueryBuilder::groupBy is deprecated, '
  1013.                 . 'pass each value as an individual variadic argument instead.'
  1014.             );
  1015.         }
  1017.         $groupBy = \is_array($groupBy) ? $groupBy : \func_get_args();
  1019.         return $this->add('groupBy', $groupBy, false);
  1020.     }
  1022.     /**
  1023.      * Adds a grouping expression to the query.
  1024.      *
  1025.      * USING AN ARRAY ARGUMENT IS DEPRECATED. Pass each value as an individual argument.
  1026.      *
  1027.      * <code>
  1028.      *     $qb = $conn->createQueryBuilder()
  1029.      *         ->select('u.name')
  1030.      *         ->from('users', 'u')
  1031.      *         ->groupBy('u.lastLogin')
  1032.      *         ->addGroupBy('u.createdAt');
  1033.      * </code>
  1034.      *
  1035.      * @param string|string[] $groupBy The grouping expression. USING AN ARRAY IS DEPRECATED.
  1036.      *                                 Pass each value as an individual argument.
  1037.      *
  1038.      * @return $this This QueryBuilder instance.
  1039.      */
  1040.     public function addGroupBy($groupBy/*, string ...$groupBys*/)
  1041.     {
  1042.         if (empty($groupBy)) {
  1043.             return $this;
  1044.         }
  1046.         if (\is_array($groupBy)) {
  1047.             Deprecation::trigger(
  1048.                 'doctrine/dbal',
  1049.                 'https://github.com/doctrine/dbal/issues/3837',
  1050.                 'Passing an array for the first argument to QueryBuilder::addGroupBy is deprecated, '
  1051.                 . 'pass each value as an individual variadic argument instead.'
  1052.             );
  1053.         }
  1055.         $groupBy = \is_array($groupBy) ? $groupBy : \func_get_args();
  1057.         return $this->add('groupBy', $groupBy, true);
  1058.     }
  1060.     /**
  1061.      * Sets a value for a column in an insert query.
  1062.      *
  1063.      * <code>
  1064.      *     $qb = $conn->createQueryBuilder()
  1065.      *         ->insert('users')
  1066.      *         ->values(
  1067.      *             array(
  1068.      *                 'name' => '?'
  1069.      *             )
  1070.      *         )
  1071.      *         ->setValue('password', '?');
  1072.      * </code>
  1073.      *
  1074.      * @param string $column The column into which the value should be inserted.
  1075.      * @param string $value  The value that should be inserted into the column.
  1076.      *
  1077.      * @return $this This QueryBuilder instance.
  1078.      */
  1079.     public function setValue($column, $value)
  1080.     {
  1081.         $this->sqlParts['values'][$column] = $value;
  1083.         return $this;
  1084.     }
  1086.     /**
  1087.      * Specifies values for an insert query indexed by column names.
  1088.      * Replaces any previous values, if any.
  1089.      *
  1090.      * <code>
  1091.      *     $qb = $conn->createQueryBuilder()
  1092.      *         ->insert('users')
  1093.      *         ->values(
  1094.      *             array(
  1095.      *                 'name' => '?',
  1096.      *                 'password' => '?'
  1097.      *             )
  1098.      *         );
  1099.      * </code>
  1100.      *
  1101.      * @param mixed[] $values The values to specify for the insert query indexed by column names.
  1102.      *
  1103.      * @return $this This QueryBuilder instance.
  1104.      */
  1105.     public function values(array $values)
  1106.     {
  1107.         return $this->add('values', $values);
  1108.     }
  1110.     /**
  1111.      * Specifies a restriction over the groups of the query.
  1112.      * Replaces any previous having restrictions, if any.
  1113.      *
  1114.      * @param mixed $having The restriction over the groups.
  1115.      *
  1116.      * @return $this This QueryBuilder instance.
  1117.      */
  1118.     public function having($having)
  1119.     {
  1120.         if (!(\func_num_args() === 1 && $having instanceof CompositeExpression)) {
  1121.             $having = CompositeExpression::and(...\func_get_args());
  1122.         }
  1124.         return $this->add('having', $having);
  1125.     }
  1127.     /**
  1128.      * Adds a restriction over the groups of the query, forming a logical
  1129.      * conjunction with any existing having restrictions.
  1130.      *
  1131.      * @param mixed $having The restriction to append.
  1132.      *
  1133.      * @return $this This QueryBuilder instance.
  1134.      */
  1135.     public function andHaving($having)
  1136.     {
  1137.         $args = \func_get_args();
  1138.         $args = array_filter($args); // https://github.com/doctrine/dbal/issues/4282
  1139.         $having = $this->getQueryPart('having');
  1141.         if ($having instanceof CompositeExpression && $having->getType() === CompositeExpression::TYPE_AND) {
  1142.             $having = $having->with(...$args);
  1143.         } else {
  1144.             array_unshift($args, $having);
  1145.             $having = CompositeExpression::and(...$args);
  1146.         }
  1148.         return $this->add('having', $having);
  1149.     }
  1151.     /**
  1152.      * Adds a restriction over the groups of the query, forming a logical
  1153.      * disjunction with any existing having restrictions.
  1154.      *
  1155.      * @param mixed $having The restriction to add.
  1156.      *
  1157.      * @return $this This QueryBuilder instance.
  1158.      */
  1159.     public function orHaving($having)
  1160.     {
  1161.         $args = \func_get_args();
  1162.         $args = array_filter($args); // https://github.com/doctrine/dbal/issues/4282
  1163.         $having = $this->getQueryPart('having');
  1165.         if ($having instanceof CompositeExpression && $having->getType() === CompositeExpression::TYPE_OR) {
  1166.             $having = $having->with(...$args);
  1167.         } else {
  1168.             array_unshift($args, $having);
  1169.             $having = CompositeExpression::or(...$args);
  1170.         }
  1172.         return $this->add('having', $having);
  1173.     }
  1175.     /**
  1176.      * Specifies an ordering for the query results.
  1177.      * Replaces any previously specified orderings, if any.
  1178.      *
  1179.      * @param string $sort  The ordering expression.
  1180.      * @param string $order The ordering direction.
  1181.      *
  1182.      * @return $this This QueryBuilder instance.
  1183.      */
  1184.     public function orderBy($sort, $order = null)
  1185.     {
  1186.         return $this->add('orderBy', $sort . ' ' . (!$order ? 'ASC' : $order), false);
  1187.     }
  1189.     /**
  1190.      * Adds an ordering to the query results.
  1191.      *
  1192.      * @param string $sort  The ordering expression.
  1193.      * @param string $order The ordering direction.
  1194.      *
  1195.      * @return $this This QueryBuilder instance.
  1196.      */
  1197.     public function addOrderBy($sort, $order = null)
  1198.     {
  1199.         return $this->add('orderBy', $sort . ' ' . (!$order ? 'ASC' : $order), true);
  1200.     }
  1202.     /**
  1203.      * Gets a query part by its name.
  1204.      *
  1205.      * @param string $queryPartName
  1206.      *
  1207.      * @return mixed
  1208.      */
  1209.     public function getQueryPart($queryPartName)
  1210.     {
  1211.         return $this->sqlParts[$queryPartName];
  1212.     }
  1214.     /**
  1215.      * Gets all query parts.
  1216.      *
  1217.      * @return mixed[]
  1218.      */
  1219.     public function getQueryParts()
  1220.     {
  1221.         return $this->sqlParts;
  1222.     }
  1224.     /**
  1225.      * Resets SQL parts.
  1226.      *
  1227.      * @param string[]|null $queryPartNames
  1228.      *
  1229.      * @return $this This QueryBuilder instance.
  1230.      */
  1231.     public function resetQueryParts($queryPartNames = null)
  1232.     {
  1233.         if ($queryPartNames === null) {
  1234.             $queryPartNames = array_keys($this->sqlParts);
  1235.         }
  1237.         foreach ($queryPartNames as $queryPartName) {
  1238.             $this->resetQueryPart($queryPartName);
  1239.         }
  1241.         return $this;
  1242.     }
  1244.     /**
  1245.      * Resets a single SQL part.
  1246.      *
  1247.      * @param string $queryPartName
  1248.      *
  1249.      * @return $this This QueryBuilder instance.
  1250.      */
  1251.     public function resetQueryPart($queryPartName)
  1252.     {
  1253.         $this->sqlParts[$queryPartName] = self::SQL_PARTS_DEFAULTS[$queryPartName];
  1255.         $this->state = self::STATE_DIRTY;
  1257.         return $this;
  1258.     }
  1260.     /**
  1261.      * Creates a new named parameter and bind the value $value to it.
  1262.      *
  1263.      * This method provides a shortcut for PDOStatement::bindValue
  1264.      * when using prepared statements.
  1265.      *
  1266.      * The parameter $value specifies the value that you want to bind. If
  1267.      * $placeholder is not provided bindValue() will automatically create a
  1268.      * placeholder for you. An automatic placeholder will be of the name
  1269.      * ':dcValue1', ':dcValue2' etc.
  1270.      *
  1271.      * For more information see {@link http://php.net/pdostatement-bindparam}
  1272.      *
  1273.      * Example:
  1274.      * <code>
  1275.      * $value = 2;
  1276.      * $q->eq( 'id', $q->bindValue( $value ) );
  1277.      * $stmt = $q->executeQuery(); // executed with 'id = 2'
  1278.      * </code>
  1279.      *
  1280.      * @see http://www.zetacomponents.org
  1281.      *
  1282.      * @param mixed                $value
  1283.      * @param int|string|Type|null $type
  1284.      * @param string               $placeHolder The name to bind with. The string must start with a colon ':'.
  1285.      *
  1286.      * @return string the placeholder name used.
  1287.      */
  1288.     public function createNamedParameter($value, $type = ParameterType::STRING, $placeHolder = null)
  1289.     {
  1290.         if ($placeHolder === null) {
  1291.             ++$this->boundCounter;
  1292.             $placeHolder = ':dcValue' . $this->boundCounter;
  1293.         }
  1295.         $this->setParameter(substr($placeHolder, 1), $value, $type);
  1297.         return $placeHolder;
  1298.     }
  1300.     /**
  1301.      * Creates a new positional parameter and bind the given value to it.
  1302.      *
  1303.      * Attention: If you are using positional parameters with the query builder you have
  1304.      * to be very careful to bind all parameters in the order they appear in the SQL
  1305.      * statement , otherwise they get bound in the wrong order which can lead to serious
  1306.      * bugs in your code.
  1307.      *
  1308.      * Example:
  1309.      * <code>
  1310.      *  $qb = $conn->createQueryBuilder();
  1311.      *  $qb->select('u.*')
  1312.      *     ->from('users', 'u')
  1313.      *     ->where('u.username = ' . $qb->createPositionalParameter('Foo', ParameterType::STRING))
  1314.      *     ->orWhere('u.username = ' . $qb->createPositionalParameter('Bar', ParameterType::STRING))
  1315.      * </code>
  1316.      *
  1317.      * @param mixed                $value
  1318.      * @param int|string|Type|null $type
  1319.      *
  1320.      * @return string
  1321.      */
  1322.     public function createPositionalParameter($value, $type = ParameterType::STRING)
  1323.     {
  1324.         ++$this->boundCounter;
  1325.         $this->setParameter($this->boundCounter, $value, $type);
  1327.         return '?';
  1328.     }
  1330.     /**
  1331.      * @throws QueryException
  1332.      *
  1333.      * @return string
  1334.      */
  1335.     private function getSQLForSelect()
  1336.     {
  1337.         $query = 'SELECT ' . ($this->sqlParts['distinct'] ? 'DISTINCT ' : '')
  1338.             . implode(', ', $this->sqlParts['select']);
  1340.         $query .= ($this->sqlParts['from'] ? ' FROM ' . implode(', ', $this->getFromClauses()) : '')
  1341.             . ($this->sqlParts['where'] !== null ? ' WHERE ' . ((string) $this->sqlParts['where']) : '')
  1342.             . ($this->sqlParts['groupBy'] ? ' GROUP BY ' . implode(', ', $this->sqlParts['groupBy']) : '')
  1343.             . ($this->sqlParts['having'] !== null ? ' HAVING ' . ((string) $this->sqlParts['having']) : '')
  1344.             . ($this->sqlParts['orderBy'] ? ' ORDER BY ' . implode(', ', $this->sqlParts['orderBy']) : '');
  1346.         if ($this->isLimitQuery()) {
  1347.             return $this->connection->getDatabasePlatform()->modifyLimitQuery(
  1348.                 $query,
  1349.                 $this->maxResults,
  1350.                 $this->firstResult
  1351.             );
  1352.         }
  1354.         return $query;
  1355.     }
  1357.     /**
  1358.      * @return string[]
  1359.      */
  1360.     private function getFromClauses()
  1361.     {
  1362.         $fromClauses = [];
  1363.         $knownAliases = [];
  1365.         // Loop through all FROM clauses
  1366.         foreach ($this->sqlParts['from'] as $from) {
  1367.             if ($from['alias'] === null) {
  1368.                 $tableSql = $from['table'];
  1369.                 $tableReference = $from['table'];
  1370.             } else {
  1371.                 $tableSql = $from['table'] . ' ' . $from['alias'];
  1372.                 $tableReference = $from['alias'];
  1373.             }
  1375.             $knownAliases[$tableReference] = true;
  1377.             $fromClauses[$tableReference] = $tableSql . $this->getSQLForJoins($tableReference, $knownAliases);
  1378.         }
  1380.         $this->verifyAllAliasesAreKnown($knownAliases);
  1382.         return $fromClauses;
  1383.     }
  1385.     /**
  1386.      * @param array<string,true> $knownAliases
  1387.      *
  1388.      * @throws QueryException
  1389.      */
  1390.     private function verifyAllAliasesAreKnown(array $knownAliases): void
  1391.     {
  1392.         foreach ($this->sqlParts['join'] as $fromAlias => $joins) {
  1393.             if (!isset($knownAliases[$fromAlias])) {
  1394.                 throw QueryException::unknownAlias($fromAlias, array_keys($knownAliases));
  1395.             }
  1396.         }
  1397.     }
  1399.     /**
  1400.      * @return bool
  1401.      */
  1402.     private function isLimitQuery()
  1403.     {
  1404.         return $this->maxResults !== null || $this->firstResult !== 0;
  1405.     }
  1407.     /**
  1408.      * Converts this instance into an INSERT string in SQL.
  1409.      *
  1410.      * @return string
  1411.      */
  1412.     private function getSQLForInsert()
  1413.     {
  1414.         return 'INSERT INTO ' . $this->sqlParts['from']['table']
  1415.             . ' (' . implode(', ', array_keys($this->sqlParts['values'])) . ')'
  1416.             . ' VALUES(' . implode(', ', $this->sqlParts['values']) . ')';
  1417.     }
  1419.     /**
  1420.      * Converts this instance into an UPDATE string in SQL.
  1421.      *
  1422.      * @return string
  1423.      */
  1424.     private function getSQLForUpdate()
  1425.     {
  1426.         $table = $this->sqlParts['from']['table']
  1427.             . ($this->sqlParts['from']['alias'] ? ' ' . $this->sqlParts['from']['alias'] : '');
  1429.         return 'UPDATE ' . $table
  1430.             . ' SET ' . implode(', ', $this->sqlParts['set'])
  1431.             . ($this->sqlParts['where'] !== null ? ' WHERE ' . ((string) $this->sqlParts['where']) : '');
  1432.     }
  1434.     /**
  1435.      * Converts this instance into a DELETE string in SQL.
  1436.      *
  1437.      * @return string
  1438.      */
  1439.     private function getSQLForDelete()
  1440.     {
  1441.         $table = $this->sqlParts['from']['table']
  1442.             . ($this->sqlParts['from']['alias'] ? ' ' . $this->sqlParts['from']['alias'] : '');
  1444.         return 'DELETE FROM ' . $table
  1445.             . ($this->sqlParts['where'] !== null ? ' WHERE ' . ((string) $this->sqlParts['where']) : '');
  1446.     }
  1448.     /**
  1449.      * @param string             $fromAlias
  1450.      * @param array<string,true> $knownAliases
  1451.      *
  1452.      * @throws QueryException
  1453.      *
  1454.      * @return string
  1455.      */
  1456.     private function getSQLForJoins($fromAlias, array &$knownAliases)
  1457.     {
  1458.         $sql = '';
  1460.         if (isset($this->sqlParts['join'][$fromAlias])) {
  1461.             foreach ($this->sqlParts['join'][$fromAlias] as $join) {
  1462.                 if (\array_key_exists($join['joinAlias'], $knownAliases)) {
  1463.                     /** @var array<string> $keys */
  1464.                     $keys = array_keys($knownAliases);
  1466.                     throw QueryException::nonUniqueAlias($join['joinAlias'], $keys);
  1467.                 }
  1469.                 $sql .= ' ' . strtoupper($join['joinType'])
  1470.                     . ' JOIN ' . $join['joinTable'] . ' ' . $join['joinAlias'];
  1471.                 if ($join['joinCondition'] !== null) {
  1472.                     $sql .= ' ON ' . $join['joinCondition'];
  1473.                 }
  1475.                 $knownAliases[$join['joinAlias']] = true;
  1476.             }
  1478.             foreach ($this->sqlParts['join'][$fromAlias] as $join) {
  1479.                 $sql .= $this->getSQLForJoins($join['joinAlias'], $knownAliases);
  1480.             }
  1481.         }
  1483.         return $sql;
  1484.     }
  1485. }