README

此包允许您通过简单定义相应的Eloquent API资源对象中应公开哪些字段，轻松且安全地为Laravel端点提供全面的过滤和排序功能。

该包深受 Spatie Query Builder 和 Laravel Orion 的启发。

基本用法

基本功能通过GET请求中的查询参数提供

 // find employees where `name` = "Michael"
GET /employees?filter[name]=Michael

// find employees where `name` like "Michael%"
GET /employees?filter[name]=Michael* 

// find employees where `name` like "Michael%" OR `name` like "Dwight"
GET /employees?filter[name]=Michael*,Dwight 

// find employees where `name` =  "Michael" AND `email` like "%@dundermifflin.com"
GET /employees?filter[name]=Michael&filter[email]=*@dundermifflin.com

// find employees where `email` like "%@dundermifflin.com" order by `hired_at`
GET /employees?filter[email]=*@dundermifflin.com&sort=hired_at 

// find employees where `email` like "%@dundermifflin.com" order by `hired_at` desc
GET /employees?filter[email]=*@dundermifflin.com&sort=-hired_at 

// find the two most recently hired employees where any searchable field contains "stamford"
GET /employees?q=stamford&sort=-hired_at&page[size]=2

了解更多关于基本搜索功能，如：过滤器、分页、搜索、排序...

扩展功能通过POST请求中的body有效载荷提供

// POST /employees/search?page[size]=10
{
    "scopes" : [
        {"name" : "active"},
        {"name" : "whereBranch", "parameters" : ["scranton"]}
    ],
    "filters" : [
        {"field" : "hired_at", "operator" : ">=", "value" : "2001-01-01"},
        {"type" : "or", "field" : "name", "operator" : "in", "value" : ["Ed Truck", "Tod Packer"]}
    ],
    "search" : {
        "value" : "manager"
    },
    "sort" : [
        {"field" : "dundie_count", "direction" : "desc"},
        {"field" : "dundie.name", "direction" : "asc"}
    ]
}

了解更多关于高级搜索功能，如：作用域、过滤器、分页、搜索、排序...

安装

您可以通过composer安装此包

composer require liveintent/laravel-resource-search

该包将自动注册其服务提供者。

您可以选择通过以下方式发布配置文件：

php artisan vendor:publish --provider="LiveIntent\LaravelResourceSearch\LaravelResourceSearchServiceProvider" --tag="resource-search-config"

将可搜索资源添加到您的API

Laravel的 Eloquent API资源 作为一个转换层，位于您的Eloquent模型和实际返回给应用用户的JSON响应之间。因此，我们认为这也是一个很好的地方来定义用户在列出和搜索这些资源时应该拥有的功能。

要将任何现有的Eloquent资源转换为可搜索的Eloquent资源，您的资源应使用此包提供的Searchable特质，并指示资源实现SearchableResource接口。最后，您需要在资源上定义一个$model属性，该属性指示应使用哪个底层的Eloquent模型进行基本查询。

<?php

use Illuminate\Http\Resources\Json\JsonResource;
use LiveIntent\LaravelResourceSearch\Searchable;
use LiveIntent\LaravelResourceSearch\Contracts\SearchableResource;

class PostResource extends JsonResource implements SearchableResource
{
    use Searchable;

    /**
     * The base model of the resource.
     */
    public $model = \App\Models\Post::class;
}

将搜索端点添加到您的API

用户在搜索API时可能使用两种方法。对于简单的查询，他们可能更喜欢使用具有最少查询参数的GET请求来构建查询。其他时候，用户可能希望构建更复杂的查询，这可能需要传递包含嵌套逻辑组等内容的更大请求有效载荷。

添加基本搜索端点

您可以通过在SearchableResource上调用basicSearch方法并将结果返回来将任何新的或现有的端点转换为允许基本搜索的端点。

use App\Http\Resources\PostResource;

Route::get('/posts', function () {
    return PostResource::basicSearch();
});

如果您需要更高级别的查询控制，例如应用查询作用域，请创建您的查询并将Builder传递给basicSearch方法，以便它可以基于用户的输入进一步过滤结果。

use App\Models\Post;
use App\Http\Resources\PostResource;

Route::get('/published-posts', function () {
    return PostResource::basicSearch(Post::published());
});

添加高级搜索端点

您可以通过在SearchableResource上调用search方法并将结果返回来将任何新的或现有的端点转换为允许高级搜索的端点。

use App\Http\Resources\PostResource;

Route::post('/posts/search', function () {
    return PostResource::search();
});

与基本搜索一样，如果您需要更高级别的查询控制，您可以将现有的Builder传递给search方法，并且它将根据用户的输入进一步过滤结果。

use App\Models\Post;
use App\Http\Resources\PostResource;

Route::post('/published-posts/search', function () {
    return PostResource::search(Post::published());
});

文档

您可以在以下位置找到文档：这里。

变更日志

请参阅CHANGELOG，了解最近有哪些更改。

贡献

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

为什么不呢...？

在您使用此包之前，还有其他几个选项您应该考虑。

• Laravel Scout - 提供了一种简单、基于驱动器的解决方案，用于向您的Eloquent模型添加全文搜索。如果您需要全文搜索，这可能是您应该采取的方法。
• Spatie Laravel Query Builder - 提供了一个简单但非常灵活的包，可以基于JSON API规范为您的API启用广泛的过滤和排序功能。然而，此包尚不支持发送更广泛的消息主体，这限制了允许更广泛结构化请求的能力。
• Laravel Orion - 是一个功能齐全的包，旨在帮助您在Laravel中设计REST API。虽然Orion提供了惊人的功能集，但它还需要与您的应用进行更深入且更具观点的集成，这可能使得仅希望为一些端点添加过滤功能变得困难。