README

使用URL参数轻松排序、过滤和搜索Eloquent模型。

类文档

目录

入门

安装

使用Composer安装

composer require meikooy/laravel-filterable 

配置

在您的config目录中创建新的配置文件filterable.php（config/filterable.php）。

<?php

return [
    'namespace' => '\App\Models' # The namespace which contains your models
];

使用

要为您的模型启用使用，您需要将提供的Filterable特质应用到您的模型上。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Meiko\Filterable\Filterable;

class Post extends Model {
    use Filterable;
}

接下来，在您的控制器中调用filters。

示例

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\Post;

class PostController extends Controller
{
    public function index(Request $request)
    {
        return Post::filters(
            function ($filterer) {
                return $filterer;
            }
        );    
    }
    

排序

要排序您的Eloquent模型，请使用sort URL参数

sort=<列名>.

升序

示例：按updated_at列升序排序帖子。

https:///api/posts?sort=updated_at

降序

要按降序排序结果，在URL参数值前加-。

https:///api/posts?sort=-updated_at

过滤

要过滤您的Eloquent模型，您需要在URL中提供列名、比较类型和值。

<列名>=<比较类型>=<值>

示例

获取标题列包含Lorem ipsum文本的帖子。

http///api/posts?title=lk=Lorem ipsum

获取标题不是Lorem ipsum的帖子。

http///api/posts?title=nl=Lorem ipsum

获取read_count列值大于100的帖子。

http///api/posts?read_count=gt=100

获取标题列包含以下之一：Lorem ipsum、Hello或First的帖子。

http///api/posts?title=in=Lorem ipsum|Hello|First

注意：当提供多个值时，使用|字符分隔元素。只有bw、not-bw、in、not-in比较类型支持多个值。

查看Field.php以获取所有支持的比较类型。

ID列

如果您需要通过一个关系过滤模型并且使用某种ID混淆库（如hashids），则使用混淆ID的查询将不会工作。

http///api/posts?user_id=BOaPXaoz # Won't return any results as we are trying to match the `user_id` (in the database) with the obfuscated value: BOaPXaoz

为了解决这个问题，您可以设置自定义的 idResolver（在 config/filterable.php 中）以在查询中使用之前将您的id值“解码”。

config/filterable.php

<?php

return [
    'namespace' => '\App\Models',
    'idResolver' => App\Models\IdResolver::class // The class has to have resolve() method
];

app/Models/IdResolver.php

<?php

namespace App\Models;

use Hashids\Hashids;

class IdResolver
{
    public function resolve($modelName, $id, $routeKeyName)
    {
        $hashids = new Hashids();
        $decodedId = $hashids->decode($id);
        return $decodedId;
    }
}

自定义过滤器

如果提供的比较类型不够用或者您希望对过滤过程添加一些额外的逻辑，您也可以创建自己的过滤器。

示例：用户与帖子之间有一个对多关系。我们需要通过创建者的用户名来过滤帖子。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\Post;

class PostController extends Controller
{
    public function index(Request $request)
    {
        return Post::filters(
                function ($filterer) {
                    $filterer->addFilterColumn(
                        'username',
                        function ($query, $type, $value) {
                            $query->whereHas(
                                'user',
                                function ($userQuery) use ($value) {
                                    return $userQuery->where('users.username', 'like', $value);
                                }
                            );
                        }
                    );

                    return $filterer;
                }
            );    
    }
    

现在我们可以在查询中使用 username URL参数。

https:///api/posts?username=meikooy

搜索

先决条件

要使用搜索，您首先需要配置可搜索的列。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Meiko\Filterable\Filterable;

class Post extends Model {
    use Filterable;

    /**
     * Searchable attributes
     *
     * @var array
     */
    protected $searchable = [
        'title',
        'content',
    ];
}

用法

要搜索，请使用 _q URL参数。

http///api/posts?_q=searchword

查询尝试在帖子的 title 和 content 列中找到与 searchword 匹配的内容。