Replace andX/orX with and/or

Author: BenMorel

UPGRADE.md

@@ -1,3 +1,9 @@
+# Upgrade to 2.11
+
+## Deprecated `ExpressionBuilder` methods
+
+The usage of the `andX()` and `orX()` methods of the `ExpressionBuilder` class has been deprecated. Use `and()` and `or()` instead.
+
 # Upgrade to 2.10
 
 ## Deprecated `Doctrine\DBAL\Event\ConnectionEventArgs` methods

docs/en/reference/query-builder.rst

@@ -332,13 +332,13 @@ Most notably you can use expressions to build nested And-/Or statements:
         ->select('id', 'name')
         ->from('users')
         ->where(
-            $queryBuilder->expr()->andX(
+            $queryBuilder->expr()->and(
                 $queryBuilder->expr()->eq('username', '?'),
                 $queryBuilder->expr()->eq('email', '?')
             )
         );
 
-The ``andX()`` and ``orX()`` methods accept an arbitrary amount
+The ``and()`` and ``or()`` methods accept an arbitrary amount
 of arguments and can be nested in each other.
 
 There is a bunch of methods to create comparisons and other SQL snippets

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

@@ -39,13 +39,27 @@ public function __construct(Connection $connection)
     }
 
     /**
-     * Creates a conjunction of the given boolean expressions.
+     * Creates a conjunction of the given expressions.
      *
-     * Example:
+     * @param string|CompositeExpression ...$expressions Requires at least one defined when converting to string.
+     */
+    public function and(...$expressions) : CompositeExpression
+    {
+        return new CompositeExpression(CompositeExpression::TYPE_AND, $expressions);
+    }
+
+    /**
+     * Creates a disjunction of the given expressions.
      *
-     *     [php]
-     *     // (u.type = ?) AND (u.role = ?)
-     *     $expr->andX('u.type = ?', 'u.role = ?'));
+     * @param string|CompositeExpression ...$expressions Requires at least one defined when converting to string.
+     */
+    public function or(...$expressions) : CompositeExpression
+    {
+        return new CompositeExpression(CompositeExpression::TYPE_OR, $expressions);
+    }
+
+    /**
+     * @deprecated Use `and()` instead.
      *
      * @param mixed $x Optional clause. Defaults = null, but requires
      *                 at least one defined when converting to string.
@@ -54,17 +68,11 @@ public function __construct(Connection $connection)
      */
     public function andX($x = null)
     {
-        return new CompositeExpression(CompositeExpression::TYPE_AND, func_get_args());
+        return $this->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,7 +81,7 @@ public function andX($x = null)
      */
     public function orX($x = null)
     {
-        return new CompositeExpression(CompositeExpression::TYPE_OR, func_get_args());
+        return $this->or(...func_get_args());
     }
 
     /**

tests/Doctrine/Tests/DBAL/Query/Expression/ExpressionBuilderTest.php

@@ -29,11 +29,11 @@ protected function setUp() : void
     /**
      * @param string[]|CompositeExpression[] $parts
      *
-     * @dataProvider provideDataForAndX
+     * @dataProvider provideDataForAnd
      */
-    public function testAndX(array $parts, string $expected) : void
+    public function testAnd(array $parts, string $expected) : void
     {
-        $composite = $this->expr->andX();
+        $composite = $this->expr->and();
 
         foreach ($parts as $part) {
             $composite->add($part);
@@ -45,7 +45,7 @@ public function testAndX(array $parts, string $expected) : void
     /**
      * @return mixed[][]
      */
-    public static function provideDataForAndX() : iterable
+    public static function provideDataForAnd() : iterable
     {
         return [
             [
@@ -90,11 +90,11 @@ public static function provideDataForAndX() : iterable
     /**
      * @param string[]|CompositeExpression[] $parts
      *
-     * @dataProvider provideDataForOrX
+     * @dataProvider provideDataForOr
      */
-    public function testOrX(array $parts, string $expected) : void
+    public function testOr(array $parts, string $expected) : void
     {
-        $composite = $this->expr->orX();
+        $composite = $this->expr->or();
 
         foreach ($parts as $part) {
             $composite->add($part);
@@ -106,7 +106,7 @@ public function testOrX(array $parts, string $expected) : void
     /**
      * @return mixed[][]
      */
-    public static function provideDataForOrX() : iterable
+    public static function provideDataForOr() : iterable
     {
         return [
             [

tests/Doctrine/Tests/DBAL/Query/QueryBuilderTest.php

@@ -68,7 +68,7 @@ public function testSelectWithSimpleWhere() : void
 
         $qb->select('u.id')
            ->from('users', 'u')
-           ->where($expr->andX($expr->eq('u.nickname', '?')));
+           ->where($expr->and($expr->eq('u.nickname', '?')));
 
         self::assertEquals('SELECT u.id FROM users u WHERE u.nickname = ?', (string) $qb);
     }