README

此包提供了方便的类定义过滤器，用于您的 eloquent 查询。
每个过滤器都可以单独验证，允许您完全控制代码库，并避免将数据库结构暴露给外界。
查询过滤支持 DB 门面和 Eloquent 查询构建器。

安装

使用终端通过 composer 安装此包

composer require coderaworks/laravel-query-filters

此外，您还可以发布提供的翻译

php artisan vendor:publish --tag=laravel-query-filters

用法

创建过滤器

要创建过滤器，您只需创建一个实现 \CoderaWorks\LaravelQueryFilters\Interfaces\QueryFilterInterface 接口 的类

use \CoderaWorks\LaravelQueryFilters\Contract\QueryFilterInterface;
use Illuminate\Database\Eloquent\Builder as EloquentBuilder;

class ExampleFilter implements QueryFilterInterface
{
    public function pattern(): string
    {
        return 'example-filter';
    }

    public function valid(string $tag, mixed $value, mixed $data): bool
    {
        return true;
    }

    public function apply(Builder|EloquentBuilder $query, string $tag, mixed $value, mixed $data): void
    {
        $query->where('example-field', $value);
    }
}

pattern 返回用于匹配请求过滤器的正则表达式模式。
valid 方法返回提供的标签、值和数据组合是否适合此过滤器。
apply 方法以您喜欢的任何方式将过滤器应用于查询。

注册过滤器

要注册过滤器，您只需在您的 ServiceProvider 中注册它，例如

use CoderaWorks\LaravelQueryFilters\QueryFiltersProcessor;
use Illuminate\Support\ServiceProvider;

class ExampleServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->afterResolving(
            QueryFiltersProcessor::class,
            function (QueryFiltersProcessor $queryFiltersProcessor) {
                $queryFiltersProcessor->registerFilters(
                    'listing-tag',
                    ExampleFilter::class,
                );
            }
        );
    }
}

使用 afterResolving 与回调还可以确保列表处理器是延迟实例化的，这将在您实际上没有使用列表处理器时提高应用程序的性能。

应用过滤器

要应用过滤器，您应该首先创建一个经过验证的表单请求类，该类实现 \CoderaWorks\LaravelQueryFilters\Http\Requests\Trait\HasQueryFiltersInRequestTrait trait，例如

use CoderaWorks\LaravelQueryFilters\Http\Requests\Trait\HasQueryFiltersInRequestTrait;
use Illuminate\Foundation\Http\FormRequest;

class ExampleQueryFiltersRequest extends FormRequest
{
    use HasQueryFiltersInRequestTrait;

    public function rules(): array
    {
        return [
            // your custom additional validation rules go here
        ] + $this->getQueryFiltersRules();
    }

    public function queryFiltersList(): string
    {
        return 'example-list';
    }
}

表单请求必须实现 queryFiltersList 方法或 $queryFiltersList 属性，该属性返回即将处理的列表的标签。
您还应该确保使用 getQueryFiltersRules 方法返回从 trait 提供的列表规则。

然后您可以在控制器中使用创建并现在经过验证的请求类

use CoderaWorks\LaravelQueryFilters\QueryFiltersProcessor;
use CoderaWorks\LaravelQueryFilters\Tests\TestClasses\Http\Requests\QueryFiltersTestRequest;
use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\DB;

class ExampleQueryFiltersController
{
    public function __invoke(
        QueryFiltersExampleRequest $request,
    )
    {
        // Get a query instance which we want to filter, e.g. via `DB::table()`:
        $query = DB::table('your-table');
        
        $query->filter(
            $request->getQueryFiltersList(),
            $request->getPossibleQueryFiltersBag(),
        );

        // Get the query result, e.g. via `get()`:
        $result = $query->get();
    }
}

有效载荷

当使用此包时，您很可能会搭配单页应用程序（如 Vue），因此您需要为列表实现一个路由。有效载荷应包含以下形状的查询过滤器

type Payload = {
    filters: [
        {
            tag: string
            value?: any
            data?: any
        }

    ]
}

JSON有效载荷示例

{
  "filters": [
    {
      "tag": "example-filter",
      "value": "example-value",
      "data": {
        "key": "value"
      }
    },
    {
      "tag": "example-filter-2",
      "value": "example-value-2"
    },
    {
      "tag": "example-filter-3"
    }
  ]
}

示例

请参阅 示例 文件夹以获取更多关于如何使用此包的代码示例。