README

描述

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

此不依赖框架的包实现了 JSON API 规范版本 v1.0，并帮助开发者专注于核心应用功能，而不是协议实现。它支持文档结构、错误、数据获取，如 JSON API 格式 中所述，并涵盖解析和检查 HTTP 请求参数和头信息。例如，它可以帮助正确响应无效请求的 Unsupported Media Type（HTTP 状态码 415）和 Not Acceptable（HTTP 状态码 406）。您无需在每个请求上手动验证所有输入参数。您可以配置服务支持哪些参数，并且此包将自动检查传入的请求。它极大地简化了 API 开发并完全支持规范。特别是

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

高代码质量和 100% 测试覆盖率，包含 250+ 测试。适用于生产环境。

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

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

—Jeremy Cloutier

全栈集成

此包不依赖框架，如果您想了解实际使用示例，您可能会对快速启动 JSON API 服务器应用程序 Limoncello App 感兴趣。

服务器支持

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

示例用法

假设您有一个 $author 类型的 \Author，您可以将它编码为 JSON API，如下所示

$encoder = Encoder::instance([
    '\Author' => '\AuthorSchema',
], new EncoderOptions(JSON_PRETTY_PRINT, 'http://example.com/api/v1'));

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

将输出

{
    "data": {
        "type": "people",
        "id": "123",
        "attributes": {
            "first_name": "John",
            "last_name": "Dow"
        },
        "links": {
            "self": "http://example.com/api/v1/people/123"
        }
    }
}

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

class AuthorSchema extends SchemaProvider
{
    protected $resourceType = 'people';

    public function getId($author)
    {
        /** @var Author $author */
        return $author->authorId;
    }

    public function getAttributes($author)
    {
        /** @var Author $author */
        return [
            'first_name' => $author->firstName,
            'last_name'  => $author->lastName,
        ];
    }
}

第一个 EncoderOptions 参数 JSON_PRETTY_PRINT 是 PHP 预定义的 JSON 常量。

第二个 EncoderOptions 参数 http://example.com/api/v1 是一个 URL 前缀，将应用于所有编码的链接，除非它们将 $treatAsHref 标志设置为 true。

有关更高级的使用方法，请查看 Wiki.

有问题吗？

请随时查看 问题 或发布一个新的问题。

需要帮助吗？

您计划添加JSON API并需要帮助吗？我们很乐意与您联系 sales@neomerx.com。

贡献

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

当前任务使用 Waffle.io 进行管理。

有 2 种方式发送拉取请求

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

许可证

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