README

介绍

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

献给Giordano Bruno

此软件包以我的英雄Giordano Bruno命名。他是一位真正的先知，敢于梦想超越想象的可能。由于他的思想和拒绝放弃这些思想，他在1600年被活活烧死。我强烈推荐观看这个关于他生平的短篇卡通，由Neil deGrasse Tyson配音（请点击观看）。

功能

解析GET参数以实现相关资源的动态预加载、排序和分页
使用过滤器组进行高级资源过滤
使用Optimus\Architect进行相关资源的侧载、ID加载或嵌入加载
... 欢迎在此处提出新的功能建议

教程

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

安装

适用于Laravel 5.3及以下版本

composer require phuongtt/bruno ~2.0

适用于Laravel 5.4及以上版本

composer require phuongtt/bruno ~3.0

使用方法

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

Book n ----- 1 Author

可用的查询参数

实现

<?php

namespace App\Http\Controllers;

use Phuongtt\Api\Controller\EloquentBuilderTrait;
use Phuongtt\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

将返回一个预加载了 Author 的5个 Book 集合。

ID模式

/books?includes[]=author:ids

将返回一个预加载了其 Author ID的 Book 集合。

侧载模式

/books?includes[]=author:sideload

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

分页

有两个参数可用：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(可选)]转换为在评估后的详细过滤器数组。

例如，这个过滤器组（详细）

[
    {
        "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标准。如果您发现符合标准上的疏忽，请通过拉取请求发送补丁。

测试

$ phpunit

贡献

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

许可

MIT许可（MIT）。有关更多信息，请参阅许可文件。

phuongtt / bruno

维护者

详细信息