README

另一个帮助您快速开始使用JSON:API的Laravel包。

此包背后的想法是尽可能简化使用Laravel资源轻松启动和运行JSON:API。

目录

• 安装
• 基本使用
  • 使用JsonApiResourceInterface
  • 使用ConvertibleToJsonApiResourceInterface
  • 资源集合
• 加载包含。 (尚待文档化)
• 提取包含的资源。 (尚待文档化)
• 分页和筛选。 (尚待文档化)
• 变更日志

安装

composer require garbetjie/laravel-jsonapi

基本使用

为了使用此包生成JSON:API资源，只需从您的控制器方法中返回一个Garbetjie\Laravel\JsonApi\JsonApiResource实例。

这可以通过创建扩展JsonApiResource的自定义资源，或者通过直接创建一个JsonApiResource的新实例并传递一个可转换为资源的值来完成（请参阅以下部分了解如何操作）。

使用JsonApiResourceInterface

当实现Garbetjie\Laravel\JsonApi\JsonApiResourceInterface时，实现该接口的对象直接负责将自己表示为JSON:API资源。这意味着任何对象都可以用来表示JSON:API资源。

最简单的方法是确保一个Eloquent资源的实例实现了此接口，因为有一些辅助方法可以更轻松地处理Eloquent模型。

资源定义

<?php

use Garbetjie\Laravel\JsonApi\JsonApiResource;
use Garbetjie\Laravel\JsonApi\JsonApiResourceInterface;
use Illuminate\Http\Resources\MissingValue;

/**
 * @property User $resource
 */
class UserResource extends JsonApiResource implements JsonApiResourceInterface
{
    public function getJsonApiId() {
        return $this->resource->getKey();
    }

    public function getJsonApiLinks($request) {
        return new MissingValue();
    }

    public function getJsonApiMeta($request) {
        return [
            'loginCount' => 1,
            'logoutCount' => new MissingValue(),
        ];
    }

    public function getJsonApiAttributes($request) {
        return [
            'name' => $this->resource->first_name,
            'displayName' => trim("{$this->resource->first_name} {$this->resource->last_name}"),
            'attribute' => $this->resource->has_attribute ? $this->resource->has_attribute : new MissingValue(),
        ];
    }

    public function getJsonApiType() {
        return 'users';
    }

    public function getJsonApiRelationships($request) {
        return [
            'logins' => [
                'data' => [
                    ['type' => 'logins', 'id' => 1]
                ],
                'links' => [
                    'related' => "/users/{$this->getJsonApiId()}/logins"
                ], 
            ],
        ];
    }
}

用法

<?php
class UsersController extends Controller
{
    public function index()
    {
        $user = User::findOrFail(1);

        return new UserResource($user);
    }

}

使用ConvertibleToJsonApiResourceInterface

当实现Garbetjie\Laravel\JsonApi\ConvertibleToJsonApiResourceInterface时，您本质上是将资源转换的实现委托给另一个对象（通常实现JsonApiResourceInterface接口的对象）。

这对于您的Model实例特别有用，您可能不想直接实现JsonApiResourceInterface接口，但仍然希望您的模型能够表示为JSON:API资源。

在上一个示例的基础上，下面提供了一个示例

定义

<?php

class User extends Model implements ConvertibleToJsonApiResourceInterface
{
    public function convertToJsonApiResource() : JsonApiResourceInterface
    {
        return new UserResource($this);
    }
}

使用集合

处理资源集合与处理单个资源并没有太大区别。您无需创建资源的新实例，只需使用下面的::collection()静态方法即可。

集合中提供的所有项都需要实现JsonApiResourceInterface或ConvertibleToJsonApiResourceInterface接口，以便在输出中显示。

<?php
class UsersController extends Controller
{
    public function index()
    {
        return UserResource::collection(User::query()->all());
        // or
        return UserResource::collection(User::paginate(15));
    }
}

变更日志

• 0.8.1

  • 修正所需的PHP版本 - 删除7.2版本，并添加7.3和7.4版本。

• 0.8.0

  • 修复了分页参数丢失的bug，并添加了相关测试。
  • 添加了配置参数以自动去除null分页链接。

• 0.7.1

  • 添加了对Laravel 8的支持。

• 0.7.0

  • 添加更多测试以捕获传递给包含加载器和提取器的值。
  • 确保包含加载器和提取器总是接收到原始对象的集合，而不是资源的集合。

• .0.6.1

  • 移除导致错误的函数参数后的逗号。

• 0.6.0

  • 重构分页配置以使用策略。
  • 添加include_mode配置，该配置确定如何处理无效的包含项。

• 0.5.0

  • 重命名多个类和接口以提供更好的可读性。
  • 更新README以提供更多使用信息。

• 0.4.0

  • 添加JsonApi外观以及用于提取过滤器和分页参数的jsonapi()辅助函数。
  • 修复了将MissingValue实例作为额外属性中的数组成员传递的bug。