— y2sunlight 2020-06-23

本章は、若干の補足を加筆してはいるものの単にPSRのサイトを日本語に翻訳したものに過ぎません。英語が堪能な方は原文をご参照下さい。翻訳に当たっては、基本的に機械翻訳を使い、理解できない部分は独断で意訳しております。拙い訳では御座いますが恥を忍んで投稿しておりますので、ご指摘など御座いましたらコメントを頂ければ幸いです。

関連記事

• PSR - PHP標準勧告
• PSR-1: Basic Coding Standard - 基本コーディング規約
• PSR-3: Logger Interface - ロガーインターフェイス
• PSR-4: Autoloading Standard - オートローディング規約
• PSR-5: PHPDoc Standard(Draft) - PHPDoc規約
• PSR-6: Caching Interface - キャッシングインターフェイス
• PSR-7: HTTP Message Interface - HTTPメッセージインターフェイス
• PSR-11: Container Interface - コンテナインターフェイス
• PSR-12: Extended Coding Style - 拡張コーディングスタイル
• PSR-13: Link definition interfaces - リンク定義インターフェース
• PSR-14: Event Dispatcher - イベントディスパッチャー
• PSR-15: HTTP Server Request Handlers - HTTPサーバーリクエストハンドラー
• PSR-16: Common Interface for Caching Libraries - キャッシングライブラリのための共通インターフェース
• PSR-17: HTTP Factories - HTTPファクトリー
• PSR-18: HTTP Client - HTTPクライアント
• PSR-19: PHPDoc tags(Draft) - PHPDocタグ

— 原文より翻訳 PSR-15: HTTP Server Request Handlers 2020-07-28 現在

このドキュメントでは、PSR-7またはその後の代替PSRで説明されているHTTPメッセージを使用するHTTPサーバーリクエストハンドラー（「リクエストハンドラー」）とHTTPサーバーミドルウェアコンポーネント（「ミドルウェア」）の一般的なインターフェースについて説明します。

HTTPリクエストハンドラーは、あらゆるWebアプリケーションの基本的な部分です。サーバー側コードは、リクエストメッセージを受信して処理し、応答メッセージを生成します。HTTPミドルウェアは、一般的なリクエストとレスポンスの処理をアプリケーション層から分離するための方法の１つです。

このドキュメントで説明するインターフェースは、リクエストハンドラーとミドルウェアを抽象化したものです。

注：「リクエストハンドラー」および「ミドルウェア」へのすべての参照は、サーバーリクエスト処理に固有なものです。

このドキュメントのキーワード MUST , MUST NOT , REQUIRED , SHALL , SHALL NOT , SHOULD , SHOULD NOT , RECOMMENDED , MAY 及び OPTIONAL は、 RFC 2119で説明されているように解釈して下さい。

RFC 2119の説明
MUST, REQUIRED, SHALL — 絶対必要
MUST NOT, SHALL NOT — 絶対禁止
SHOULD, RECOMMENDED — 推奨（但し、無視できる特定の正当な理由が存在するかもしれない）
SHOULD NOT — 推奨できない（但し、許可できる特定の正当な理由が存在するかもしれない）
MAY, OPTIONAL — オプション

• PSR-7　・・・　HTTP message interfaces
• RFC 2119　・・・　Key words for use in RFCs to Indicate Requirement Levels

リクエストハンドラーは、PSR-7で定義されているように、リクエストを処理して応答を生成する個別のコンポーネントです。

リクエスト条件によりリクエストハンドラーがレスポンスを生成できない場合、リクエストハンドラーは例外をスローする場合があります( MAY )。例外のタイプは定義されていません。

この規約を使用するリクエストハンドラーは、次のインターフェースを実装する必要があります( MUST )：

• Psr\Http\Server\RequestHandlerInterface

ミドルウェアコンポーネントは個別のコンポーネントですが、PSR-7で定義されているように、着信要求の処理と結果応答の作成に他のミドルウェアコンポーネントと一緒に参加することが多いです。

ミドルウェアコンポーネントは、十分な条件が満たされている場合、リクエストハンドラーに委任することなく応答を作成して返すことができます( MAY )。

この規約を使用するミドルウェアは、次のインターフェースを実装する必要があります( MUST )：

• Psr\Http\Server\MiddlewareInterface

応答を生成するミドルウェアまたはリクエストハンドラーは、PSR-7の ResponseInterface プロトタイプ または ResponseInterface インスタンスを生成できるファクトリーを構成することをお勧めします( RECOMMENDED )。それは、特定のHTTPメッセージの実装への依存を防ぐためです。

ミドルウェアを使用するアプリケーションは、例外をキャッチしてそれらをレスポンスに変換するコンポーネントを含むことが推奨されます( RECOMMENDED )。このミドルウェアは、最初に実行されるコンポーネントであり、全ての他の処理をラップすべきです( SHOULD )。それは、レスポンスが常に生成されることを保証するためです。

リクエストハンドラーは次のインターフェースを実装する必要があります( MUST )。

RequestHandlerInterface.php

namespace Psr\Http\Server;
 
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
 
/**
 * サーバーリクエストを処理し、レスポンスを生成します。
 *
 * HTTPリクエストハンドラーは、HTTPレスポンスを生成するためにHTTPリクエストを処理します。
 */
interface RequestHandlerInterface
{
    /**
     * リクエストを処理し、レスポンスを生成します。
     *
     * レスポンスを生成するために、他の協調するコードを呼び出すことができます。
     */
    public function handle(ServerRequestInterface $request): ResponseInterface;
}

互換性のあるミドルウェアコンポーネントは次のインターフェースを実装する必要があります( MUST )。

MiddlewareInterface.php

namespace Psr\Http\Server;
 
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
 
/**
 * サーバーのリクエストとレスポンスを処理する参加者。
 *
 * HTTPミドルウェアコンポーネントは、HTTPメッセージの処理に参加します：
 * つまり、リクエストに基づいて動作するか、レスポンスを生成するか、
 * または　リクエストを後続のミドルウェアに転送し場合によってはそのレスポンスに基づいて動作します。
 */
interface MiddlewareInterface
{
    /**
     * 着信サーバー要求を処理します。
     *
     * レスポンスを生成するために、着信サーバーリクエストを処理します。
     * レスポンス自体を生成できない場合は、それをするのに提供されたリクエストハンドラーに委任します。
     */
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface;
}