README

此包包含以下兼容中继的中间件

• ExceptionHandler 用于处理后续中间件的异常
• FormContentHandler 用于反序列化 PSR-7 请求的 URL 编码有效负载
• JsonContentHandler 用于反序列化 PSR-7 请求的 JSON 有效负载
• JsonDecoder 用于反序列化 PSR-7 请求的 JSON 有效负载（已废弃）
• ResponseSender 用于发送 PSR-7 响应
• SessionHeadersHandler 用于“手动”管理会话头，而不是 PHP 自动管理
• StatelessExceptionHandler 用于处理后续中间件的异常（适合多个请求/响应周期）

此包可通过 Composer 以 relay/middleware 的方式安装和 PSR-4 自动加载。

ExceptionHandler

同样，ExceptionHandler 做的是它的名字所暗示的事情：它会捕获通过后续中间件装饰器冒泡上来的任何异常。

ExceptionHandler 对 $request 或 $response 不做任何处理，并将它们直接传递给 try/catch 块内的 $next。如果没有异常冒泡，它将返回 $next 的 $response。然而，如果它捕获到异常，它将返回一个包含异常消息和 HTTP 500 状态码的新 $response 对象。然后它返回新的 $response 对象。

ExceptionHandler 旨在放在 Relay 队列的顶部附近，但在 ResponseSender 之后，这样 ResponseSender 就可以发送返回的 $response。

要将 ExceptionHandler 添加到您的队列，直接用空的 $response 实现对象实例化...

$queue[] = new \Relay\Middleware\ExceptionHandler(new ResponseImplementation());

... 或者使用您选择的 $resolver 从 $queue 实例化它。

FormContentHandler

FormContentHandler 几乎与下文的 JsonContentHandler 完全相同，但它解析 Content-Type 为 application/x-www-form-urlencoded 的请求的有效负载。

JsonContentHandler

同样，JsonContentHandler 做的是它听起来像的事情：它会反序列化 PSR-7 请求对象的 JSON 有效负载，并将参数提供给后续中间件装饰器。

JsonContentHandler 会检查传入的请求是否不是 GET 方法，并且是否有 application/json 或 application/vnd.api+json 的 Content-Type 头。如果找到这两个条件，它会解析 JSON 并将其作为 $request 的 解析后的主体 提供给后续中间件装饰器。如果方法是 GET 或 Content-Type 头定义了不同的 mime 类型，则 JsonContentHandler 忽略 $request 并继续链式处理。

要将 JsonContentHandler 添加到您的队列，直接实例化...

$queue[] = new \Relay\Middleware\JsonContentHandler();

... 或者使用您选择的 $resolver 从 $queue 实例化它。

要在后续中间件中访问解码的参数，请使用 $request 的 getParsedBody() 方法。

$decodedJsonData = $request->getParsedBody();

JsonDecoder

注意：此处理程序已被废弃，以利于 JsonContentHandler！

再次，JsonDecoder 做的正是其名字所暗示的：它将 PSR-7 请求对象的 JSON 负载数据反序列化，并将参数提供给后续的中间件装饰器。

JsonDecoder 会检查传入的请求是否为 GET 方法以外的请求，以及是否存在 application/json 的 Content-Type 头部。如果两者都存在，它将解码 JSON 并将其作为 $request 的 解析后的正文 提供出来，然后将其和 $response 一起传递给 $next。如果方法是 GET 或者 Content-Type 头部没有指定 application/json，则 JsonDecoder 对 $request 不做任何操作，并直接将其和 $response 传递给 $next。

要将 JsonDecoder 添加到您的队列中，直接实例化它...

$queue[] = new \Relay\Middleware\JsonDecoder();

... 或者使用您选择的 $resolver 从 $queue 实例化它。

要在后续中间件中访问解码的参数，请使用 $request 的 getParsedBody() 方法。

$decodedJsonData = $request->getParsedBody();

ResponseSender

ResponseSender 正如其名字所示，它只是发送 PSR-7 响应对象。

ResponseSender 对 $request 或 $response 不做任何处理，直接将它们传递给 $next。之后，它获取返回的 $response 并使用 header() 和 echo 发送它，然后返回发送的 $response。

ResponseSender 应该放在 Relay 队列的顶部，以便它是最后一个有机会对返回的响应进行操作的中间件。

要将 ResponseSender 添加到您的 Relay 队列中，直接实例化它 ...

$queue[] = new \Relay\Middleware\ResponseSender();

... 或者使用您选择的 $resolver 从 $queue 实例化它。

SessionHeadersHandler

通常，当调用 session_start() 时，PHP 会自动发送头部信息。然而，这意味着头部信息不是作为 PSR-7 响应对象的一部分发送的，因此不受您的控制。此处理程序通过将相关头部信息放入 PSR-7 响应中，将它们重新置于您的控制之下；其行为几乎与 PHP 的原生自动会话头部行为相同。

注意：为了使此中间件正常工作，您必须禁用 PHP 会话头部管理的 ini 设置。例如

ini_set('session.use_trans_sid', false);
ini_set('session.use_cookies', false);
ini_set('session.use_only_cookies', true);
ini_set('session.cache_limiter', '');

如果不这样做，处理程序将抛出 RuntimeException。

要将 SessionHeadersHandler 添加到您的队列中，直接实例化它...

$queue[] = new \Relay\Middleware\SessionHeadersHandler();

... 或者使用您选择的 $resolver 从 $queue 实例化它。

实例化时，您可以将 缓存限制器 值作为第一个构造函数参数传递。允许的值是 'nocache'、'public'、'private_no_cache' 或 'private'。如果您根本不想传递任何缓存限制器头部，请传递空字符串 ''。默认值为 'nocache'。

您还可以传递一个 缓存过期 值，单位为分钟，作为第二个构造函数参数。默认值为 180 分钟。

StatelessExceptionHandler

StatelessExceptionHandler 的行为与 ExceptionHandler 相同。区别在于它适合在可能多次使用的环境中使用。

要将 StatelessExceptionHandler 添加到您的队列中，直接使用可以创建 $response 对象的工厂实例化它 ...

$responseFactory = function () {
    return new ResponseImplementation();
};

$queue[] = new \Relay\Middleware\StatelessExceptionHandler($responseFactory);