README

一个PHP包，用于将远程 {json:api} 资源映射到Eloquent模型和集合。

@todo 这份文档需要更新。

从 1.0.x 升级到 1.2.x

依赖项 swisnl/json-api-client 已从 '0.10.x' 升级到 '0.20.x'，支持Lumen 5.8。在你的 ServiceProvider

将 use Swis\JsonApi\Client\Interfaces\ParserInterface; 替换为 use Swis\JsonApi\Client\Interfaces\ResponseParserInterface;
将 use Swis\JsonApi\Client\ItemDocumentSerializer; 替换为 use PXC\JsonApi\Client\ItemDocumentSerializerInterface;
相应地更改文件的其他部分。

安装

composer require pxc/json-api-client

注意。在安装此包之前，请确保已安装HTTP客户端，或者同时安装一个，例如 composer require swisnl/json-api-client php-http/guzzle6-adapter。

HTTP客户端

借助 PHP-HTTP，我们与任何HTTP消息客户端解耦。这需要另一个提供 php-http/client-implementation 的包。例如，要使用Guzzle 6，只需要求 php-http/guzzle6-adapter

composer require php-http/guzzle6-adapter

Laravel Service Provider

如果你正在使用Laravel < 5.5 或已禁用包自动发现，你必须将服务提供者添加到你的 config/app.php 文件中

'providers' => [
    ...,
    \Swis\JsonApi\Client\Providers\ServiceProvider::class,
],

入门

你可以简单地将客户端作为依赖项要求，并在你的类中使用它。这允许你，例如，创建一个使用 DocumentClient 的存储库

use Swis\JsonApi\Client\Interfaces\DocumentClientInterface;
use Swis\JsonApi\Client\Interfaces\ItemDocumentInterface;

class BlogRepository
{
    protected $client;

    public function __construct(DocumentClientInterface $client)
    {
        $this->client = $client;
    }

    public function all(array $parameters = [])
    {
        return $this->client->get('blogs?'.http_build_query($parameters));
    }

    public function create(ItemDocumentInterface $document, array $parameters = [])
    {
        return $this->client->post('blogs?'.http_build_query($parameters), $document);
    }

    public function find(string $id, array $parameters = [])
    {
        return $this->client->get('blogs/'.urlencode($id).'?'.http_build_query($parameters));
    }

    public function update(ItemDocumentInterface $document, array $parameters = [])
    {
        return $this->client->patch('blogs/'.urlencode($document->getData()->getId()).'?'.http_build_query($parameters), $document);
    }

    public function delete(string $id, array $parameters = [])
    {
        return $this->client->delete('blogs/'.urlencode($id).'?'.http_build_query($parameters));
    }
}

配置

以下是由此包提供的默认配置

return [
    /*
    |--------------------------------------------------------------------------
    | Base URI
    |--------------------------------------------------------------------------
    |
    | Specify a base uri which will be prepended to every URI.
    |
    | Default: empty string
    |
    */
    'base_uri' => '',
];

发布配置

如果你想更改默认配置，请发布并编辑配置文件

php artisan vendor:publish --provider="Swis\JsonApi\Client\Providers\ServiceProvider" --tag="config"

客户端

此包提供两个客户端；DocumentClient 和 Client。

DocumentClient

这是你通常使用的客户端。根据 JSON API规范，所有请求和响应都是文档。因此，此客户端始终期望在发布数据时输入一个 \Swis\JsonApi\Client\Interfaces\DocumentInterface，并且始终返回此相同接口。这可能是一个空的 Document，一个 ItemDocument 用于一个项目，一个 CollectionDocument 用于一个集合，或者一个 InvalidResponseDocument，当服务器以非2xx响应时。

DocumentClient 在内部遵循以下步骤

使用你的HTTP客户端发送请求；
使用 art4/json-api-client 解析和验证响应；
创建正确的文档实例；
使用与 TypeMapper 注册的项目模型或一个 \Swis\JsonApi\Client\Item 作为后备来为每个项目进行填充；
填充所有关系；
向文档中添加元数据，例如错误、链接和元数据。

客户端

这是一个更底层的客户端，可以用于例如发布二进制数据（如图片）。它可以接收你的请求工厂作为输入数据的所有内容，并返回被 \Swis\JsonApi\Client\Response 包装的 'raw' \Psr\Http\Message\ResponseInterface。它不解析或验证响应或填充项！

项

默认情况下，所有项都是 \Swis\JsonApi\Client\Item 的实例。该 Item 扩展了 jenssegers/model，它提供了一个类似于 Laravel Eloquent 的基类。请参阅其文档了解它提供的功能。您可以通过扩展 \Swis\JsonApi\Client\Item 或自行实现 \Swis\JsonApi\Client\Interfaces\ItemInterface 来定义自己的模型。如果您想定义例如隐藏属性、类型转换或获取/设置修改器，这将很有用。如果您使用自定义模型，您必须将其与 TypeMapper 注册。

关系

在 jenssegers/model 的基础上，此包实现了类似于 Laravel Eloquent 的关系。这些关系提供了一个流畅的接口来检索相关项。目前有四种关系可用

HasOneRelation
HasManyRelation
MorphToRelation
MorphToManyRelation

请参阅以下示例，了解如何定义关系

use Swis\JsonApi\Client\Item;

class AuthorItem extends Item
{
    protected $type = 'author';

    public function blogs()
    {
        return $this->hasMany(BlogItem::class);
    }
}

class BlogItem extends Item
{
    protected $type = 'blog';

    public function author()
    {
        return $this->hasOne(AuthorItem::class);
    }
}

集合

此包使用 Laravel Collections 作为项数组的包装器。

类型映射器

所有自定义模型都必须使用 TypeMapper 进行注册。正如其名称所示，此 TypeMapper 将 JSON API 类型映射到自定义项模型。

映射类型

您可以使用 \Swis\JsonApi\Client\TypeMapper 手动注册项，或使用提供的 \Swis\JsonApi\Client\Providers\TypeMapperServiceProvider

use Swis\JsonApi\Client\Providers\TypeMapperServiceProvider as BaseTypeMapperServiceProvider;

class TypeMapperServiceProvider extends BaseTypeMapperServiceProvider
{
    /**
     * A list of class names implementing \Swis\JsonApi\Client\Interfaces\ItemInterface.
     *
     * @var string[]
     */
    protected $items = [
        \App\Items\Author::class,
        \App\Items\Blog::class,
        \App\Items\Comment::class,
    ];
}

服务提供程序

此 \Swis\JsonApi\Client\Providers\ServiceProvider 注册了 TypeMapper、JsonApi\Parser 以及两个客户端： Client 和 DocumentClient。每个部分都可以被覆盖，以便进行扩展自定义。

绑定类型映射器

服务提供程序将 TypeMapper 注册为单例，因此您的整个应用程序都具有相同的映射。

绑定客户端

服务提供程序将 Client 和 DocumentClient 注册到您的应用程序。默认情况下，它使用 php-http/discovery 来查找 HTTP 客户端和消息工厂。您可以通过覆盖 getMessageFactory() 方法指定您自己的消息工厂，并通过覆盖 getHttpClient() 方法指定您自己的 HTTP 客户端。前者应返回一个消息工厂，后者应返回一个实现 HTTPlug 的 HTTP 客户端。这些方法是添加额外选项到您的 HTTP 客户端或为您的测试注册模拟 HTTP 客户端的最佳位置

protected function getHttpClient(): HttpClient
{
    if (app()->environment('testing')) {
        return new \Swis\Http\Fixture\Client(
            new \Swis\Http\Fixture\ResponseBuilder('/path/to/fixtures');
        );
    }

    return \Http\Adapter\Guzzle6\Client::createWithConfig(
        [
            'timeout' => 2,
        ]
    );
}

注意。此示例在测试环境中使用我们的 swisnl/php-http-fixture-client。此包允许您轻松使用静态固定值模拟请求。绝对值得一试！

如果您注册了自己的服务提供程序并使用包自动发现，请勿忘记在您的 package.json 中排除此包

"extra": {
  "laravel": {
    "dont-discover": [
      "swisnl/json-api-client"
    ]
  }
},

变更日志

请参阅 CHANGELOG 了解最近更改的更多信息。

测试

composer test

贡献

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

安全

如果您发现任何与安全相关的问题，请通过电子邮件security@swis.nl联系，而不是使用问题跟踪器。

许可证

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

SWIS

SWIS是一家位于荷兰莱顿的网页代理机构。我们热爱与开源软件合作。

pxc / json-api-client

维护者

详细信息