增强 whereBrackets，支持查询条件收集器 (#580)

* 增强 whereBrackets，支持查询条件收集器

* 更新文档

* 更新文档

* 优化代码，完善测试用例

* 修复测试

doc/base/version/2.0-2.1.md

@@ -18,6 +18,12 @@ v2.0 是一个非常成功的 LTS 版本，进行了底层重构，增加了强
 
 ## 新功能
 
+### v2.1.53
+
+**发布日期：** `2023-09-01`
+
+* 增强 `whereBrackets`，支持查询条件收集器 ([#580](https://github.com/imiphp/imi/pull/580)) ([文档](https://doc.imiphp.com/v2.1/components/db/index.html#whereBrackets))
+
 ### v2.1.52
 
 **发布日期：** `2023-08-18`

doc/components/db/index.md

@@ -453,26 +453,37 @@ Db::query()->orWhereRaw('id >= :value', [':value' => 1]);
 #### whereBrackets
 
 ```php
+// 查询条件收集器：where (age < 14 or age > 60)
+Db::query()->where('id', '=', 1)->whereBrackets(function(\Imi\Db\Query\Interfaces\IQuery $query, \Imi\Db\Query\Interfaces\IWhereCollector $where) {
+    // 注意：使用第 2 个参数 $where，而不是 $query
+    $where->where('age', '<', 14)->orWhere('age', '>', 60);
+    // 不要有返回值
+}, 'or');
+
 // where id = 1 or (age < 14)
 Db::query()->where('id', '=', 1)->whereBrackets(function(\Imi\Db\Query\Interfaces\IQuery $query) {
-    // 直接返回字符串
+    // 返回条件字符串
     return 'age < 14';
 }, 'or');
+
 // 支持使用 sql 语句: where id = 1 or (age > 10 and age < 14)
 Db::query()->where('id', '=', 1)->whereBrackets(function(\Imi\Db\Query\Interfaces\IQuery $query) {
-    // 直接返回字符串
+    // 返回 Where 系列数组
     return [
         \Imi\Db\Query\Where\Where::raw('age > 10'),
         new \Imi\Db\Query\Where\Where('age', '<', 14),
     ];
 }, 'or');
+
 // where id = 1 or (age < 14)
 Db::query()->where('id', '=', 1)->whereBrackets(function(\Imi\Db\Query\Interfaces\IQuery $query) {
-    // 直接返回字符串
+    // 返回 Where 系列对象
     return new \Imi\Db\Query\Where\Where('age', '<', 14);
 }, 'or');
+
+// OR 条件
 Db::query()->where('id', '=', 1)->orWhereBrackets(function(\Imi\Db\Query\Interfaces\IQuery $query) {
-    // 直接返回字符串
+    // 返回 Where 系列对象
     return new \Imi\Db\Query\Where\Where('age', '<', 14);
 });
 ```

src/Components/pgsql/tests/Unit/Db/Pdo/QueryCurdTest.php

@@ -26,7 +26,7 @@ class QueryCurdTest extends QueryCurdBaseTest
      *
      * @var string
      */
-    protected $expectedTestWhereExSql = 'select * from "tb_article" where ("id" = :p1 and ("id" in (:p2) ) )';
+    protected $expectedTestWhereExSql = 'select * from "tb_article" where ("id" = :p1 and ("id" in (:p2)))';
 
     /**
      * 测试 JSON 查询的 SQL.

src/Components/pgsql/tests/Unit/Db/Swoole/QueryCurdTest.php

@@ -26,7 +26,7 @@ class QueryCurdTest extends QueryCurdBaseTest
      *
      * @var string
      */
-    protected $expectedTestWhereExSql = 'select * from "tb_article" where ("id" = :p1 and ("id" in (:p2) ) )';
+    protected $expectedTestWhereExSql = 'select * from "tb_article" where ("id" = :p1 and ("id" in (:p2)))';
 
     /**
      * 测试 JSON 查询的 SQL.

src/Components/swoole/tests/unit/Component/Tests/Db/Swoole/QueryCurdTest.php

@@ -23,7 +23,7 @@ class QueryCurdTest extends QueryCurdBaseTest
      *
      * @var string
      */
-    protected $expectedTestWhereExSql = 'select * from `tb_article` where (`id` = :p1 and (`id` in (:p2) ) )';
+    protected $expectedTestWhereExSql = 'select * from `tb_article` where (`id` = :p1 and (`id` in (:p2)))';
 
     /**
      * 测试 JSON 查询的 SQL.

src/Db/Query/Interfaces/IBaseWhereCollector.php

@@ -0,0 +1,190 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Imi\Db\Query\Interfaces;
+
+interface IBaseWhereCollector
+{
+    /**
+     * 设置 where 条件，一般用于 =、>、<、like等.
+     *
+     * @param mixed $value
+     *
+     * @return static
+     */
+    public function where(string $fieldName, string $operation, $value, string $logicalOperator = 'and'): self;
+
+    /**
+     * 设置 where 条件，用原生语句.
+     *
+     * @return static
+     */
+    public function whereRaw(string $raw, string $logicalOperator = 'and', array $binds = []): self;
+
+    /**
+     * 设置 where 条件，传入回调，回调中的条件加括号.
+     *
+     * @return static
+     */
+    public function whereBrackets(callable $callback, string $logicalOperator = 'and'): self;
+
+    /**
+     * 设置 where 条件，使用 IBaseWhere 结构.
+     *
+     * @return static
+     */
+    public function whereStruct(IBaseWhere $where, string $logicalOperator = 'and'): self;
+
+    /**
+     * 设置 where 条件，支持语法如下：.
+     *
+     * [
+     *      'id'    => 1,
+     *      'or'    => [
+     *          'id' => 2,
+     *      ],
+     *      'title' => ['like', '%test%'],
+     *      'age'   => ['>', 18],
+     *      'age'   => ['between', 19, 29]
+     * ]
+     *
+     * SQL: id = 1 or (id = 2) and title like '%test%' and age > 18 and age between 19 and 29
+     *
+     * @return static
+     */
+    public function whereEx(array $condition, string $logicalOperator = 'and'): self;
+
+    /**
+     * where between $begin end $end.
+     *
+     * @param mixed $begin
+     * @param mixed $end
+     *
+     * @return static
+     */
+    public function whereBetween(string $fieldName, $begin, $end, string $logicalOperator = 'and'): self;
+
+    /**
+     * or where between $begin end $end.
+     *
+     * @param mixed $begin
+     * @param mixed $end
+     *
+     * @return static
+     */
+    public function orWhereBetween(string $fieldName, $begin, $end): self;
+
+    /**
+     * where not between $begin end $end.
+     *
+     * @param mixed $begin
+     * @param mixed $end
+     *
+     * @return static
+     */
+    public function whereNotBetween(string $fieldName, $begin, $end, string $logicalOperator = 'and'): self;
+
+    /**
+     * or where not between $begin end $end.
+     *
+     * @param mixed $begin
+     * @param mixed $end
+     *
+     * @return static
+     */
+    public function orWhereNotBetween(string $fieldName, $begin, $end): self;
+
+    /**
+     * 设置 where or 条件.
+     *
+     * @param mixed $value
+     *
+     * @return static
+     */
+    public function orWhere(string $fieldName, string $operation, $value): self;
+
+    /**
+     * 设置 where or 条件，用原生语句.
+     *
+     * @return static
+     */
+    public function orWhereRaw(string $where, array $binds = []): self;
+
+    /**
+     * 设置 where or 条件，传入回调，回调中的条件加括号.
+     *
+     * @return static
+     */
+    public function orWhereBrackets(callable $callback): self;
+
+    /**
+     * 设置 where or 条件，使用 IBaseWhere 结构.
+     *
+     * @return static
+     */
+    public function orWhereStruct(IBaseWhere $where): self;
+
+    /**
+     * 设置 where or 条件，支持语法参考 whereEx 方法.
+     *
+     * @return static
+     */
+    public function orWhereEx(array $condition): self;
+
+    /**
+     * where field in (list).
+     *
+     * @return static
+     */
+    public function whereIn(string $fieldName, array $list, string $logicalOperator = 'and'): self;
+
+    /**
+     * or where field in (list).
+     *
+     * @return static
+     */
+    public function orWhereIn(string $fieldName, array $list): self;
+
+    /**
+     * where field not in (list).
+     *
+     * @return static
+     */
+    public function whereNotIn(string $fieldName, array $list, string $logicalOperator = 'and'): self;
+
+    /**
+     * or where field not in (list).
+     *
+     * @return static
+     */
+    public function orWhereNotIn(string $fieldName, array $list): self;
+
+    /**
+     * where field is null.
+     *
+     * @return static
+     */
+    public function whereIsNull(string $fieldName, string $logicalOperator = 'and'): self;
+
+    /**
+     * or where field is null.
+     *
+     * @return static
+     */
+    public function orWhereIsNull(string $fieldName): self;
+
+    /**
+     * where field is not null.
+     *
+     * @return static
+     */
+    public function whereIsNotNull(string $fieldName, string $logicalOperator = 'and'): self;
+
+    /**
+     * or where field is not null.
+     *
+     * @return static
+     */
+    public function orWhereIsNotNull(string $fieldName): self;
+}