README

LaravelFilter 是一个旨在简化 Laravel 项目中表字段过滤过程的包。它提供了一种简单的方法来为您的模型实现自定义查询过滤器。

入门

安装

在开始之前，请检查官方的 Laravel 安装指南以了解服务器要求。官方文档

您可以通过 composer 安装此包

composer require baraadark/laravel-filter

接下来，发布配置文件

php artisan vendor:publish --tag=config

用法

应用 Filterable 特性

在您的模型中使用 Filterable 特性来启用过滤。

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use BaraaDark\LaravelFilter\Traits\Filterable;

class YourModel extends Model
{
    use Filterable;
}

重写 filterKeys 函数

您应该重写 filtersKeys 方法以返回一个包含过滤键及其对应过滤类的数组。

示例

use BaraaDark\LaravelFilter\Traits\Filterable;

class YourModel extends Model
{
    use Filterable;

    public function filtersKeys(): array
    {
        return [
            // 'filter-key' => FilterClass::class
        ];
    }
}

filtersKeys 方法返回一个关联数组，其中的键是请求中期望的过滤键的名称，值是包含查询逻辑的过滤类。

创建 Filter 类

要创建 Filter 类，运行以下命令

php artisan make:filter

您将被提示输入类名和相关模型名。生成的文件将位于 App\Http\Filters\ModelName。

Filter 类结构

namespace App\Http\Filters\ModelName;

use BaraaDark\LaravelFilter\Filter;

class FilterClass extends Filter
{
    /**
     * Get the validation rules that apply to the filter request.
     *
     * @return array
     */
    public static function rules(): array
    {
        return [];
    }

    /**
     * Apply filter query on the related model.
     *
     * @param \Illuminate\Database\Eloquent\Builder &$query
     */
    public function apply(&$query)
    {
        return $query;
    }
}

示例 Filter 类

use BaraaDark\LaravelFilter\Filter;

class ProductPriceRangeFilter extends Filter
{
    /**
     * Get the validation rules that apply to the filter request.
     *
     * @return array
     */
    public static function rules(): array
    {
        return [
            'min'   => ['required', 'numeric', 'min:0'],
            'max'   => ['required', 'numeric']
        ];
    }

    /**
     * Apply filter query on related model.
     * @param  \Illuminate\Database\Eloquent\Builder &$query
     */
    public function apply(&$query)
    {
        return $query->where('price', '>=', $this->min)
            ->where('price', '<=', $this->max);
    }
}

注意：您可以通过使用 $this->key 容易地访问与每个过滤键关联的值。

产品模型

use BaraaDark\LaravelFilter\Traits\Filterable;
use App\Http\Filters\Product\ProductPriceRangeFilter;

class Product extends Model
{
    use HasFactory, Filterable;

    protected $guarded = [];

    public function filtersKeys(): array
    {
        return [
            'price-range'   => ProductPriceRangeFilter::class
        ];
    }
}

应用过滤器

可以通过在请求体中发送以下结构的请求来应用过滤器

{
    "filters": {
        "filter_key": {
            "filter_class_key": "value",
            "filter_class_key": "value"
        }
    }
}

示例

{
    "filters": {
        "price-range": {
            "min": 500000,
            "max": 1000000
        }
    }
}

全局与局部作用域

如果配置文件中将 apply_global_scope 设置为 true，则在请求中包含过滤器时，将全局应用于所有模型。这不建议作为一般设置，因为可能在同一个函数中使用多个模型，并且您可能希望手动将过滤器应用于主模型。

配置

要配置全局作用域

// config/laravel-filter.php

return [
    'apply_global_scope' => false, // Set to true to enable global scope
];

使用局部作用域

如果 apply_global_scope 设置为 false，您可以在控制器中手动应用过滤器

use App\Models\SubjectCategory;

public function index(): LengthAwarePaginator
{
    return SubjectCategory::applyFilter()->paginate();
}

注意

请记住，由于请求包含数据，使用过滤的路线应使用 POST 或 match(['post', 'get'])。

baraadark / laravel-filter

维护者

详细信息