Case sensitive option in LikeCondition

CHANGELOG.md

@@ -68,6 +68,7 @@
 - Chg #938, #936, #937: Remove `ext-json`, `ext-ctype`, `ext-mbstring` from `require` section of `composer.json` (@Tigrov) 
 - Chg #936: Remove `hasLimit()` and `hasOffset()` methods from `AbstractDQLQueryBuilder` class (@Tigrov)
 - Chg #937: Remove `baseName()` and `pascalCaseToId()` methods from `DbStringHelper` (@Tigrov)
+- New #939: Add `caseSensitive` option to like condition (@vjik)
 
 ## 1.3.0 March 21, 2024
 

UPGRADE.md

@@ -123,6 +123,7 @@ Each table column has its own class in the `Yiisoft\Db\Schema\Column` namespace
 - `QueryBuilderInterface::prepareValue()` - converts a value to its SQL representation;
 - `QueryBuilderInterface::getServerInfo()` - returns `ServerInfoInterface` instance which provides server information;
 - `ConnectionInterface::getServerInfo()` - returns `ServerInfoInterface` instance which provides server information;
+- `LikeConditionInterface::getCaseSensitive()` - returns whether the comparison is case-sensitive.
 
 ### Remove methods
 

docs/guide/en/query/where.md

@@ -191,6 +191,9 @@ You may use false or an empty array to indicate the values are already escaped a
 > Note: That when using an escape mapping (or the third operand isn't provided),
 > the values will be automatically inside within a pair of percentage characters.
 
+Optionally, you can specify the case sensitivity of the `LIKE` condition by passing boolean value with `caseSensitive` 
+key, e.g. `['like', 'name', 'Ivan', 'caseSensitive' => true]`.
+
 > Note: When using PostgreSQL, you may also use `ilike` instead of `like` for case-insensitive matching.
 
 ### or like

src/QueryBuilder/Condition/Builder/LikeConditionBuilder.php

@@ -4,6 +4,8 @@
 
 namespace Yiisoft\Db\QueryBuilder\Condition\Builder;
 
+use Yiisoft\Db\Command\Param;
+use Yiisoft\Db\Constant\DataType;
 use Yiisoft\Db\Exception\Exception;
 use Yiisoft\Db\Exception\InvalidArgumentException;
 use Yiisoft\Db\Exception\InvalidConfigException;
@@ -51,16 +53,14 @@ public function __construct(
      */
     public function build(LikeConditionInterface $expression, array &$params = []): string
     {
-        $operator = strtoupper($expression->getOperator());
-        $column = $expression->getColumn();
         $values = $expression->getValue();
         $escape = $expression->getEscapingReplacements();
 
         if ($escape === []) {
             $escape = $this->escapingReplacements;
         }
 
-        [$andor, $not, $operator] = $this->parseOperator($operator);
+        [$andor, $not, $operator] = $this->parseOperator($expression);
 
         if (!is_array($values)) {
             $values = [$values];
@@ -70,39 +70,76 @@ public function build(LikeConditionInterface $expression, array &$params = []):
             return $not ? '' : '0=1';
         }
 
-        if ($column instanceof ExpressionInterface) {
-            $column = $this->queryBuilder->buildExpression($column, $params);
-        } elseif (!str_contains($column, '(')) {
-            $column = $this->queryBuilder->quoter()->quoteColumnName($column);
-        }
+        $column = $this->prepareColumn($expression, $params);
 
         $parts = [];
 
-        /** @psalm-var string[] $values */
+        /** @psalm-var list<string|ExpressionInterface> $values */
         foreach ($values as $value) {
-            if ($value instanceof ExpressionInterface) {
-                $phName = $this->queryBuilder->buildExpression($value, $params);
-            } else {
-                $phName = $this->queryBuilder->bindParam(
-                    $escape === null ? $value : ('%' . strtr($value, $escape) . '%'),
-                    $params
-                );
-            }
-            $parts[] = "$column $operator $phName$this->escapeSql";
+            $placeholderName = $this->preparePlaceholderName($value, $expression, $escape, $params);
+            $parts[] = "$column $operator $placeholderName$this->escapeSql";
         }
 
         return implode($andor, $parts);
     }
 
+    /**
+     * Prepare column to use in SQL.
+     *
+     * @throws Exception
+     * @throws InvalidArgumentException
+     * @throws InvalidConfigException
+     * @throws NotSupportedException
+     */
+    protected function prepareColumn(LikeConditionInterface $expression, array &$params): string
+    {
+        $column = $expression->getColumn();
+
+        if ($column instanceof ExpressionInterface) {
+            return $this->queryBuilder->buildExpression($column, $params);
+        }
+
+        if (!str_contains($column, '(')) {
+            return $this->queryBuilder->quoter()->quoteColumnName($column);
+        }
+
+        return $column;
+    }
+
+    /**
+     * Prepare value to use in SQL.
+     *
+     * @throws Exception
+     * @throws InvalidArgumentException
+     * @throws InvalidConfigException
+     * @throws NotSupportedException
+     * @return string
+     */
+    protected function preparePlaceholderName(
+        string|ExpressionInterface $value,
+        LikeConditionInterface $expression,
+        array|null $escape,
+        array &$params,
+    ): string {
+        if ($value instanceof ExpressionInterface) {
+            return $this->queryBuilder->buildExpression($value, $params);
+        }
+        return $this->queryBuilder->bindParam(
+            new Param($escape === null ? $value : ('%' . strtr($value, $escape) . '%'), DataType::STRING),
+            $params
+        );
+    }
+
     /**
      * Parses operator and returns its parts.
      *
      * @throws InvalidArgumentException
      *
      * @psalm-return array{0: string, 1: bool, 2: string}
      */
-    protected function parseOperator(string $operator): array
+    protected function parseOperator(LikeConditionInterface $expression): array
     {
+        $operator = strtoupper($expression->getOperator());
         if (!preg_match('/^(AND |OR |)((NOT |)I?LIKE)/', $operator, $matches)) {
             throw new InvalidArgumentException("Invalid operator in like condition: \"$operator\"");
         }

src/QueryBuilder/Condition/Interface/ConditionInterface.php

@@ -16,7 +16,7 @@ interface ConditionInterface extends ExpressionInterface
      * Creates object by array-definition.
      *
      * @param string $operator Operator in uppercase.
-     * @param array  $operands Array of corresponding operands
+     * @param array $operands Array of corresponding operands
      *
      * @throws InvalidArgumentException If input parameters aren't suitable for this condition.
      */

src/QueryBuilder/Condition/Interface/LikeConditionInterface.php

@@ -43,4 +43,9 @@ public function getOperator(): string;
      * @return array|ExpressionInterface|int|Iterator|string|null The value to the right of {@see operator}.
      */
     public function getValue(): array|int|string|Iterator|ExpressionInterface|null;
+
+    /**
+     * @return bool|null Whether the comparison is case-sensitive. `null` means using the default behavior.
+     */
+    public function getCaseSensitive(): ?bool;
 }

src/QueryBuilder/Condition/LikeCondition.php

@@ -22,9 +22,10 @@ final class LikeCondition implements LikeConditionInterface
     protected array|null $escapingReplacements = [];
 
     public function __construct(
-        private string|ExpressionInterface $column,
-        private string $operator,
-        private array|int|string|Iterator|ExpressionInterface|null $value
+        private readonly string|ExpressionInterface $column,
+        private readonly string $operator,
+        private readonly array|int|string|Iterator|ExpressionInterface|null $value,
+        private readonly ?bool $caseSensitive = null,
     ) {
     }
 
@@ -48,6 +49,11 @@ public function getValue(): array|int|string|Iterator|ExpressionInterface|null
         return $this->value;
     }
 
+    public function getCaseSensitive(): ?bool
+    {
+        return $this->caseSensitive;
+    }
+
     public function setEscapingReplacements(array|null $escapingReplacements): void
     {
         $this->escapingReplacements = $escapingReplacements;
@@ -68,6 +74,7 @@ public static function fromArrayDefinition(string $operator, array $operands): s
             self::validateColumn($operator, $operands[0]),
             $operator,
             self::validateValue($operator, $operands[1]),
+            isset($operands['caseSensitive']) ? (bool) $operands['caseSensitive'] : null,
         );
 
         if (array_key_exists(2, $operands) && (is_array($operands[2]) || $operands[2] === null)) {

tests/AbstractQueryBuilderTest.php

@@ -223,14 +223,7 @@ public function testBatchInsert(
         $this->assertSame($expectedParams, $params);
     }
 
-    /**
-     * @dataProvider \Yiisoft\Db\Tests\Provider\QueryBuilderProvider::buildCondition
-     *
-     * @throws Exception
-     * @throws InvalidConfigException
-     * @throws InvalidArgumentException
-     * @throws NotSupportedException
-     */
+    #[DataProviderExternal(QueryBuilderProvider::class, 'buildCondition')]
     public function testBuildCondition(
         array|ExpressionInterface|string $condition,
         string|null $expected,
@@ -451,14 +444,7 @@ public function testBuildJoin(): void
         );
     }
 
-    /**
-     * @dataProvider \Yiisoft\Db\Tests\Provider\QueryBuilderProvider::buildLikeCondition
-     *
-     * @throws Exception
-     * @throws InvalidConfigException
-     * @throws InvalidArgumentException
-     * @throws NotSupportedException
-     */
+    #[DataProviderExternal(QueryBuilderProvider::class, 'buildLikeCondition')]
     public function testBuildLikeCondition(
         array|ExpressionInterface $condition,
         string $expected,
@@ -476,7 +462,16 @@ public function testBuildLikeCondition(
             . (empty($expected) ? '' : ' WHERE ' . DbHelper::replaceQuotes($expected, $db->getDriverName())),
             $sql
         );
-        $this->assertSame($expectedParams, $params);
+        $this->assertSame(array_keys($expectedParams), array_keys($params));
+        foreach ($params as $name => $value) {
+            if ($value instanceof Param) {
+                $this->assertInstanceOf(Param::class, $expectedParams[$name]);
+                $this->assertSame($expectedParams[$name]->getValue(), $value->getValue());
+                $this->assertSame($expectedParams[$name]->getType(), $value->getType());
+            } else {
+                $this->assertSame($expectedParams[$name], $value);
+            }
+        }
     }
 
     public function testBuildLimit(): void

tests/Common/CommonQueryTest.php

@@ -4,6 +4,7 @@
 
 namespace Yiisoft\Db\Tests\Common;
 
+use PHPUnit\Framework\Attributes\DataProvider;
 use Yiisoft\Db\Expression\Expression;
 use Yiisoft\Db\Query\Query;
 use Yiisoft\Db\Tests\AbstractQueryTest;
@@ -81,4 +82,58 @@ public function testSelectWithoutFrom()
 
         $db->close();
     }
+
+    public function testLikeDefaultCaseSensitive(): void
+    {
+        $db = $this->getConnection(true);
+
+        $result = (new Query($db))
+            ->select('name')
+            ->from('customer')
+            ->where(['like', 'name', 'user1'])
+            ->scalar();
+
+
+        $this->assertSame('user1', $result);
+    }
+
+    public static function dataLikeCaseSensitive(): iterable
+    {
+        yield 'sameCase' => ['user1', 'user1'];
+        yield 'otherCase' => [false, 'USER1'];
+    }
+
+    #[DataProvider('dataLikeCaseSensitive')]
+    public function testLikeCaseSensitive(mixed $expected, string $value): void
+    {
+        $db = $this->getConnection(true);
+
+        $result = (new Query($db))
+            ->select('name')
+            ->from('customer')
+            ->where(['like', 'name', $value, 'caseSensitive' => true])
+            ->scalar();
+
+        $this->assertSame($expected, $result);
+    }
+
+    public static function dataLikeCaseInsensitive(): iterable
+    {
+        yield 'sameCase' => ['user1', 'user1'];
+        yield 'otherCase' => ['user1', 'USER1'];
+    }
+
+    #[DataProvider('dataLikeCaseInsensitive')]
+    public function testLikeCaseInsensitive(mixed $expected, string $value): void
+    {
+        $db = $this->getConnection(true);
+
+        $result = (new Query($db))
+            ->select('name')
+            ->from('customer')
+            ->where(['like', 'name', $value, 'caseSensitive' => false])
+            ->scalar();
+
+        $this->assertSame($expected, $result);
+    }
 }

tests/Db/QueryBuilder/Condition/LikeConditionTest.php

@@ -4,14 +4,13 @@
 
 namespace Yiisoft\Db\Tests\Db\QueryBuilder\Condition;
 
+use PHPUnit\Framework\Attributes\TestWith;
 use PHPUnit\Framework\TestCase;
 use Yiisoft\Db\Exception\InvalidArgumentException;
 use Yiisoft\Db\QueryBuilder\Condition\LikeCondition;
 
 /**
  * @group db
- *
- * @psalm-suppress PropertyNotSetInConstructor
  */
 final class LikeConditionTest extends TestCase
 {
@@ -22,6 +21,7 @@ public function testConstructor(): void
         $this->assertSame('id', $likeCondition->getColumn());
         $this->assertSame('LIKE', $likeCondition->getOperator());
         $this->assertSame('test', $likeCondition->getValue());
+        $this->assertNull($likeCondition->getCaseSensitive());
     }
 
     public function testFromArrayDefinition(): void
@@ -76,4 +76,17 @@ public function testSetEscapingReplacements(): void
 
         $this->assertSame(['%' => '\%', '_' => '\_'], $likeCondition->getEscapingReplacements());
     }
+
+    #[TestWith([null])]
+    #[TestWith([true])]
+    #[TestWith([false])]
+    public function testFromArrayDefinitionCaseSensitive(?bool $caseSensitive): void
+    {
+        $likeCondition = LikeCondition::fromArrayDefinition('LIKE', ['id', 'test', 'caseSensitive' => $caseSensitive]);
+
+        $this->assertSame('id', $likeCondition->getColumn());
+        $this->assertSame('LIKE', $likeCondition->getOperator());
+        $this->assertSame('test', $likeCondition->getValue());
+        $this->assertSame($caseSensitive, $likeCondition->getCaseSensitive());
+    }
 }