【PHP】PSR-17 HTTP Factories（HTTPファクトリ）

RequestFactoryInterface

クライアントリクエストを作成する機能を持ちます。

namespace Psr\Http\Message;

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\UriInterface;

interface RequestFactoryInterface
{
    /**
     * 新しいリクエストを作成する
     *
     * @param string $method リクエストに関連付けられたHTTPメソッド
     * @param UriInterface|string $uri リクエストに関連付けられたURI
     */
    public function createRequest(string $method, $uri): RequestInterface;
}

ResponseFactoryInterface

レスポンスを作成する機能を持ちます。

namespace Psr\Http\Message;

use Psr\Http\Message\ResponseInterface;

interface ResponseFactoryInterface
{
    /**
     * 新しいレスポンスを作成する
     *
     * @param int $code HTTPステータスコード デフォルト=200
     * @param string $reasonPhrase 
     *      生成された応答のステータスコードに関連付ける理由フレーズ
     *      何も提供されない場合、実装はHTTP仕様で提案されているデフォルトを使用できる
     */
    public function createResponse(int $code = 200, string $reasonPhrase = ''): ResponseInterface;
}

ServerRequestFactoryInterface

サーバーリクエストを作成する機能を持ちます。

<?php
namespace Psr\Http\Message;

use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\UriInterface;

interface ServerRequestFactoryInterface
{
    /**
     * サーバーリクエストを作成する
     *
     * サーバーパラメーターは指定されたとおりに正確に取得されることに注意してください。
     * 指定された値の解析/処理は実行されません。 特に、HTTPメソッドまたはURIを決定する試みは行われません。
     * これらは明示的に提供する必要があります。
     *
     * @param string $method リクエストに関連付けられたHTTPメソッド
     * @param UriInterface|string $uri リクエストに関連付けられたURI
     * @param array $serverParams サーバーAPI（SAPI）パラメーターの配列
     */
    public function createServerRequest(string $method, $uri, array $serverParams = []): ServerRequestInterface;
}

StreamFactoryInterface

リクエストとレスポンスのストリームを作成する機能を持ちます。

<?php
namespace Psr\Http\Message;

use Psr\Http\Message\StreamInterface;

interface StreamFactoryInterface
{
    /**
     * 文字列から新しいストリームを作成する
     *
     * ストリームは一時リソースで作成する必要があります（SHOULD）
     *
     * @param string $content ストリームに入力する文字列コンテンツ
     */
    public function createStream(string $content = ''): StreamInterface;

    /**
     * 既存のファイルからストリームを作成する
     *
     * ファイルは指定されたモードを使用して開く必要があります（MUST）
     * これはfopen関数でサポートされている任意のモードです
     *
     * $filenameはfopen()でサポートされている任意の文字列（MAY）
     *
     * @param string $filename ストリームのベースとして使用するファイル名またはストリームURI
     * @param string $mode 基になるファイル名/ストリームを開くモード
     *
     * @throws \RuntimeException ファイルを開けない場合
     * @throws \InvalidArgumentException モードが無効な場合
     */
    public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface;

    /**
     * 既存のリソースから新しいストリームを作成する
     *
     * ストリームは読み取り可能でなければならない。書き込み可能の場合もある。
     *
     * @param resource $resource ストリームのベースとして使用するPHPリソース
     */
    public function createStreamFromResource($resource): StreamInterface;
}

このインターフェイスの実装では、文字列からリソースを作成するときに一時的なストリームを使用する必要があります。推奨される方法は次のとおりです。

$resource = fopen('php://temp', 'r+');

UploadedFileFactoryInterface

アップロードされたファイルのストリームを作成する機能を持ちます。

<?php
namespace Psr\Http\Message;

use Psr\Http\Message\StreamInterface;
use Psr\Http\Message\UploadedFileInterface;

interface UploadedFileFactoryInterface
{
    /**
     * 新しいアップロードファイルを作成する
     *
     * サイズが指定されていない場合はストリームのサイズを確認して決定される
     *
     * @link http://php.net/manual/features.file-upload.post-method.php
     * @link http://php.net/manual/features.file-upload.errors.php
     *
     * @param StreamInterface $stream アップロードされたファイルコンテンツを表す基になるストリーム
     *
     * @param int $size ファイルサイズ（bytes）
     * @param int $error PHP アップロードエラーコード
     * @param string $clientFilename クライアントが提供するファイル名etc
     * @param string $clientMediaType クライアントが提供するメディアタイプetc
     *
     * @throws \InvalidArgumentException ファイルリソースが読めない場合
     */
    public function createUploadedFile(
        StreamInterface $stream,
        int $size = null,
        int $error = \UPLOAD_ERR_OK,
        string $clientFilename = null,
        string $clientMediaType = null
    ): UploadedFileInterface;
}

UriFactoryInterface

クライアントおよびサーバーリクエストのURIを作成する機能を持ちます。

namespace Psr\Http\Message;

use Psr\Http\Message\UriInterface;

interface UriFactoryInterface
{
    /**
     * 新しいURIを作成する
     *
     * @param string $uri パースするURI
     *
     * @throws \InvalidArgumentException 指定されたURIをパースできない場合
     */
    public function createUri(string $uri = '') : UriInterface;
}

範囲とするところ

PSR-7互換オブジェクトを作成するメソッドを定義するインターフェースのセットを提供します。

範囲としないところ

PSR-7ファクトリーの特定の実装を提供すること。

選択されたアプローチ

ファクトリメソッド定義は、インスタンス化後にオブジェクトを変更できるかどうかに基づいて選択されています。変更できないインターフェイスの場合、インスタンス化時にすべてのオブジェクトプロパティを定義する必要があります。

UriInterfaceの場合、便宜上完全なURIを渡すことができます。

使用されるメソッド名は競合しません。これにより、適切な場合に単一のクラスで複数のインターフェイスを実装できます。

既存の実装

PSR-7の現在の実装はすべて、独自の要件を定義しています。ほとんどの場合、必要なパラメーターは、提案されているファクトリーメソッドと同じかそれよりも厳密ではありません。

潜在的な問題

この標準を確立する上で最も難しいタスクは、インターフェイスのメソッドシグネチャを定義することです。PSR-7には明示的に必要な値について明確な宣言がないため、読み取り専用のプロパティはインターフェイスにオブジェクトをコピーおよび変更するメソッドがあるかどうかに基づいて推測する必要があります。

PHP 7を選ぶ理由

PSR-7はPHP 7を対象としていませんが、この仕様の著者は執筆時点（2018年4月）でPHP 5.6が15か月前にバグ修正の受信を停止し、8か月後にセキュリティパッチを受信しなくなることに注意しています。

PHP 7.0自体は、2018年12月3にセキュリティサポートが停止（現在のサポートの詳細については、PHPのサポートされているバージョンのドキュメントを参照してください）。

補足

PHP 7.0は2018年12月3にセキュリティサポートが停止しました。

仕様は長期的なものであることを意図しているため著者は、仕様は予見可能な将来にサポートされるバージョンを対象とすべきだと感じています。

PHP 5はサポートしません。そのためセキュリティの観点からPHP 7の下で何かをターゲットにすることは、サポートされていないPHPバージョンの使用を暗黙のうちに承認するため、ユーザーにとっては害になります。

さらに、同様に重要なこととして、PHP 7では、定義するインターフェイスに戻り値のタイプのヒントを提供できます。これにより、エンドユーザーは実装によって返される値がまさに期待どおりになると想定できるため、強力で予測可能な契約が保証されます。

複数のインターフェースが必要な理由

提案された各インターフェイスは、（主に）1つのPSR-7タイプの生成を担当します。これにより、消費者は必要なものを正確に入力できます。レスポンスが必要な場合は、ResponseFactoryInterfaceで入力します。

URIが必要な場合は、UriFactoryInterfaceでタイプヒントします。このようにして、ユーザーは必要なものについてきめ細かく設定できます。

これによりアプリケーション開発者は、使用しているPSR-7実装に基づいて匿名の実装を提供し、特定のコンテキストに必要なインスタンスのみを生成できます。結果、定型文が削減されます。開発者は、未使用のメソッドのスタブを作成する必要はありません。

ResponseFactoryInterfaceへの$reasonPhrase引数が存在するのはなぜか？

ResponseFactoryInterface::createResponse() には、オプションの文字列引数 $reasonPhrase が含まれています。

PSR-7仕様では、ステータスコードを提供すると同時に理由フレーズを提供できます。これは、2つが関連するデータであるためです。

この仕様の作成者は、PSR-7 ResponseInterface::withStatus()署名を模倣して、作成された応答に両方のデータセットが存在することを保証することを選択しました。

ServerRequestFactoryInterfaceへの$serverParams引数が存在するのはなぜか？

ServerRequestFactoryInterface::createServerRequest() には、オプションの $serverParams 配列引数が含まれます。

これが提供される理由は、サーバーのパラメーターが設定された状態でインスタンスを作成できるようにするためです。

ServerRequestInterfaceを介してアクセス可能なデータのうち、ミューテーターメソッドを持たないデータは、サーバーのパラメーターに対応するデータのみです。

そのためこのデータは最初の作成時に提供する必要があり、ファクトリメソッドへの引数として存在します。

スーパーグローバルからServerRequestInterfaceを作成するファクトリーがないのはなぜか？

ServerRequestFactoryInterface の主な使用例は、既知のデータから新しい ServerRequestInterface インスタンスを作成することです。

スーパーグローバルからのデータのマーシャリングに関するソリューションは、次のことを前提としています。

• スーパーグローバルが存在する
• スーパーグローバルは特定の構造に従う

これらの2つの仮定は常に当てはまるわけではありません。Swoole、ReactPHPなどの非同期システムを使用する場合

• $_GET/$_POST/$_COOKIE、および$_FILESなどの標準的なスーパーグローバルを設定しません
• $_SERVERに標準のSAPI（mod_php、mod-cgi、mod-fpmなど）と同じ要素を追加しません

さらに、さまざまな標準SAPIがさまざまな情報を$_SERVERに提供しリクエストヘッダーにアクセスするため、リクエストの初期設定にはさまざまなアプローチが必要です。

そのため、スーパーグローバルからインスタンスを作成するためのインターフェイスの設計はこの仕様の範囲外であり、主に実装固有のものである必要があります。

RequestFactoryInterface::createRequestが文字列URIを許可するのはなぜか？

RequestFactoryInterface の主な使用例は、リクエストを作成することです。リクエストに必要な値は、リクエストメソッドとURIのみです。

RequestFactoryInterface::createRequest() は UriInterfaceインスタンスを受け入れることができますが、文字列も許可します。

理論的根拠は2つあります。まず、大部分のユースケースはリクエストインスタンスを作成することです。

URIインスタンスの作成は二次的です。UriInterface を必要とするということは、ユーザーが UriFactoryInterface にアクセスする必要があるか、 RequestFactoryInterfaceがUriFactoryInterface に厳しい要件を持つことを意味します。

1つ目はFactoryの消費者の使用を複雑にし、2つ目はFactoryの開発者またはFactoryインスタンスを作成する開発者の使用を複雑にします。

第二に、UriFactoryInterface は UriInterfaceインスタンスを作成する1つの方法を提供します。これは文字列URIからのものです。

URIの作成が文字列に基づいている場合、RequestFactoryInterface が同じセマンティクスを許可しない理由はありません。さらに、この提案が開発された時点で調査されたすべてのPSR-7実装では、RequestInterfaceインスタンスを作成するときに、提供されたUriInterface実装に値が渡されるため、文字列URIが許可されました。そのため、文字列を受け入れることは適切であり、既存のセマンティクスに従います。