Merge pull request #3841 from morozov/issues/3825-NEXT

Enforced argument and return types in QueryBuilder and ExpressionBuilder

lib/Doctrine/DBAL/Query/Expression/ExpressionBuilder.php

@@ -72,11 +72,11 @@ class ExpressionBuilder
     /**
      * Creates a comparison expression.
      *
-     * @param mixed  $x        The left expression.
-     * @param string $operator One of the ExpressionBuilder::* constants.
-     * @param mixed  $y        The right expression.
+     * @param string $x        The left expression.
+     * @param string $operator The comparison operator.
+     * @param string $y        The right expression.
      */
-    public function comparison($x, string $operator, $y) : string
+    public function comparison(string $x, string $operator, string $y) : string
     {
         return $x . ' ' . $operator . ' ' . $y;
     }
@@ -91,10 +91,10 @@ class ExpressionBuilder
      *     // u.id = ?
      *     $expr->eq('u.id', '?');
      *
-     * @param mixed $x The left expression.
-     * @param mixed $y The right expression.
+     * @param string $x The left expression.
+     * @param string $y The right expression.
      */
-    public function eq($x, $y) : string
+    public function eq(string $x, string $y) : string
     {
         return $this->comparison($x, self::EQ, $y);
     }
@@ -108,10 +108,10 @@ class ExpressionBuilder
      *     // u.id <> 1
      *     $q->where($q->expr()->neq('u.id', '1'));
      *
-     * @param mixed $x The left expression.
-     * @param mixed $y The right expression.
+     * @param string $x The left expression.
+     * @param string $y The right expression.
      */
-    public function neq($x, $y) : string
+    public function neq(string $x, string $y) : string
     {
         return $this->comparison($x, self::NEQ, $y);
     }
@@ -125,10 +125,10 @@ class ExpressionBuilder
      *     // u.id < ?
      *     $q->where($q->expr()->lt('u.id', '?'));
      *
-     * @param mixed $x The left expression.
-     * @param mixed $y The right expression.
+     * @param string $x The left expression.
+     * @param string $y The right expression.
      */
-    public function lt($x, $y) : string
+    public function lt(string $x, string $y) : string
     {
         return $this->comparison($x, self::LT, $y);
     }
@@ -142,10 +142,10 @@ class ExpressionBuilder
      *     // u.id <= ?
      *     $q->where($q->expr()->lte('u.id', '?'));
      *
-     * @param mixed $x The left expression.
-     * @param mixed $y The right expression.
+     * @param string $x The left expression.
+     * @param string $y The right expression.
      */
-    public function lte($x, $y) : string
+    public function lte(string $x, string $y) : string
     {
         return $this->comparison($x, self::LTE, $y);
     }
@@ -159,10 +159,10 @@ class ExpressionBuilder
      *     // u.id > ?
      *     $q->where($q->expr()->gt('u.id', '?'));
      *
-     * @param mixed $x The left expression.
-     * @param mixed $y The right expression.
+     * @param string $x The left expression.
+     * @param string $y The right expression.
      */
-    public function gt($x, $y) : string
+    public function gt(string $x, string $y) : string
     {
         return $this->comparison($x, self::GT, $y);
     }
@@ -176,10 +176,10 @@ class ExpressionBuilder
      *     // u.id >= ?
      *     $q->where($q->expr()->gte('u.id', '?'));
      *
-     * @param mixed $x The left expression.
-     * @param mixed $y The right expression.
+     * @param string $x The left expression.
+     * @param string $y The right expression.
      */
-    public function gte($x, $y) : string
+    public function gte(string $x, string $y) : string
     {
         return $this->comparison($x, self::GTE, $y);
     }
@@ -207,24 +207,24 @@ class ExpressionBuilder
     /**
      * Creates a LIKE comparison expression.
      *
-     * @param string $x Field in string format to be inspected by LIKE() comparison.
-     * @param mixed  $y Argument to be used in LIKE() comparison.
+     * @param string $expression The expression to be inspected by the LIKE comparison
+     * @param string $pattern    The pattern to compare against
      */
-    public function like(string $x, $y, ?string $escapeChar = null) : string
+    public function like(string $expression, string $pattern, ?string $escapeChar = null) : string
     {
-        return $this->comparison($x, 'LIKE', $y) .
+        return $this->comparison($expression, 'LIKE', $pattern) .
             ($escapeChar !== null ? sprintf(' ESCAPE %s', $escapeChar) : '');
     }
 
     /**
      * Creates a NOT LIKE comparison expression
      *
-     * @param string $x Field in string format to be inspected by NOT LIKE() comparison.
-     * @param mixed  $y Argument to be used in NOT LIKE() comparison.
+     * @param string $expression The expression to be inspected by the NOT LIKE comparison
+     * @param string $pattern    The pattern to compare against
      */
-    public function notLike(string $x, $y, ?string $escapeChar = null) : string
+    public function notLike(string $expression, string $pattern, ?string $escapeChar = null) : string
     {
-        return $this->comparison($x, 'NOT LIKE', $y) .
+        return $this->comparison($expression, 'NOT LIKE', $pattern) .
             ($escapeChar !== null ? sprintf(' ESCAPE %s', $escapeChar) : '');
     }
 

lib/Doctrine/DBAL/Query/QueryBuilder.php

@@ -596,7 +596,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function from(string $from, ?string $alias = null)
+    public function from(string $from, ?string $alias = null) : self
     {
         return $this->add('from', new From($from, $alias), true);
     }
@@ -618,7 +618,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function join(string $fromAlias, string $join, string $alias, ?string $condition = null)
+    public function join(string $fromAlias, string $join, string $alias, ?string $condition = null) : self
     {
         return $this->innerJoin($fromAlias, $join, $alias, $condition);
     }
@@ -640,7 +640,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function innerJoin(string $fromAlias, string $join, string $alias, ?string $condition = null)
+    public function innerJoin(string $fromAlias, string $join, string $alias, ?string $condition = null) : self
     {
         return $this->add('join', [
             $fromAlias => Join::inner($join, $alias, $condition),
@@ -664,7 +664,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function leftJoin(string $fromAlias, string $join, string $alias, ?string $condition = null)
+    public function leftJoin(string $fromAlias, string $join, string $alias, ?string $condition = null) : self
     {
         return $this->add('join', [
             $fromAlias => Join::left($join, $alias, $condition),
@@ -688,7 +688,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function rightJoin(string $fromAlias, string $join, string $alias, ?string $condition = null)
+    public function rightJoin(string $fromAlias, string $join, string $alias, ?string $condition = null) : self
     {
         return $this->add('join', [
             $fromAlias => Join::right($join, $alias, $condition),
@@ -710,7 +710,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function set(string $key, string $value)
+    public function set(string $key, string $value) : self
     {
         return $this->add('set', $key . ' = ' . $value, true);
     }
@@ -742,7 +742,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function where($predicate, ...$predicates)
+    public function where($predicate, ...$predicates) : self
     {
         return $this->setPredicates('where', $predicate, ...$predicates);
     }
@@ -766,7 +766,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function andWhere($predicate, ...$predicates)
+    public function andWhere($predicate, ...$predicates) : self
     {
         return $this->appendPredicates('where', CompositeExpression::TYPE_AND, $predicate, ...$predicates);
     }
@@ -790,7 +790,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function orWhere($predicate, ...$predicates)
+    public function orWhere($predicate, ...$predicates) : self
     {
         return $this->appendPredicates('where', CompositeExpression::TYPE_OR, $predicate, ...$predicates);
     }
@@ -882,7 +882,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function values(array $values)
+    public function values(array $values) : self
     {
         return $this->add('values', $values);
     }
@@ -896,7 +896,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function having($predicate, ...$predicates)
+    public function having($predicate, ...$predicates) : self
     {
         return $this->setPredicates('having', $predicate, ...$predicates);
     }
@@ -910,7 +910,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function andHaving($predicate, ...$predicates)
+    public function andHaving($predicate, ...$predicates) : self
     {
         return $this->appendPredicates('having', CompositeExpression::TYPE_AND, $predicate, ...$predicates);
     }
@@ -924,7 +924,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function orHaving($predicate, ...$predicates)
+    public function orHaving($predicate, ...$predicates) : self
     {
         return $this->appendPredicates('having', CompositeExpression::TYPE_OR, $predicate, ...$predicates);
     }
@@ -983,7 +983,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function orderBy(string $sort, ?string $order = null)
+    public function orderBy(string $sort, ?string $order = null) : self
     {
         return $this->add('orderBy', $sort . ' ' . (! $order ? 'ASC' : $order), false);
     }
@@ -996,7 +996,7 @@ class QueryBuilder
      *
      * @return $this This QueryBuilder instance.
      */
-    public function addOrderBy(string $sort, ?string $order = null)
+    public function addOrderBy(string $sort, ?string $order = null) : self
     {
         return $this->add('orderBy', $sort . ' ' . (! $order ? 'ASC' : $order), true);
     }