README

简介

一个Laravel基础控制器类和一个特性，允许您为资源URL添加过滤、排序、预加载和分页功能。

献给Bruno

此包以我的英雄Giordano Bruno的名字命名。一个真正的先知，敢于梦想那些被认为不可能的事情。为了他的思想和拒绝放弃它们，他在1600年被活活烧死。 我强烈推荐这部由Neil deGrasse Tyson讲述他生平的短片。

功能

• 解析GET参数以动态预加载相关资源、排序和分页
• 使用过滤组进行高级资源过滤
• 使用 duongld\Architect 进行外部、id或内嵌相关资源的加载

指南

要开始使用Bruno，我强烈推荐阅读关于 Laravel API中的资源控制 的文章

安装

composer require duongld/bruno

使用

以下示例将是一个假定的资源端点 /books，它将返回一个属于每个 Author 的 Book 集合。

Book n ----- 1 Author

可用的查询参数

执行

<?php

namespace App\Http\Controllers;

use Duongld\Api\Controller\EloquentBuilderTrait;
use Duongld\Api\Controller\LaravelController;
use App\Models\Book;

class BookController extends LaravelController
{
    use EloquentBuilderTrait;

    public function getBooks()
    {
        // Parse the resource options given by GET parameters
        $resourceOptions = $this->parseResourceOptions();

        // Start a new query for books using Eloquent query builder
        // (This would normally live somewhere else, e.g. in a Repository)
        $query = Book::query();
        $this->applyResourceOptions($query, $resourceOptions);
        $books = $query->get();

        // Parse the data using Optimus\Architect
        $parsedData = $this->parseData($books, $resourceOptions, 'books');

        // Create JSON response of parsed data
        return $this->response($parsedData);
    }
}

语法文档

预加载

简单预加载

/books?includes[]=author

使用模型 Book 中的函数关系author来加载额外的 Author 数组。

IDs模式

/books?includes[]=author:ids

获取所有 Author 的id。

侧加载模式

/books?includes[]=author:sideload

将 Author 数组分离成另一个单独的数组。在 Book 中仍将包含 Author 的id。

请参阅Duongld\Architect的README中的预加载部分

分页

有两个参数： limit 和 page。 limit 将确定每页的记录数量，而 page 将确定当前页。

/books?limit=10&;page=3

将返回从30到40的book记录。

排序

应定义为排序规则数组。它们将按定义的顺序应用。

排序规则

示例

[
    {
        "key": "title",
        "direction": "ASC"
    }, {
        "key": "year",
        "direction": "DESC"
    }
]

这将导致书籍按书名升序排序，然后按年份降序排序。

过滤

应定义为过滤组数组。

过滤组

过滤器

运算符

特殊值

自定义过滤器（请参阅下面的英文文档）

可选的简写过滤语法（请参阅下面的英文文档）

Bruno ENGLISH

简介

A Laravel base controller class and a trait that will enable to add filtering, sorting, eager loading and pagination to your resource URLs.

Dedicated to Giordano Bruno

This package is named after my hero Giordano Bruno. A true visionary who dared to dream beyond what was thought possible. For his ideas and his refusal to renounce them he was burned to the stake in 1600. I highly recommend this short cartoon on his life narrated by Neil deGrasse Tyson.

功能

• Parse GET parameters for dynamic eager loading of related resources, sorting and pagination
• Advanced filtering of resources using filter groups
• 使用 duongld\Architect 进行相关资源的侧载、ID 加载或嵌入加载。
• ... 欢迎在这里提出新功能想法 Ideas for new functionality is welcome here

教程

要开始使用 Bruno，我强烈推荐我的关于 Laravel API 中资源控制的文章：resource controls in Laravel APIs

安装

composer require duongld/bruno

用法

以下示例将使用假设的资源端点 /books，该端点将返回一个包含 Book 的集合，每个 Book 都属于一个 Author。

Book n ----- 1 Author

可用的查询参数

实现

<?php

namespace App\Http\Controllers;

use Duongld\Api\Controller\EloquentBuilderTrait;
use Duongld\Api\Controller\LaravelController;
use App\Models\Book;

class BookController extends LaravelController
{
    use EloquentBuilderTrait;

    public function getBooks()
    {
        // Parse the resource options given by GET parameters
        $resourceOptions = $this->parseResourceOptions();

        // Start a new query for books using Eloquent query builder
        // (This would normally live somewhere else, e.g. in a Repository)
        $query = Book::query();
        $this->applyResourceOptions($query, $resourceOptions);
        $books = $query->get();

        // Parse the data using Optimus\Architect
        $parsedData = $this->parseData($books, $resourceOptions, 'books');

        // Create JSON response of parsed data
        return $this->response($parsedData);
    }
}

语法文档

预加载

简单预加载

/books?includes[]=author

将返回一个包含 5 个 Book 的集合，这些 Book 已经预加载了 Author。

IDs模式

/books?includes[]=author:ids

将返回一个包含 Book 的集合，这些 Book 已经预加载了它们 Author 的 ID。

侧加载模式

/books?includes[]=author:sideload

将返回一个包含 Book 的集合和根作用域中预加载的它们 Author 的集合。

有关 Optimus\Architect 的 README 中的预加载类型更多信息

分页

有两个参数可用：limit 和 page。 limit 将确定每页的记录数，而 page 将确定当前页。

/books?limit=10&;page=3

将返回第 30-40 本书籍。

排序

应定义为排序规则的数组。它们将按照定义的顺序应用。

排序规则

示例

[
    {
        "key": "title",
        "direction": "ASC"
    }, {
        "key": "year",
        "direction": "DESC"
    }
]

将按标题升序排序书籍，然后按年份降序排序。

过滤

应定义为过滤组的数组。

过滤组

过滤器

运算符

特殊值

自定义过滤器

记住我们的关系 Books n ----- 1 Author。假设你想通过 Author 名称过滤书籍。

[
    {
        "filters": [
            {
                "key": "author",
                "value": "Optimus",
                "operator": "sw"
            }
        ]
    }
]

现在这很好，但是我们的模型上没有 author 属性，因为它是一个关系。这会导致错误，因为 Eloquent 会尝试在一个不存在的 author 属性上使用 where 子句。我们可以通过实现自定义过滤器来修复这个问题。在任何使用 EloquentBuilderTrait 的地方，实现一个名为 filterAuthor 的函数

public function filterAuthor(Builder $query, $method, $clauseOperator, $value)
{
    // if clauseOperator is idential to false,
    //     we are using a specific SQL method in its place (e.g. `in`, `between`)
    if ($clauseOperator === false) {
        call_user_func([$query, $method], 'authors.name', $value);
    } else {
        call_user_func([$query, $method], 'authors.name', $clauseOperator, $value);
    }
}

注意：需要注意的是，自定义过滤器将查找与属性同名的关联。例如，如果尝试对名为 author 的属性使用自定义过滤器，那么 Bruno 将尝试从 Book 模型中预加载 author 关联。

自定义过滤器函数

示例

[
    {
        "or": true,
        "filters": [
            {
                "key": "author",
                "value": "Optimus",
                "operator": "sw"
            },
            {
                "key": "author",
                "value": "Prime",
                "operator": "ew"
            }
        ]
    }
]

作者姓名以 Optimus 开头或以 Prime 结尾的书籍。

[
    {
        "filters": [
            {
                "key": "author",
                "value": "Brian",
                "operator": "sw"
            }
        ]
    },
    {
        "filters": [
            {
                "key": "year",
                "value": 1990,
                "operator": "gt"
            },
            {
                "key": "year",
                "value": 2000,
                "operator": "lt"
            }
        ]
    }
]

作者姓名以 Brian 开头且出版年份在 1990 年至 2000 年之间的书籍。

可选简写过滤语法（简写）

过滤器可以可选地以简写形式表达，它将给定一个给定过滤器数组 [key, operator, value, not(optional)] 并在评估时构建一个详尽的过滤器数组。

例如，以下过滤器组（详尽）

[
    {
        "or": false,
        "filters": [
            {
                "key": "author",
                "value": "Optimus",
                "operator": "sw"
            },
            {
                "key": "author",
                "value": "Prime",
                "operator": "ew"
            },
            {
                "key": "deleted_at",
                "value": null,
                "operator": "eq",
                "not": true
            }
        ]
    }
]

可以以这种方式表达（简写）

[
    {
        "or": false,
        "filters": [
            ["author", "sw", "Optimus"],
            ["author", "ew", "Prime"],
            ["deleted_at", "eq", null, true]
        ]
    }
]

标准

此包符合 PSR-1、PSR-2 和 PSR-4。如果您发现合规性问题，请通过拉取请求发送补丁。

贡献

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

许可证

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