README

状态

这是一个对neomerx/json-api的维护分支。它被用于Laravel JSON:API。

虽然我们使用这个包来构建Laravel JSON:API，但它仍然是无框架的。我们没有任何计划改变这一点。所以你可以在任何PHP应用程序中使用它。

描述

一个好的API是提高客户体验最有效的方法之一。数据格式和通信协议的标准方法可以提高生产力并使应用程序之间的集成更加顺畅。

这个无框架的包实现了JSON API规范版本 v1.1，并有助于集中精力在核心应用程序功能上，而不是在协议实现上。它支持文档结构、错误、数据获取，如JSON API Format中所述，并涵盖了解析和检查HTTP请求参数和头部的功能。例如，它有助于正确响应无效请求的Unsupported Media Type（HTTP代码 415）和Not Acceptable（HTTP代码 406）。你不需要在每个请求上手动验证所有输入参数。你可以配置你的服务支持哪些参数，并且这个包将自动检查传入的请求。这大大简化了API开发并完全支持规范。特别是

• 资源属性和关系
• 多态资源数据和关系
• 包含相关资源的复合文档（支持循环资源引用）
• 文档、资源、错误、关系和链接对象元信息
• 配置文件
• 根据RFC 7231解析HTTP Accept和Content-Type头部
• 解析HTTP查询参数（例如分页、排序等）
• 稀疏字段集和自定义包含路径
• 错误

高代码质量且具有100%测试覆盖率的测试用例超过150个。适用于生产。

要了解更多信息，请查看Wiki和示例应用程序.

“我很喜欢它如何使快速实现API变得如此简单”

– Jeremy Cloutier

全栈集成

这个包是无框架的，如果你在寻找实际使用的示例，你可能对快速启动JSON API服务器应用程序Limoncello App感兴趣。

服务器支持

• 一些示例数据模型和用户的CRUD操作。
• 对API服务器的跨源请求（CORS）。
• 认证（Bearer令牌）和授权CRUD操作。
• 支持资源包含、分页等JSON API功能。

示例用法

假设你有一个$author类型为\Author的实例，你可以像这样将其编码为JSON API

$encoder = Encoder::instance([
        Author::class => AuthorSchema::class,
    ])
    ->withUrlPrefix('http://example.com/api/v1')
    ->withEncodeOptions(JSON_PRETTY_PRINT);

echo $encoder->encodeData($author) . PHP_EOL;

将输出

{
    "data" : {
        "type"       : "people",
        "id"         : "123",
        "attributes" : {
            "first-name": "John",
            "last-name": "Doe"
        },
        "relationships" : {
            "comments" : {
                "links": {
                    "related" : "http://example.com/api/v1/people/123/comments"
                }
            }
        },
        "links" : {
            "self" : "http://example.com/api/v1/people/123"
        }
    }
}

AuthorSchema提供了关于资源属性的信息，可能看起来像这样

class AuthorSchema extends BaseSchema
{
    public function getType(): string
    {
        return 'people';
    }

    public function getId($author): ?string
    {
        return $author->authorId;
    }

    public function getAttributes($author, ContextInterface $context): iterable
    {
        return [
            'first-name' => $author->firstName,
            'last-name'  => $author->lastName,
        ];
    }

    public function getRelationships($author, ContextInterface $context): iterable
    {
        return [
            'comments' => [
                self::RELATIONSHIP_LINKS_SELF    => false,
                self::RELATIONSHIP_LINKS_RELATED => true,

                // Data include supported as well as other cool features
                // self::RELATIONSHIP_DATA => $author->comments,
            ],
        ];
    }
}

参数 http://example.com/api/v1 是一个URL前缀，它将应用于所有编码链接，除非设置了不添加前缀的标志。

参数 JSON_PRETTY_PRINT 是PHP预定义的 JSON常量。

一个包含多个、嵌套、过滤对象和更多内容的示例程序 在这里。

有关更高级的用法，请参阅 Wiki.

版本

当前版本是 4.x（PHP 7.1+），对于较旧的PHP（PHP 5.5 - 7.0，HHVM），请使用版本 1.x。

有问题？

请勿犹豫，检查 问题 或发布一个新的问题。

需要帮助？

您计划添加JSON API并需要帮助吗？我们很乐意与您 [email protected] 联系。

贡献

如果您发现任何未反映在此软件包中的规范变更，请发布一个 问题。欢迎对文档和代码改进的拉取请求。

有 2 种方式发送拉取请求

• 小拉取请求应发送到 develop 分支，作为 1 个提交
• 对于较大的拉取请求（例如，新功能），建议创建一个 issue 请求为该功能创建新分支。当创建了一个名为 feature/issueXX 的新分支（其中 XX 是问题号）时，您应向该分支提交拉取请求。当功能完成时，该分支将被压缩并合并到 develop 和 master 分支。

许可

Apache许可证（版本 2.0）。请参阅 许可证文件 了解更多信息。