README

HATEOAS 允许您公开您的 REST API 的授权逻辑。此包使您能够轻松地将 HATEOAS 链接添加到 Laravel API 资源中。

每个资源都有自己的 HATEOAS 链接，并且仅返回每个资源可访问的链接。如果某个链接在资源上不可用，则您的 API 客户端可以禁用与该 HATEOAS 链接相关的功能。

默认情况下，以下格式的链接数组将被添加到 Laravel API 资源的 JSON 中

{
    "data": [
        {
            "id": 1,
            "text": "Hello world!",
            "_links": [
                {
                    "rel": "self",
                    "type": "GET",
                    "href": "https:///message/1"
                },
                {
                    "rel": "delete",
                    "type": "DELETE",
                    "href": "https:///message/1"
                }
            ]
        }
    ]
}

安装

您可以通过 composer 安装此包

composer require gdebrauwer/laravel-hateoas

用法

您可以使用以下 artisan 命令为模型创建一个新的 HATEOAS 类

php artisan make:hateoas MessageHateoas --model=Message

在创建的类中，您可以定义将用于生成链接的公共方法。方法应返回一个链接或 null。

class MessageHateoas
{
    use CreatesLinks;

    public function self(Message $message) : ?Link
    {
        if (! auth()->user()->can('view', $message)) {
            return;
        }

        return $this->link('message.show', ['message' => $message]);
    }

    public function delete(Message $message) : ?Link
    {
        if (! auth()->user()->can('delete', $message)) {
            return $this->link('message.archive', ['message' => $message]);
        }

        return $this->link('message.destroy', ['message' => $message]);
    }
}

要将链接添加到 API 资源中，您必须添加 HasLinks 特性并使用 $this->links() 方法。HATEOAS 类将自动发现。

class MessageResource extends JsonResource
{
    use HasLinks;

    public function toArray($request) : array
    {
        return [
            'id' => $this->id,
            'text' => $this->text,
            '_links' => $this->links(),
        ];
    }
}

自定义

格式化

您可以通过向 formatLinksUsing 方法提供实现 Formatter 接口的格式化器类来自定义 JSON 链接的格式。如果格式化链接的代码非常小，或者您不想为此创建单独的格式化器类，您还可以选择向 formatLinksUsing 方法提供格式化回调函数。

use GDebrauwer\Hateoas\Hateoas;
use GDebrauwer\Hateoas\LinkCollection;

// Provide your own Formatter class ...
Hateoas::formatLinksUsing(CustomFormatter::class);

// ... Or provide a callback
Hateoas::formatLinksUsing(function (LinkCollection $links) {
    // return array based on links
});

HATEOAS 类发现

默认情况下，模型的 HATEOAS 类将被自动发现。具体来说，HATEOAS 类必须位于包含模型的目录下的 Hateoas 目录中。如果您想提供自己的 HATEOAS 类发现逻辑，您可以注册自定义回调

use GDebrauwer\Hateoas\Hateoas;

Hateoas::guessHateoasClassNameUsing(function (string $class) {
    // return a HATEOAS class name
});

测试

composer test

代码风格检查

composer lint

变更日志

有关最近更改的更多信息，请参阅 变更日志

贡献

有关详细信息，请参阅 贡献指南

鸣谢

• Günther Debrauwer
• 所有贡献者

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅 许可证文件