README

Woohoo Labs. Yin Middleware 是一组中间件，帮助您将 Woohoo Labs. Yin 集成到您的 PHP 应用程序中。

目录

• 简介
• 安装
• 基本用法
• 版本控制
• 变更日志
• 测试
• 贡献
• 支持
• 鸣谢
• 许可协议

简介

特性

• 100% PSR-15 兼容性
• 100% PSR-7 兼容性
• 对 JSON 模式的请求验证
• 对 JSON 和 JSON:API 模式的响应验证
• 调度 JSON:API 意识控制器
• JSON:API 异常处理

安装

开始之前，您需要的是 Composer。

安装 PSR-7 实现

由于 Yin Middleware 需要 PSR-7 实现（一个提供 psr/http-message-implementation 虚拟包的包），您必须先安装一个。您可以使用 Zend Diactoros 或您偏好的任何库

$ composer require zendframework/zend-diactoros

安装 Yin Middleware

要安装此库的最新版本，请运行以下命令

$ composer require woohoolabs/yin-middleware

注意：默认情况下，测试和示例不会被下载。如果您需要它们，您必须使用 composer require woohoolabs/yin-middleware --prefer-source 或克隆存储库。

Yin Middleware 4.1 至少需要 PHP 7.4，但您可以使用 Yin Middleware 4.0.0 用于 PHP 7.1。

安装可选依赖项

如果您想使用默认中间件堆栈中的 JsonApiRequestValidatorMiddleware 和 JsonApiResponseValidatorMiddleware，则还必须要求以下依赖项

$ composer require seld/jsonlint
$ composer require justinrainbow/json-schema

基本用法

支持的中间件接口设计

Yin-Middleware 的接口设计基于 PSR-15 实际标准。这就是为什么它与 Woohoo Labs. Harmony、Zend-Stratigility、Zend-Expressive 以及许多其他框架兼容。

以下部分将指导您如何使用和配置提供的中间件。

注意：当将 ServerRequestInterface 实例传递给您的中间件调度器时，实际上必须使用 WoohooLabs\Yin\JsonApi\Request\JsonApiRequestInterface 实例（可能是 WoohooLabs\Yin\JsonApi\Request\JsonApiRequest 类），否则 JsonApiDispatcherMiddleware 和 JsonApiExceptionHandlerMiddleware 将抛出异常。

YinCompatibilityMiddleware

此中间件简化了在其他框架中使用 Yin 和 Yin-Middleware 的过程。它通过将基本的 PSR-7 请求对象升级到 JsonApiRequest（适合与 Yin 一起使用）来实现这一点。请注意，此中间件应位于任何使用 JsonApiRequest 作为 $request 参数的其他中间件之前。

$harmony->addMiddleware(new YinCompatibilityMiddleware());

中间件的可用配置选项（它们可以传递给构造函数）

• exceptionFactory：要使用的 ExceptionFactoryInterface 实例
• 反序列化器：要使用的 DeserializerInterface 实例

JsonApiRequestValidatorMiddleware

此中间件主要用于开发环境，能够验证 PSR-7 请求是否符合 JSON 和 JSON:API 规范。只需将其添加到您的应用程序中（示例为 Woohoo Labs. Harmony）

$harmony->addMiddleware(new JsonApiRequestValidatorMiddleware());

如果验证失败，将抛出一个包含适当 JSON:API 错误的异常。如果您想自定义错误消息或响应，请提供您自己的异常工厂。对于其他自定义，可以自由扩展该类。

中间件的可用配置选项（它们可以传递给构造函数）

• exceptionFactory：要使用的 ExceptionFactoryInterface 实例
• includeOriginalMessageInResponse：如果为 true，则原始请求体将被包含在 "meta" 顶级成员中
• negotiate：如果为 true，则中间件将执行 JSON:API 规范中指定的内容协商。在这种情况下，将检查 "Content-Type" 和 "Accept" 头部。
• validateQueryParams：如果为 true，则查询参数将根据 JSON:API 规范进行验证
• validateJsonBody：如果为 true，则请求体将根据 JSON 规范进行验证

JsonApiResponseValidatorMiddleware

此中间件主要用于开发环境，能够验证 PSR-7 响应是否符合 JSON 和 JSON:API 规范。只需将其添加到您的应用程序中（示例为 Woohoo Labs. Harmony）

$harmony->addMiddleware(new JsonApiResponseValidatorMiddleware());

如果验证失败，将抛出一个包含适当 JSON:API 错误的异常。如果您想自定义错误消息或响应，请提供您自己的异常工厂。对于其他自定义，可以自由扩展该类。

中间件的可用配置选项（它们可以传递给构造函数）

• exceptionFactory：要使用的 ExceptionFactoryInterface 实例
• serializer：要使用的 SerializerInterface 实例
• includeOriginalMessageInResponse：如果为 true，则原始响应将被包含在 "meta" 顶级成员中
• validateJsonBody：如果为 true，则响应体将根据 JSON 规范进行验证
• validateJsonApiBody：如果为 true，则响应将根据 JSON:API 规范进行验证

JsonApiDispatcherMiddleware

此中间件能够调度具有 JSON:API 意识的控制器。只需将其添加到您的应用程序中（示例为 Woohoo Labs. Harmony）

$harmony->addMiddleware(new JsonApiDispatcherMiddleware());

此中间件的工作方式与 Woohoo Labs. Harmony 中的中间件完全相同，唯一的区别是它使用以下签名调度控制器操作

public function myAction(JsonApi $jsonApi): ResponseInterface;

而不是

public function myAction(ServerRequestInterface $request, ResponseInterface $response): ResponseInterface;

差异微妙，因为 $jsonApi 对象包含一个与 PSR-7 兼容的请求，并且可以使用它创建 PSR-7 响应。有关更多详细信息，请参阅 Woohoo Labs. Yin 的文档。

中间件的可用配置选项（它们可以传递给构造函数）

• container：用于实例化控制器的 PSR-11 兼容 容器实例
• exceptionFactory：要使用的 ExceptionFactoryInterface 实例（例如：在调度失败时使用）
• serializer：要使用的 SerializerInterface 实例
• handlerAttribute：存储可调度的控制器的请求属性名称（通常由路由器提供）。

JsonApiExceptionHandlerMiddleware

它捕获异常，并返回适当的 JSON:API 错误响应。

中间件的可用配置选项（它们可以传递给构造函数）

• errorResponsePrototype：在发生错误时，此响应对象将被操作并返回
• catching：如果为 false，则中间件不会捕获 JsonApiException
• verbose：如果为 true，则将提供有关抛出的异常的额外元信息
• exceptionFactory：要使用的 ExceptionFactoryInterface 实例
• serializer：要使用的 SerializerInterface 实例

版本控制

此库遵循 SemVer v2.0.0。

变更日志

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

测试

Woohoo Labs. Yin Middleware 包含一个 PHPUnit 测试套件。要运行测试，请在将 phpunit.xml.dist 复制为 phpunit.xml 后，从项目文件夹中运行以下命令：

$ phpunit

此外，您也可以运行 docker-compose up 或 make test 来执行测试。

贡献

请参阅 CONTRIBUTING 获取详细信息。

支持

请参阅 SUPPORT 获取详细信息。

鸣谢

• Máté Kocsis
• 所有贡献者

许可协议

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