— y2sunlight 2020-07-28

本章は、若干の補足を加筆してはいるものの単に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 - PHPDocタグ

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

This document describes a common standard for factories that create PSR-7 compliant HTTP objects.

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

PSR-7 did not include a recommendation on how to create HTTP objects, which leads to difficulties when needing to create new HTTP objects within components that are not tied to a specific implementation of PSR-7.

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

The interfaces outlined in this document describe methods by which PSR-7 objects can be instantiated.

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

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

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

An HTTP factory is a method by which a new HTTP object, as defined by PSR-7, is created. HTTP factories MUST implement these interfaces for each object type that is provided by the package.

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

The following interfaces MAY be implemented together within a single class or in separate classes.

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

Has the ability to create client requests.

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

RequestFactoryInterface.php

namespace Psr\Http\Message;
 
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\UriInterface;
 
interface RequestFactoryInterface
{
    /**
     * Create a new request.
     * 新しいリクエストを作成します。
     *
     * @param string $method The HTTP method associated with the request.
     *                       リクエストに関連付けられたHTTPメソッド。
     * @param UriInterface|string $uri The URI associated with the request. 
     *                                 リクエストに関連付けられたURI。
     */
    public function createRequest(string $method, $uri): RequestInterface;
}

Has the ability to create responses.

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

ResponseFactoryInterface.php

namespace Psr\Http\Message;
 
use Psr\Http\Message\ResponseInterface;
 
interface ResponseFactoryInterface
{
    /**
     * Create a new response.
     * 新しいレスポンスを作成します。
 
     *
     * @param int $code The HTTP status code. Defaults to 200.
     *                  HTTPステータスコード。デフォルトは200です。
     * @param string $reasonPhrase The reason phrase to associate with the status code
     *     in the generated response. If none is provided, implementations MAY use
     *     the defaults as suggested in the HTTP specification.
     *     生成された応答のステータスコードに関連付ける理由フレーズ。
     *     何も提供されていない場合、実装はHTTP仕様で提案されているデフォルトを使用できます。
     */
    public function createResponse(int $code = 200, string $reasonPhrase = ''): ResponseInterface;
}

Has the ability to create server requests.

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

ServerRequestFactoryInterface.php

namespace Psr\Http\Message;
 
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\UriInterface;
 
interface ServerRequestFactoryInterface
{
    /**
     * Create a new server request.
     * 新しいサーバーリクエストを作成します。
     *
     * Note that server parameters are taken precisely as given - no parsing/processing
     * of the given values is performed. In particular, no attempt is made to
     * determine the HTTP method or URI, which must be provided explicitly.
     * サーバーパラメータは指定されたとおりに正確に取得されることに注意してください。
     * 指定された値の解析/処理は実行されません。特に、明示的に指定する必要があるHTTPメソッドまたは
     * URIを決定する試みは行われません。
     *
     * @param string $method The HTTP method associated with the request.
     *                       リクエストに関連付けられたHTTPメソッド。
     * @param UriInterface|string $uri The URI associated with the request. 
     *                                 リクエストに関連付けられたURI。
     * @param array $serverParams An array of Server API (SAPI) parameters with
     *     which to seed the generated request instance.
     *     生成されたリクエストのインスタンスをシードするサーバーAPI（SAPI）パラメーターの配列。
     */
    public function createServerRequest(string $method, $uri, array $serverParams = []): ServerRequestInterface;
}

Has the ability to create streams for requests and responses.

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

StreamFactoryInterface.php

namespace Psr\Http\Message;
 
use Psr\Http\Message\StreamInterface;
 
interface StreamFactoryInterface
{
    /**
     * Create a new stream from a string.
     * 文字列から新しいストリームを作成します。
     *
     * The stream SHOULD be created with a temporary resource.
     * ストリームは一時的なリソースで作成する必要があります。
     *
     * @param string $content String content with which to populate the stream.
     *                        ストリームに入力する文字列コンテンツ。
     */
    public function createStream(string $content = ''): StreamInterface;
 
    /**
     * Create a stream from an existing file.
     * 既存のファイルからストリームを作成します。
     *
     * The file MUST be opened using the given mode, which may be any mode
     * supported by the `fopen` function.
     * ファイルは与えられたモードを使って開かれなければなりません。
     * これは `fopen`関数でサポートされているどのモードでもかまいません。
     *
     * The `$filename` MAY be any string supported by `fopen()`.
     * `$filename`は`fopen()`でサポートされている任意の文字列にすることができます。
     *
     * @param string $filename The filename or stream URI to use as basis of stream.
     *                         ストリームの基礎として使用するファイル名またはストリームURI。
     * @param string $mode The mode with which to open the underlying filename/stream.
     *                     基本となるファイル名/ストリームを開くためのモード。
     *
     * @throws \RuntimeException If the file cannot be opened.
     *                           ファイルを開けない場合。
     * @throws \InvalidArgumentException If the mode is invalid.
     *                                   モードが無効な場合。
     */
    public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface;
 
    /**
     * Create a new stream from an existing resource.
     * 既存のリソースから新しいストリームを作成します。
     *
     * The stream MUST be readable and may be writable.
     * ストリームは読み取り可能でなければならず、書き込み可能である必要があります(MUST)。
     *
     * @param resource $resource The PHP resource to use as the basis for the stream.
     *                           ストリームのベースとして使用するPHPリソース。
     */
    public function createStreamFromResource($resource): StreamInterface;
}

Implementations of this interface SHOULD use a temporary stream when creating resources from strings. The RECOMMENDED method for doing so is:

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

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

UploadedFileFactoryInterface.php

UriFactoryInterface.php