README

一套用于轻松快速创建REST api的Laravel工具集。

要求

Yodo需要php 7.0或更高版本，并设计为与Laravel 5.5或更高版本协同工作。

安装

通过Composer

$ composer require ingruz/yodo

入门

假设您需要为Post模型创建CRUD（更准确地说，BREAD）处理器，您应该首先在您的app/Http/Controllers文件夹中创建一个PostController类。

<?php
use Ingruz\Yodo\Base\Controller;

class PostController extends Controller {}

然后，您应该告诉您的路由器使用该控制器来处理Post资源

Route::resource('posts', PostController::class);

这就完成了！现在您应该有一个完整的BREAD端点，支持分页、过滤、排序等更多功能！

用法

当然，您可以对Yodo的大部分行为进行自定义！

除了控制器之外，Yodo还有两个主要组件：仓库（Repositories）和转换器（Transformers）。默认情况下，Yodo将在app/Repositories文件夹中搜索自定义Repository，在app/Transformers文件夹中搜索自定义Transformer（未来这两个路径都将可自定义），使用控制器资源的名称进行搜索（例如，如果类名是PostController，它将分别搜索PostRepository和PostTransformer）。

您始终可以使用自定义路径或名称来指定它们，通过覆盖控制器中的受保护方法getRepositoryClass或getTransformerClass。

如果您没有指定任何内容，并且Yodo找不到合适的类，它将回退到默认的Repository和Transformer。在大多数情况下，您不需要自定义仓库，但对于转换器来说，这种情况会更为常见，因为默认的转换器将只返回一个模型数组。

仓库

要创建自定义仓库，只需扩展默认仓库

<?php
use Ingruz\Yodo\Base\Repository;

class PostRepository extends Repository {}

与控制器一样，默认情况下，仓库将搜索其模型类在您的根命名空间中（因此PostRepository将查找App\Post模型）。您始终可以通过覆盖getModelClass方法或直接传递实例到仓库的构造函数（也支持传递字符串形式的类名）来指定。

您可以通过许多方式自定义仓库的工作方式，特别是当处理由资源控制器中的index方法使用的getAll方法时。

• 静态 $eagerAssociations（默认为[]）：定义将自动预加载的关联列表；

• 静态 $defaultParams（默认为['limit' => 50]）：定义一个参数哈希，如果未在别处指定，则将传递给getAll方法；

• 静态 $defaultScopes（默认为[]）：定义应用于由getAll方法生成的查询的本地作用域列表；

• 静态 $filterParams（默认为[]）：定义在指定过滤参数（q）时将执行全文搜索的列列表；

• 静态 $queryParamsHandlers（默认为[]）：定义可能的查询参数哈希，可以映射到数据库列或由闭包处理，更详细的信息请参见以下章节；

• 静态 $orderParamsHandlers（默认为[]）：与$queryParamsHandler相同，但用于排序；

• 静态 $rules：在创建和更新阶段使用 Laravel 内置验证器定义一系列规则以验证模型，更详细的信息请参阅以下章节。

处理查询参数

此处定义的查询参数将被仓库自动处理，您可以在 $queryParamsHandlers 中将其定义为哈希，或者通过重写 getQueryParams 方法返回一个数组。

static $queryParamsHandlers = [
    'writer' => 'writer_id',
    'commentedByUser' => 'comments.user_id'
];

// ...

public function getQueryParams($requestParams) {
    $queryParams = parent::getQueryParams($requestParams);

    $queryParams['after'] = function($query, $params) {
        return $query->whereHas('comments', function($q) use($params) {
            $q->where('created_by', '>=', $params['after']);
        });
    };
    
    $queryParams['special'] = App\Resolvers\Post\SpecialParamResolver::class;

    return $queryParams;
}

因此，哈希的值可以是：

• 一个简单的字符串：将查询参数映射到模型数据库表的列上；
• 一个简单的字符串，但带有点（.）：将查询参数映射到相关模型数据库表的列上；
• 一个以 :: 开头的字符串，表示 Eloquent Scope，例如 ::active；
• 一个闭包，它接受当前的 $query 对象和查询参数数组，可以用于处理更复杂的情况；
• 一个表示扩展了基本 Ingruz\Yodo\Base\AbstractQueryParamsResolver 的类的字符串；

请求验证

可以指定一个数组，其中包含 Laravel 的验证规则，该规则将由仓库在创建和更新操作之前用于验证请求。

您可以将规则定义为纯数组

static $rules = [
    'title' => 'required|min:10',
    'date' => 'date'
];

或者只为特定操作定义规则

static $rules = [
    'create' => [
        'date' => 'date
    ]
];

或者定义始终需要检查的一般规则和针对特定操作的具体规则

static $rules = [
    'save' => [
        'title' => 'required|min:10'
    ],
    'create' => [
        'date' => 'date'
    ]
];

事件

设置模型事件的绝佳位置是仓库的 boot 方法

public function boot() {
    Post::created(function($model) {
        app('notifier')->notifyNewPost($model); // pseudo-code
    });
}

公共 API

• getModel：返回仓库模型的实例，这对于创建自定义方法很有用；
• getAll($params)：返回通过 $params 过滤、排序和分页的所有行；
• getById($id)：通过其 $id 返回一行；
• getFirstBy($key, $value, $operand)：获取匹配 where 子句的第一行；
• getManyBy($key, $value, $operand)：获取匹配 where 子句的所有行；
• create($data)：使用提供的 $data 创建一个新项目；
• update($item, $data)：使用提供的 $data 更新一个 $item（可以是实际实例或字符串 id）；
• delete($item)：从数据库中删除一个 $item。

转换器

Yodo 使用出色的 Fractal 库来处理模型的 JSON 转换。

要创建自定义转换器，只需扩展 Fractal 的 TransformerAbstract。

<?php
use League\Fractal;

class PostTransformer extends Fractal\TransformerAbstract
{
    public function transform(Post $post)
    {
        return [
            ...
        ];
    }
}

异常

Yodo 将自动根据以下两个异常返回错误响应

• ModelValidationException：如果创建或更新请求的负载不满足在仓库内部定义的验证规则，则将抛出此异常。将返回包含验证错误消息的响应，HTTP 状态码为 422；
• ApiLimitNotValidException：如果列表请求包含一个无效的限制（超过仓库中定义的 $limitCap 或设置为不允许的 0），则将抛出此异常。将返回 HTTP 状态码为 400 的响应。

自定义

要自定义 Yodo 的一些默认方面，您需要使用其服务提供程序。如果您使用的是 Laravel 5.5 或更高版本，您无需执行任何操作，包发现将为您包含它。

否则，只需将其添加到您的 config/app.php 文件的 providers 数组中

'providers' => [
    // ...

    Ingruz\Yodo\YodoServiceProvider::class
]

然后，您可以使用命令 php artisan vendor:publish 发布 yodo.php 配置文件。

在配置文件中，您可以自定义仓库和转换器命名空间根以及 Yodo 在出现 ModelValidationException 和 ApiLimitNotValidException 时返回的 HTTP 错误代码。

变更日志

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

测试

$ composer test

贡献

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

安全

如果您发现任何与安全相关的问题，请直接通过电子邮件联系作者，而不是使用问题跟踪器。

鸣谢

• Ingro

许可

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