README

此包允许您通过查询字符串轻松处理数据库过滤。这个想法来自Jeffrey的视频之一（付费墙后）。一个简单的例子可能如下所示：/users?filter-username=~joe将生成SQL查询select * from users where "username" like '%joe%'。

安装

您可以通过composer安装此包

composer require kyslik/laravel-filterable

如果您使用的是Laravel 7

composer require kyslik/laravel-filterable dev-L7

Laravel会自动发现此包。如果您觉得过时了，请禁用自动发现，并将Kyslik\LaravelFilterable\FilterableServiceProvider::class添加到您的config/app.php中的提供者数组中。

您可以通过执行以下artisan命令来继续发布配置php artisan vendor:publish。

简介

该包允许您创建并应用两种类型的过滤器：自定义和通用。

自定义过滤器

自定义过滤器就像在Jeffrey的视频中一样。您在一个构建器实例上定义逻辑，然后通过本地作用域应用它。

假设一个产品需要显示最近创建的记录。您在过滤器类中创建一个方法recent($minutes = null)，它返回Builder实例

public function recent($minutes = null): \Illuminate\Database\Eloquent\Builder
{
    $minutes = (is_numeric($minutes)) ? $minutes : 30;

    return $this->builder->where('created_at', '>=', Carbon\Carbon::now()->subMinutes($minutes));
}

注意：完整的示例将在后面展示

通用过滤器

通用过滤器是在配置文件中定义的。默认情况下，该包支持过滤timestamps、ranges、ins、booleans和strings。

/?filter-created_at=t>=1510952444
/?filter-id=><1,19
/?filter-id=i=1,5,10,12
/?filter-admin=b=yes
/?filter-username=joe
/?filter-username=~joe
/?filter-username=~joe&filter-admin=b=yes&filter-created_at=t=1510952444

通用过滤器的默认运算符矩阵

用法

在使用自定义或通用过滤器时，您必须

在具有签名scopeFilter(Builder $query, FILTERNAME $filters)的模型上具有本地作用域
有特定的（FILTERNAME）过滤器类，该类扩展了以下之一
- Kyslik\LaravelFilterable\Generic\Filter类 - 允许使用自定义和通用过滤器
- Kyslik\LaravelFilterable\Filter类 - 仅允许使用自定义过滤器
在控制器中调用作用域

make:filter命令

您可以使用以下命令创建新的过滤器。

php artisan make:filter SomeFilter

这将创建一个新自定义过滤器在app/Filters目录中。要创建通用过滤器，请向命令添加--generic（-g）标志

php artisan make:filter SomeGenericFilter -g

最后，您可以通过更改namespace配置值来覆盖默认命名空间

config/filterable.php

return [
    'namespace' => 'Http\Filters',
    ...
];

自定义过滤器的示例

假设您想在User模型上使用filterable。您将需要创建一个过滤器类App/Filters/UserFilter.php（php artisan make:filter UserFilter），指定filterMap()和自定义逻辑的方法（recent(...)）。

<?php
namespace App\Filters;

use Kyslik\LaravelFilterable\Filter;

class UserFilter extends Filter
{
    public function filterMap(): array
    {
        return ['recent' => ['recently', 'recent']];
    }

    public function recent($minutes = null)
    {
        $minutes = (is_numeric($minutes)) ? $minutes : 30;

        return $this->builder->where('created_at', '>=', \Carbon\Carbon::now()->subMinutes($minutes)->toDateTimeString());
    }
}

注意：filterMap()应返回一个关联数组，其中键是方法名，值是别名或别名数组

现在通过本地作用域将Filterable添加到User模型中

use Kyslik\LaravelFilterable\Filterable;

...
class User extends Model
{
    use Filterable;
    ...
}

最后，在控制器中调用作用域如下

use App\Filters\UserFilter;
...
public function index(User $user, UserFilter $filters)
{
    return $user->filter($filters)->paginate();
}

现在最终用户可以访问users?recent或users?recently或users?recent=25，结果将由在UserFilter类中定义的recent()方法进行过滤。

带有通用过滤器的示例

假设您想在User模型上使用通用过滤器。您需要创建过滤器类App/Filters/UserFilter.php（使用php artisan make:filter UserFilter -g创建），并像下面一样指定$filterables

<?php
namespace App\Filters;

use Kyslik\LaravelFilterable\Generic\Filter;

class UserFilter extends Filter
{
    protected $filterables = ['id', 'username', 'email', 'created_at', 'updated_at'];
}

接下来，您需要通过本地作用域将Filterable添加到User模型中

use Kyslik\LaravelFilterable\Filterable;

...
class User extends Model
{
    use Filterable;
    ...
}

最后，在控制器中调用作用域如下

use App\Filters\UserFilter;
...
public function index(User $user, UserFilter $filters)
{
    return $user->filter($filters)->paginate();
}

现在您已经准备好过滤User模型。

注意：在幕后，...\Generic\Filter类扩展了Filter类，因此使用...\Generic\Filter还可以使您能够应用在过滤器类中定义的自定义过滤器

其他配置

当使用通用过滤器时，您可以定义哪些泛型应该被允许。在过滤器类中定义settings()方法，如下所示

use Kyslik\LaravelFilterable\Generic\Filter
...
class UserFilter extends Filter
{
    protected $filterables = ['id', 'username', 'email', 'created_at', 'updated_at'];

    protected function settings()
    {
        // global settings for this filter, pick either "except" or "only" logic
        $this->only(['=', '~', '!~']);
        // $this->except(['!=']);

        // settings applied only to some columns, these settings ignore the "global" settings above
        $this->for(['username', 'id'])->only(['!=', '>=', '=', '~']);
        $this->for(['id'])->only(['=', '!=', '~']); // settings for "id" will be re-written
    }
}

其他功能

默认过滤

如果您需要在尚未应用过滤器时（由请求中的查询字符串内容确定）应用过滤器，您可以在控制器中使用以下代码

public function index(User $user, UserFilter $filter)
{
    // will redirect and "apply" the `recent` and `filter-id` filters 
    // if not a single filter from UserFilter is applied
    $filter->default(['recent' => now()->toDateTimeString(), 'filter-id' => '!=5']);

    return $user->filter($filter)->paginate();
}

最终用户将被重定向从http://filters.test/users到http://filters.test/users?recent=2018-10-01 13:52:40&filter-id=!=5。如果您指定的默认过滤器不存在，将抛出Kyslik\LaravelFilterable\Exceptions\InvalidArgumentException。

注意：小心无限重定向

您可以在原始问题#10中了解更多关于此功能的信息。

为过滤器添加JoinSupport

TBA

您可以在原始PR#9中了解更多关于此功能的信息。

测试

composer test

变更日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

贡献

请参阅CONTRIBUTING以获取详细信息。

安全

如果您发现任何安全相关的问题，请通过电子邮件martin.kiesel@gmail.com报告，而不是使用问题跟踪器。

鸣谢

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。

kyzlik / laravel-filterable

维护者

详细信息