README

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

目录

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

介绍

功能

• 100% PSR-15 兼容性
• 100% PSR-7 兼容性
• 根据 JSON 模式验证请求
• 根据 JSON 和 JSON:API 模式验证响应
• 调度 JSON:API 感知控制器
• JSON:API 异常处理

安装

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

安装 PSR-7 实现

因为 Yin 中间件需要 PSR-7 实现（一个提供 psr/http-message-implementation 虚拟包的软件包），您必须首先安装一个。您可以使用 Zend Diactoros 或您喜欢的任何其他库

$ composer require zendframework/zend-diactoros

安装 Yin 中间件

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

$ composer require woohoolabs/yin-middleware

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

Yin 中间件 4.1 至少需要 PHP 7.4，但您可以使用 Yin 中间件 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 实例
• deserializer：要使用的 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）。有关更多信息，请参阅许可文件。