PSR-17: HTTP Factories

— y2sunlight 2020-07-28

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

PSR-17: HTTPファクトリー

— 原文より翻訳 PSR-17: HTTP HTTP Factories 2020-08-17 現在

このドキュメントでは、PSR-7準拠のHTTPオブジェクトを作成するファクトリーの一般的な規約について説明します。

PSR-7には、HTTPオブジェクトの作成方法に関する推奨事項が含まれていなかったため、PSR-7の特定の実装に関連付けられていないコンポーネント内に新しいHTTPオブジェクトを作成する必要がある場合に問題が発生します。

このドキュメントで概説されているインターフェースは、PSR-7オブジェクトをインスタンス化できるメソッドについて説明しています。

このドキュメントのキーワード 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 — オプション

1. 仕様

HTTPファクトリーは、PSR-7で定義されている新しいHTTPオブジェクトを作成するためのメソッドです。HTTPファクトリーは、パッケージによって提供されるそれぞれのオブジェクトタイプごとにこれらのインターフェースを実装する必要があります( MUST )。

2. インターフェース

以下のインターフェースは、単一のクラスまたは別々のクラスで一緒に実装される場合があります( MAY )。

2.1 RequestFactoryInterface

このインターフェースはクライアント要求を作成する機能があります。

RequestFactoryInterface.php

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;
}

2.2 ResponseFactoryInterface

このインターフェースは応答を作成する機能があります。

ResponseFactoryInterface.php

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;
}

2.3 ServerRequestFactoryInterface

このインターフェースはサーバー要求を作成する機能があります。

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;
}

2.4 StreamFactoryInterface

このインターフェースはリクエストとレスポンスのストリームを作成する機能があります。

StreamFactoryInterface.php

namespace Psr\Http\Message;
 
use Psr\Http\Message\StreamInterface;
 
interface StreamFactoryInterface
{
    /**
     * 文字列から新しいストリームを作成します。
     *
     * ストリームは一時的なリソースで作成する必要があります。
     *
     * @param string $content ストリームに入力する文字列コンテンツ。
     */
    public function createStream(string $content = ''): StreamInterface;
 
    /**
     * 既存のファイルからストリームを作成します。
     *
     * ファイルは与えられたモードを使って開かれなければなりません。
     * これは `fopen`関数でサポートされているどのモードでもかまいません。
     *
     * `$filename`は`fopen()`でサポートされている任意の文字列にすることができます。
     *
     * @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;
}

このインターフェースの実装では、文字列からリソースを作成するときに一時ストリームを使用すべきです( SHOULD )。そのための推奨される方法は次のとおりです( RECOMMENDED )：

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

2.5 UploadedFileFactoryInterface

このインターフェースはアップロードされたファイルのストリームを作成する機能があります。

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 ファイルのサイズ（バイト単位）。
     * @param int $error PHPファイルのアップロードエラー。
     * @param string $clientFilename クライアントが提供するファイル名（存在する場合）。
     * @param string $clientMediaType クライアントが提供するメディアタイプ（存在する場合）。
     *
     * @throws \InvalidArgumentException ファイルリソースが読み取り可能でない場合。
     */
    public function createUploadedFile(
        StreamInterface $stream,
        int $size = null,
        int $error = \UPLOAD_ERR_OK,
        string $clientFilename = null,
        string $clientMediaType = null
    ): UploadedFileInterface;
}

2.6 UriFactoryInterface

このインターフェースはクライアントとサーバーのリクエストに対するURIを作成する機能があります。

UriFactoryInterface.php

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;
}

目次