updated-packages

vendor/doctrine/dbal/lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php

@@ -3,6 +3,10 @@
 namespace Doctrine\DBAL\Query\Expression;
 
 use Countable;
+use Doctrine\Deprecations\Deprecation;
+use ReturnTypeWillChange;
+
+use function array_merge;
 use function count;
 use function implode;
 
@@ -36,6 +40,8 @@ class CompositeExpression implements Countable
     private $parts = [];
 
     /**
+     * @internal Use the and() / or() factory methods.
+     *
      * @param string          $type  Instance type of composite expression.
      * @param self[]|string[] $parts Composition of expressions to be joined on composite expression.
      */
@@ -44,17 +50,49 @@ class CompositeExpression implements Countable
         $this->type = $type;
 
         $this->addMultiple($parts);
+
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/3864',
+            'Do not use CompositeExpression constructor directly, use static and() and or() factory methods.'
+        );
+    }
+
+    /**
+     * @param self|string $part
+     * @param self|string ...$parts
+     */
+    public static function and($part, ...$parts): self
+    {
+        return new self(self::TYPE_AND, array_merge([$part], $parts));
+    }
+
+    /**
+     * @param self|string $part
+     * @param self|string ...$parts
+     */
+    public static function or($part, ...$parts): self
+    {
+        return new self(self::TYPE_OR, array_merge([$part], $parts));
     }
 
     /**
      * Adds multiple parts to composite expression.
      *
+     * @deprecated This class will be made immutable. Use with() instead.
+     *
      * @param self[]|string[] $parts
      *
-     * @return \Doctrine\DBAL\Query\Expression\CompositeExpression
+     * @return CompositeExpression
      */
     public function addMultiple(array $parts = [])
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/issues/3844',
+            'CompositeExpression::addMultiple() is deprecated, use CompositeExpression::with() instead.'
+        );
+
         foreach ($parts as $part) {
             $this->add($part);
         }
@@ -65,12 +103,20 @@ class CompositeExpression implements Countable
     /**
      * Adds an expression to composite expression.
      *
+     * @deprecated This class will be made immutable. Use with() instead.
+     *
      * @param mixed $part
      *
-     * @return \Doctrine\DBAL\Query\Expression\CompositeExpression
+     * @return CompositeExpression
      */
     public function add($part)
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/issues/3844',
+            'CompositeExpression::add() is deprecated, use CompositeExpression::with() instead.'
+        );
+
         if (empty($part)) {
             return $this;
         }
@@ -84,11 +130,31 @@ class CompositeExpression implements Countable
         return $this;
     }
 
+    /**
+     * Returns a new CompositeExpression with the given parts added.
+     *
+     * @param self|string $part
+     * @param self|string ...$parts
+     */
+    public function with($part, ...$parts): self
+    {
+        $that = clone $this;
+
+        $that->parts[] = $part;
+
+        foreach ($parts as $part) {
+            $that->parts[] = $part;
+        }
+
+        return $that;
+    }
+
     /**
      * Retrieves the amount of expressions on composite expression.
      *
      * @return int
      */
+    #[ReturnTypeWillChange]
     public function count()
     {
         return count($this->parts);

vendor/doctrine/dbal/lib/Doctrine/DBAL/Query/Expression/ExpressionBuilder.php

@@ -3,6 +3,8 @@
 namespace Doctrine\DBAL\Query\Expression;
 
 use Doctrine\DBAL\Connection;
+use Doctrine\Deprecations\Deprecation;
+
 use function func_get_arg;
 use function func_get_args;
 use function func_num_args;
@@ -39,13 +41,29 @@ class ExpressionBuilder
     }
 
     /**
-     * Creates a conjunction of the given boolean expressions.
+     * Creates a conjunction of the given expressions.
      *
-     * Example:
+     * @param string|CompositeExpression $expression
+     * @param string|CompositeExpression ...$expressions
+     */
+    public function and($expression, ...$expressions): CompositeExpression
+    {
+        return CompositeExpression::and($expression, ...$expressions);
+    }
+
+    /**
+     * Creates a disjunction of the given expressions.
      *
-     *     [php]
-     *     // (u.type = ?) AND (u.role = ?)
-     *     $expr->andX('u.type = ?', 'u.role = ?'));
+     * @param string|CompositeExpression $expression
+     * @param string|CompositeExpression ...$expressions
+     */
+    public function or($expression, ...$expressions): CompositeExpression
+    {
+        return CompositeExpression::or($expression, ...$expressions);
+    }
+
+    /**
+     * @deprecated Use `and()` instead.
      *
      * @param mixed $x Optional clause. Defaults = null, but requires
      *                 at least one defined when converting to string.
@@ -54,17 +72,17 @@ class ExpressionBuilder
      */
     public function andX($x = null)
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/3851',
+            'ExpressionBuilder::andX() is deprecated, use ExpressionBuilder::and() instead.'
+        );
+
         return new CompositeExpression(CompositeExpression::TYPE_AND, func_get_args());
     }
 
     /**
-     * Creates a disjunction of the given boolean expressions.
-     *
-     * Example:
-     *
-     *     [php]
-     *     // (u.type = ?) OR (u.role = ?)
-     *     $qb->where($qb->expr()->orX('u.type = ?', 'u.role = ?'));
+     * @deprecated Use `or()` instead.
      *
      * @param mixed $x Optional clause. Defaults = null, but requires
      *                 at least one defined when converting to string.
@@ -73,6 +91,12 @@ class ExpressionBuilder
      */
     public function orX($x = null)
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/3851',
+            'ExpressionBuilder::orX() is deprecated, use ExpressionBuilder::or() instead.'
+        );
+
         return new CompositeExpression(CompositeExpression::TYPE_OR, func_get_args());
     }
 
@@ -208,7 +232,7 @@ class ExpressionBuilder
     /**
      * Creates an IS NULL expression with the given arguments.
      *
-     * @param string $x The field in string format to be restricted by IS NULL.
+     * @param string $x The expression to be restricted by IS NULL.
      *
      * @return string
      */
@@ -220,7 +244,7 @@ class ExpressionBuilder
     /**
      * Creates an IS NOT NULL expression with the given arguments.
      *
-     * @param string $x The field in string format to be restricted by IS NOT NULL.
+     * @param string $x The expression to be restricted by IS NOT NULL.
      *
      * @return string
      */
@@ -273,7 +297,7 @@ class ExpressionBuilder
     /**
      * Creates a NOT IN () comparison expression with the given arguments.
      *
-     * @param string          $x The field in string format to be inspected by NOT IN() comparison.
+     * @param string          $x The expression to be inspected by NOT IN() comparison.
      * @param string|string[] $y The placeholder or the array of values to be used by NOT IN() comparison.
      *
      * @return string
@@ -286,8 +310,8 @@ class ExpressionBuilder
     /**
      * Quotes a given input parameter.
      *
-     * @param mixed       $input The parameter to be quoted.
-     * @param string|null $type  The type of the parameter.
+     * @param mixed    $input The parameter to be quoted.
+     * @param int|null $type  The type of the parameter.
      *
      * @return string
      */