— y2sunlight 2020-05-25

本章は、若干の補足を加筆してはいるものの単に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-7: HTTP message interfaces 2020-05-25 現在

このドキュメントでは、RFC 7230 および RFC 7231 で説明されているHTTPメッセージを表すための一般的なインターフェイスと、RFC 3986 で説明されているHTTPメッセージで使用するURIについて説明します。

HTTPメッセージはWeb開発の基礎です。WebブラウザーとcURLなどのHTTPクライアントは、HTTPレスポンスメッセージを提供するWebサーバーに送信されるHTTPリクエストメッセージを作成します。サーバー側コードは、HTTPリクエストメッセージを受信し、HTTPレスポンスメッセージを返します。

HTTPメッセージは通常、エンドユーザー（コンシューマー）からは抽象化されていますが、開発者は通常、HTTP APIにリクエストを送信する場合でも、または着信リクエストを処理する場合でも、タスクを実行するために、それらの構造とアクセスまたは操作の方法を知る必要があります。

原文では、コンシューマー(consumer)と言う表現が多く見られます。これはエンドユーザーと同じ意味で使用されていると思われます。

すべてのHTTPリクエストメッセージには特定の形式があります：

POST /path HTTP/1.1
Host: example.com

foo=bar&baz=bat

リクエストの最初の行は「リクエストライン」であり、HTTPリクエストメソッド、リクエストターゲット（通常は絶対URIまたはWebサーバー上のパス）、HTTPプロトコルバージョンが順に含まれます。この後には、1行以上のHTTPヘッダー、空行、およびメッセージボディが続きます。

HTTPレスポンスメッセージも同様の構造を持っています：

HTTP/1.1 200 OK
Content-Type: text/plain

This is the response body

最初の行は「ステータスライン」で、HTTPプロトコルのバージョン、HTTPステータスコード、「理由フレーズ」が順に含まれます。「理由フレーズ」とは、ステータスコードの人間が読める説明のことです。 リクエストメッセージと同様に、この後に1行以上のHTTPヘッダー、空行、およびメッセージボディが続きます。

このドキュメントで説明されているインターフェースは、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 — オプション

• RFC 2119　・・・　Key words for use in RFCs to Indicate Requirement Levels
• RFC 3986　・・・　Uniform Resource Identifier (URI): Generic Syntax
• RFC 7230　・・・　Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing
• RFC 7231　・・・　Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content

HTTPメッセージは、クライアントからサーバーへのリクエスト、またはサーバーからクライアントへのレスポンスです。この仕様は、HTTPメッセージ Psr\Http\Message\RequestInterfaceコード および Psr\Http\Message\ResponseInterface に対するインターフェースをそれぞれ定義します。

Psr\Http\Message\RequestInterface と Psr\Http\Message\ResponseInterface はどちらも Psr\Http\Message\MessageInterface を拡張(extends)します。Psr\Http\Message\MessageInterface を直接実装(implements)してもかまいませんが( MAY )、実装者は Psr\Http\Message\RequestInterface と Psr\Http\Message\ResponseInterface を実装する必要があります ( SHOULD )。

これ以降、これらのインターフェースを参照する場合、名前空間 Psr\Http\Message は省略されます。

HTTPメッセージには、Case-insensitiveな（大文字と小文字を区別しない）ヘッダーフィールド名が含まれます。ヘッダーは、Case-insensitiveな方法で MessageInterface を実装しているクラスから名前で取得されます。たとえば、fooヘッダーを取得する場合、FoOコードヘッダーを取得した場合と同じ結果が返されます。 同様に、Fooヘッダーを設定すると、先に設定されたfooヘッダー値が上書きされます。  

$message = $message->withHeader('foo', 'bar');
 
echo $message->getHeaderLine('foo');
// Outputs: bar
 
echo $message->getHeaderLine('FOO');
// Outputs: bar
 
$message = $message->withHeader('fOO', 'baz');
echo $message->getHeaderLine('foo');
// Outputs: baz

ヘッダーは大文字と小文字を区別せずに取得できますが、特に getHeaders() を使用して取得する場合は、実装によって元の大文字と小文字を維持する必要があります( MUST )。

非準拠のHTTPアプリケーションはある特定のケースに依存するかもしれません。従って、ユーザーがリクエストまたはレスポンスを作成する時に、そのケースのHTTPヘッダーを指定できることは有益です。

複数の値を持つヘッダーに対応しつつ、ヘッダーを文字列として操作する便利さを提供するために、ヘッダーは MessageInterface のインスタンスから配列または文字列として取得できます。getHeaderLine() メソッドを使用して、名前によってCase-insensitiveなヘッダーに対するヘッダー値を文字列として取得して下さい。その文字列には、カンマで連結されたすべてのヘッダー値が含まれています。getHeader() を使用して、名前によって特定のCase-insensitiveなヘッダーに対するすべてのヘッダー値を配列で取得して下さい。

$message = $message
    ->withHeader('foo', 'bar')
    ->withAddedHeader('foo', 'baz');
 
$header = $message->getHeaderLine('foo');
// $header contains: 'bar,baz'
 
$header = $message->getHeader('foo');
// ['bar', 'baz']

注意：すべてのヘッダー値をカンマを使用して連結できるわけではありません（例えば、Set-Cookie）。このようなヘッダーを操作する場合、MessageInterface ベースのクラスのコンシューマーは、そのような複数値のヘッダーを取得するために getHeader() メソッドに頼るべきです ( SHOULD )。

リクエストでは、Hostヘッダーは通常、URIのホストコンポーネントと、TCP接続を確立するときに使用されたホストをミラーリングします。 ただし、HTTP仕様では、Hostヘッダーが2つのそれぞれのヘッダーと異なることを許可しています。

（リクエストオブジェクトの）構築中、'Hostヘッダーが提供されていない場合、実装は提供されたURIから'Hostヘッダーを設定しようと試みる必要があります( MUST )。

RequestInterface::withUri() は、デフォルトでは、返すべきリクエストのHostヘッダーを、（引数で）渡された UriInterface のホストコンポーネントと一致するHostヘッダーに置き換えます。

withUri() の2番目の（ $preserveHost ）引数に true を渡すことで、Hostヘッダーの元の状態を保持するように選択できます。この引数が true に設定されている場合、返すべきリクエストは返されたメッセージのホストヘッダーを更新しません（メッセージにHostヘッダーが含まれていない場合を除きます）。

上記の原文
You can opt-in to preserving the original state of the Host header by passing true for the second ($preserveHost) argument. When this argument is set to true, the returned request will not update the Host header of the returned message – unless the message contains no Host header.

この表は、様々な初期リクエストとURIに対して $preserveHost 引数を true に設定して、withUri() によって返されたリクエストに対して getHeaderLine('Host') が返すものを示しています。

HTTPメッセージは、開始行、ヘッダー、および本文で構成されます。HTTPメッセージの本文は、非常に小さい場合と非常に大きい場合があります。メッセージの本文を完全にメモリに格納する必要があるため、メッセージの本文を文字列として表現しようとすると、意図したよりも多くのメモリが消費されます。リクエストまたはレスポンスの本文をメモリに保存しようとすると、その実装を使用して大きなメッセージ本文を処理できなくなります。StreamInterface は、データストリームの読み取りまたは書き込み時、実装の詳細を隠蔽するために使用されます。文字列が適切なメッセージ実装である状況では、php://memory や php:php://temp などの組み込みストリームを使用できます。

StreamInterface は、ストリームの読み取り、書き込み、および効率的なトラバース（通過）を可能にするいくつかのメソッドを公開しています。

TODO: ここから

Streams expose their capabilities using three methods: isReadable(), isWritable(), and isSeekable(). These methods can be used by stream collaborators to determine if a stream is capable of their requirements.

ストリームは、isReadable()、isWritable()、isSeekable() の3つのメソッドを使用してその機能を公開します。ストリームの共同制作者はこれらのメソッドを使用して、ストリームが要件を満たしているかどうかを判断できます。

Each stream instance will have various capabilities: it can be read-only, write-only, or read-write. It can also allow arbitrary random access (seeking forwards or backwards to any location), or only sequential access (for example in the case of a socket, pipe, or callback-based stream).

各ストリームインスタンスにはさまざまな機能があります。読み取り専用、書き込み専用、または読み書き可能です。 また、任意のランダムアクセス（任意の場所への前方または後方へのシーク）またはシーケンシャルアクセス（たとえば、ソケット、パイプ、またはコールバックベースのストリームの場合）のみを許可することもできます。

Finally, StreamInterface defines a toString() method to simplify retrieving or emitting the entire body contents at once. 最後に、StreamInterfaceはtoString() メソッドを定義して、ボディコンテンツ全体を一度に取得（読み込み）または放出（書き込み）することを簡素化します。

Unlike the request and response interfaces, StreamInterface does not model immutability. In situations where an actual PHP stream is wrapped, immutability is impossible to enforce, as any code that interacts with the resource can potentially change its state (including cursor position, contents, and more). Our recommendation is that implementations use read-only streams for server-side requests and client-side responses. Consumers should be aware of the fact that the stream instance may be mutable, and, as such, could alter the state of the message; when in doubt, create a new stream instance and attach it to a message to enforce state.

リクエストおよびレスポンスインターフェイスとは異なり、StreamInterfaceは不変性(immutability)をモデル化していません。 実際のPHPストリームがラップされている状況では、リソースとやり取りするコードがその状態（カーソルの位置、内容など）を変更する可能性があるため、不変性を強制することは不可能です。 実装では、サーバー側の(HTTP)要求とクライアント側の(HTTP)応答に読み取り専用ストリームを使用することをお勧めします。 コンシューマーは、ストリームインスタンスが変更可能であり、メッセージの状態を変更する可能性があることを認識しておく必要があります。 疑わしい場合は、新しいストリームインスタンスを作成し、それをメッセージにアタッチして状態を強制します。

Per RFC 7230, request messages contain a “request-target” as the second segment of the request line. The request target can be one of the following forms:

RFC 7230に従い、リクエストメッセージには、リクエストラインの2番目のセグメントとして「リクエストターゲット」が含まれています。 リクエストターゲットは、次のいずれかの形式になります。

• origin-form, which consists of the path, and, if present, the query string; this is often referred to as a relative URL. Messages as transmitted over TCP typically are of origin-form; scheme and authority data are usually only present via CGI variables.

• origin-form: パスと、クエリ文字列（存在する場合）で構成されます。 これは多くの場合、相対URLと呼ばれます。 TCPを介して送信されるメッセージは、通常はorigin-formです。 スキームと権限データは通常、CGI変数を介してのみ提供されます。

• absolute-form, which consists of the scheme, authority (“[user-info@]host[:port]”, where items in brackets are optional), path (if present), query string (if present), and fragment (if present). This is often referred to as an absolute URI, and is the only form to specify a URI as detailed in RFC 3986. This form is commonly used when making requests to HTTP proxies.

• absolute-form: スキーム、権限（「[user-info@]host[:port]」、角括弧内の項目はオプション）、パス（存在する場合）、クエリ文字列（存在する場合）、およびフラグメント（存在する場合）で構成されます。 これは、多くの場合、絶対URIと呼ばれ、RFC 3986で詳述されているようにURIを指定する唯一のフォームです。このフォームは一般的に、HTTPプロキシへのリクエストを行うときに使用されます。

• authority-form, which consists of the authority only. This is typically used in CONNECT requests only, to establish a connection between an HTTP client and a proxy server.

• authority-form: 権限のみで構成されます。 これは通常、HTTPクライアントとプロキシサーバー間の接続を確立するために、CONNECTリクエストでのみ使用されます。

• asterisk-form, which consists solely of the string *, and which is used with the OPTIONS method to determine the general capabilities of a web server.

• asterisk-form: 単独の*文字で構成されます。OPTIONSメソッドで使われ、Webサーバーの一般的な機能を判断します。

Aside from these request-targets, there is often an ‘effective URL’ which is separate from the request target. The effective URL is not transmitted within an HTTP message, but it is used to determine the protocol (http/https), port and hostname for making the request.

これらのリクエストターゲットとは別に、リクエストターゲットとは異なる「有効なURL」がよくあります。 有効なURLはHTTPメッセージ内では送信されませんが、リクエストを行うためにプロトコル (http/https)、ポート、およびホスト名を決定するために使用されます。

The effective URL is represented by UriInterface. UriInterface models HTTP and HTTPS URIs as specified in RFC 3986 (the primary use case). The interface provides methods for interacting with the various URI parts, which will obviate the need for repeated parsing of the URI. It also specifies a __toString() method for casting the modeled URI to its string representation.

有効なURLはUriInterfaceで表されます。 UriInterfaceは、RFC 3986（主な使用例）で指定されているHTTPおよびHTTPS URIをモデル化します。 このインターフェースは、さまざまなURI部分と対話するためのメソッドを提供します。これにより、URIを繰り返し解析する必要がなくなります。 また、モデル化されたURIをその文字列表現にキャストするための__toString() メソッドも仕様に含んでいます。

When retrieving the request-target with getRequestTarget(), by default this method will use the URI object and extract all the necessary components to construct the origin-form. The origin-form is by far the most common request-target.

getRequestTarget() を使用してリクエストターゲットを取得する場合、デフォルトでは、このメソッドはURIオブジェクトを使用し、必要なすべてのコンポーネントを抽出してorigin-formを構築します。 origin-formは、最も一般的なリクエストターゲットです。

If it’s desired by an end-user to use one of the other three forms, or if the user wants to explicitly override the request-target, it is possible to do so with withRequestTarget().

エンドユーザーが他の3つの形式（origin-form以外）のいずれかを使用したい場合、またはユーザーがリクエストターゲットを明示的にオーバーライドしたい場合は、withRequestTarget() を使用してこれを行うことができます。

Calling this method does not affect the URI, as it is returned from getUri().

このメソッドはgetUri() から返されるため、このメソッドを呼び出してもURIには影響しません。

For example, a user may want to make an asterisk-form request to a server:

たとえば、ユーザーがサーバーにasterisk-formのリクエストを行う場合があります。

 
$request = $request
    ->withMethod('OPTIONS')
    ->withRequestTarget('*')
    ->withUri(new Uri('https://example.org/'));

This example may ultimately result in an HTTP request that looks like this:

この例では、最終的に次のようなHTTPリクエストになります。

OPTIONS * HTTP/1.1

But the HTTP client will be able to use the effective URL (from getUri()), to determine the protocol, hostname and TCP port.

しかし、プロトコル、ホスト名、およびTCPポートを決定する為に、HTTPクライアントは、（getUri() からの）有効なURLを使用することができます。

An HTTP client MUST ignore the values of Uri::getPath() and Uri::getQuery(), and instead use the value returned by getRequestTarget(), which defaults to concatenating these two values.

HTTPクライアントは、Uri::getPath() およびUri::getQuery() の値を無視し、代わりにgetRequestTarget() によって返される値を使用する必要があります (MUST)。getRequestTarget()はデフォルトでは、これら2つの値を連結します。

Clients that choose to not implement 1 or more of the 4 request-target forms, MUST still use getRequestTarget(). These clients MUST reject request-targets they do not support, and MUST NOT fall back on the values from getUri().

4つのリクエストターゲット形式の1つ以上を実装しないことを選択したクライアントは、引き続きgetRequestTarget() を使用する必要があります (MUST)。これらのクライアントは、サポートしていないリクエストターゲットを拒否する必要があり (MUST)、getUri() からの値に依存してはなりません (MUST NOT)。

RequestInterface provides methods for retrieving the request-target or creating a new instance with the provided request-target. By default, if no request-target is specifically composed in the instance, getRequestTarget() will return the origin-form of the composed URI (or “/” if no URI is composed).

RequestInterfaceは、リクエストターゲットを取得するメソッド、または指定されたリクエストターゲットを使用して新しいインスタンスを作成するメソッドを提供します。デフォルトでは、リクエストターゲットがインスタンスで具体的に構成されていない場合、getRequestTarget() は、構成されたURIのorigin-form（または構成されていない場合は「/」）を返します。

withRequestTarget($requestTarget) creates a new instance with the specified request target, and thus allows developers to create request messages that represent the other three request-target forms (absolute-form, authority-form, and asterisk-form). When used, the composed URI instance can still be of use, particularly in clients, where it may be used to create the connection to the server.

withRequestTarget($requestTarget) は、指定されたリクエストターゲットを使用して新しいインスタンスを作成するため、開発者は他の3つのリクエストターゲット形式（absolute-form、authority-form、およびasterisk-form）を表すリクエストメッセージを作成できます。それが使用された場合、構成されたURIインスタンスは、特にクライアントで、サーバーへの接続を作成するために使用される可能性があるため、引き続き使用できます。

RequestInterface provides the general representation of an HTTP request message. However, server-side requests need additional treatment, due to the nature of the server-side environment. Server-side processing needs to take into account Common Gateway Interface (CGI), and, more specifically, PHP’s abstraction and extension of CGI via its Server APIs (SAPI). PHP has provided simplification around input marshaling via superglobals such as:

RequestInterfaceは、HTTPリクエストメッセージの一般的な表現を提供します。 ただし、サーバー側の環境の性質上、サーバー側のリクエストには追加の処理が必要です。 サーバー側の処理では、Common Gateway Interface（CGI）、PHP（さらに具体的には、サーバーAPI（SAPI）を介したCGIの抽象化）と拡張を考慮する必要があります。 PHPは、次のようなスーパーグローバル変数を介して入力のマーシャリングを簡素化しました。

• $_COOKIE, which deserializes and provides simplified access to HTTP cookies.
• $_GET, which deserializes and provides simplified access to query string arguments.
• $_POST, which deserializes and provides simplified access for urlencoded parameters submitted via HTTP POST; generically, it can be considered the results of parsing the message body.
• $_FILES, which provides serialized metadata around file uploads.
• $_SERVER, which provides access to CGI/SAPI environment variables, which commonly include the request method, the request scheme, the request URI, and headers.

• $_COOKIE: HTTPCookieへのデシリアル化と簡略化されたアクセスを提供します。
• $_GET: クエリ文字列引数へのデシリアル化と簡略化されたアクセスを提供します。
• $_POST: HTTP POST経由で送信されたURLエンコードされたパラメーターへのデシリアル化と簡略化されたアクセスを提供します。 一般的には、メッセージ本文の解析結果と考えることができます。
• $_FILES: ファイルのアップロードに関するシリアル化されたメタデータを提供します。
• $_SERVER: CGI / SAPI環境変数へのアクセスを提供します。これには、通常、リクエストメソッド、リクエストスキーム、リクエストURI、およびヘッダーが含まれます。

ServerRequestInterface extends RequestInterface to provide an abstraction around these various superglobals. This practice helps reduce coupling to the superglobals by consumers, and encourages and promotes the ability to test request consumers.

ServerRequestInterfaceはRequestInterfaceを拡張して、これらのさまざまなスーパーグローバル変数に関する抽象化を提供します。 このプラクティスは、コンシューマーによるスーパーグローバル変数への結合を減らすのに役立ち、リクエストコンシューマーをテストする機能を奨励および促進します。

The server request provides one additional property, “attributes”, to allow consumers the ability to introspect, decompose, and match the request against application-specific rules (such as path matching, scheme matching, host matching, etc.). As such, the server request can also provide messaging between multiple request consumers.

サーバーリクエストは、「attributes」という1つの追加プロパティを提供して、コンシューマーがアプリケーション固有のルール（パスマッチング、スキームマッチング、ホストマッチングなど）に対してリクエストを内省(introspect)、分解(decompose)、および照合(match)できるようにします。 したがって、サーバーリクエストは、複数のリクエストコンシューマー間のメッセージングにも提供できます。

ServerRequestInterface specifies a method for retrieving a tree of upload files in a normalized structure, with each leaf an instance of UploadedFileInterface.

ServerRequestInterfaceは、正規化された構造でアップロードファイルのツリーを取得するメソッドを規定します。そのツリーの各リーフにはUploadedFileInterfaceのインスタンスがあります。

The $_FILES superglobal has some well-known problems when dealing with arrays of file inputs. As an example, if you have a form that submits an array of files — e.g., the input name “files”, submitting files[0] and files[1] — PHP will represent this as:

$_FILESスーパーグローバル変数には、ファイル入力の配列を処理するときによく知られた問題がいくつかあります。 例として、ファイルの配列を送信するフォームがある場合（例えば入力名を「files」とする）、files[0] とfiles[1] を送信すると、PHPはこれを次のように表します：

array(
    'files' => array(
        'name' => array(
            0 => 'file0.txt',
            1 => 'file1.html',
        ),
        'type' => array(
            0 => 'text/plain',
            1 => 'text/html',
        ),
        /* etc. */
    ),
)

instead of the expected:

期待されるのは次のようです：

array(
    'files' => array(
        0 => array(
            'name' => 'file0.txt',
            'type' => 'text/plain',
            /* etc. */
        ),
        1 => array(
            'name' => 'file1.html',
            'type' => 'text/html',
            /* etc. */
        ),
    ),
)

The result is that consumers need to know this language implementation detail, and write code for gathering the data for a given upload.

その結果、コンシューマーはこの言語実装(PHP)の詳細を知って、与えられたアップロードのデータを収集するためのコードを書く必要があります。

Additionally, scenarios exist where $_FILES is not populated when file uploads occur:

さらに、ファイルのアップロードが発生したときに$_FILESが入力されない状況があります：

• When the HTTP method is not POST.
• When unit testing.
• When operating under a non-SAPI environment, such as ReactPHP.

• HTTPメソッドがPOSTでない場合
• ユニットテスト時
• ReactPHPのように非SAPI環境下で操作する場合

In such cases, the data will need to be seeded differently. As examples:

そのような場合、データを別の方法でシード（特別な処理）する必要があります。 例としては：

• A process might parse the message body to discover the file uploads. In such cases, the implementation may choose not to write the file uploads to the file system, but instead wrap them in a stream in order to reduce memory, I/O, and storage overhead.

• プロセスがメッセージ本文を解析して、ファイルのアップロードを検出する場合があります。 このような場合、実装では、ファイルアップロードをファイルシステムに書き込まず、代わりにストリームにラップして、メモリ、I/O、ストレージのオーバーヘッドを削減します。

• In unit testing scenarios, developers need to be able to stub and/or mock the file upload metadata in order to validate and verify different scenarios.

• ユニットテストのシナリオでは、さまざまなシナリオを検証および検査するために、開発者はファイルアップロードのメタデータをスタブ化および/またはモックできる必要があります。

getUploadedFiles() provides the normalized structure for consumers. Implementations are expected to:

getUploadedFiles() は、コンシューマに正規化された構造を提供します。 実装では、次のことが期待されます：

• Aggregate all information for a given file upload, and use it to populate a Psr\Http\Message\UploadedFileInterface instance.
• Re-create the submitted tree structure, with each leaf being the appropriate Psr\Http\Message\UploadedFileInterface instance for the given location in the tree.

• 与えられたファイルアップロードのすべての情報を集約し、それを使用してPsr\Http\Message\UploadedFileInterfaceインスタンスに入力します。
• 送信されたツリー構造を再作成します。その時各リーフは、ツリー内の与えられた場所に対して適切なPsr\Http\Message\UploadedFileInterfaceのインスタンスになります。

The tree structure referenced should mimic the naming structure in which files were submitted.

参照されるツリー構造は、ファイルが送信されたときのネーミング構造を模倣する必要があります。

In the simplest example, this might be a single named form element submitted as:

最も単純な例では、これは次のように送信された単一の名前付きフォーム要素でしょう：

<input type="file" name="avatar" />

In this case, the structure in $_FILES would look like:

この場合、$_FILESの構造は次のようになります：

array(
    'avatar' => array(
        'tmp_name' => 'phpUxcOty',
        'name' => 'my-avatar.png',
        'size' => 90996,
        'type' => 'image/png',
        'error' => 0,
    ),
)

The normalized form returned by getUploadedFiles() would be:

getUploadedFiles() によって返される正規化された形式は次のようになります：

array(
    'avatar' => /* UploadedFileInterface instance */
)

In the case of an input using array notation for the name:

名前に配列表記を使用した入力の場合：

<input type="file" name="my-form[details][avatar]" />

$_FILES ends up looking like this:

$_FILESは次のようになります：

array (
    'my-form' => array (
        'name' => array (
            'details' => array (
                'avatar' => 'my-avatar.png',
            ),
        ),
        'type' => array (
            'details' => array (
                'avatar' => 'image/png',
            ),
        ),
        'tmp_name' => array (
            'details' => array (
                'avatar' => 'phpmFLrzD',
            ),
        ),
 
        'error' => array (
            'details' => array (
                'avatar' => 0,
            ),
        ),
        'size' => array (
            'details' => array (
                'avatar' => 90996,
            ),
        ),
    ),
)

And the corresponding tree returned by getUploadedFiles() should be:

そして、getUploadedFiles() によって返される対応するツリーは次のようになります：

array(
    'my-form' => array(
        'details' => array(
            'avatar' => /* UploadedFileInterface instance */
        ),
    ),
)

In some cases, you may specify an array of files:

場合によっては、ファイルの配列を指定できます：

Upload an avatar: <input type="file" name="my-form[details][avatars][]" />
Upload an avatar: <input type="file" name="my-form[details][avatars][]" />

(As an example, JavaScript controls might spawn additional file upload inputs to allow uploading multiple files at once.)

（例として、JavaScriptコントロールは、複数のファイルを一度にアップロードできるように、追加のファイルアップロード入力を生成する場合があります。）

In such a case, the specification implementation must aggregate all information related to the file at the given index. The reason is because $_FILES deviates from its normal structure in such cases:

このような場合、仕様の実装では、指定されたインデックスにあるファイルに関連するすべての情報を集約する必要があります。 その理由は、$_FILESは通常の構造から逸脱しているためです。それは、次のような場合です：

array (
    'my-form' => array (
        'name' => array (
            'details' => array (
                'avatar' => array (
                    0 => 'my-avatar.png',
                    1 => 'my-avatar2.png',
                    2 => 'my-avatar3.png',
                ),
            ),
        ),
        'type' => array (
            'details' => array (
                'avatar' => array (
                    0 => 'image/png',
                    1 => 'image/png',
                    2 => 'image/png',
                ),
            ),
        ),
        'tmp_name' => array (
            'details' => array (
                'avatar' => array (
                    0 => 'phpmFLrzD',
                    1 => 'phpV2pBil',
                    2 => 'php8RUG8v',
                ),
            ),
        ),
        'error' => array (
            'details' => array (
                'avatar' => array (
                    0 => 0,
                    1 => 0,
                    2 => 0,
                ),
            ),
        ),
        'size' => array (
            'details' => array (
                'avatar' => array (
                    0 => 90996,
                    1 => 90996,
                    3 => 90996,
                ),
            ),
        ),
    ),
)

The above $_FILES array would correspond to the following structure as returned by getUploadedFiles():

上記の$_FILES配列は、getUploadedFiles() によって返される次の構造に対応します：

array(
    'my-form' => array(
        'details' => array(
            'avatars' => array(
                0 => /* UploadedFileInterface instance */,
                1 => /* UploadedFileInterface instance */,
                2 => /* UploadedFileInterface instance */,
            ),
        ),
    ),
)

Consumers would access index 1 of the nested array using:

コンシューマーは、ネストされた配列のインデックス1に次のようにしてアクセスします：

$request->getUploadedFiles()['my-form']['details']['avatars'][1];

Because the uploaded files data is derivative (derived from $_FILES or the request body), a mutator method, withUploadedFiles(), is also present in the interface, allowing delegation of the normalization to another process.

アップロードされたファイルデータは派生物（$_FILESまたはリクエストボディからの派生）であるため、インターフェイスにはミューテーターメソッド(mutator method) としてwithUploadedFiles() も存在し、正規化を別のプロセスに委譲できます。

In the case of the original examples, consumption resembles the following:

冒頭の例の場合、使用方法は次のようになります：

$file0 = $request->getUploadedFiles()['files'][0];
$file1 = $request->getUploadedFiles()['files'][1];
 
printf(
    "Received the files %s and %s",
    $file0->getClientFilename(),
    $file1->getClientFilename()
);
 
// "Received the files file0.txt and file1.html"

This proposal also recognizes that implementations may operate in non-SAPI environments. As such, UploadedFileInterface provides methods for ensuring operations will work regardless of environment. In particular:

この提案は、実装が非SAPI環境で動作する可能性があることも認識しています。 したがって、UploadedFileInterfaceは、環境に関係なく操作が確実に機能するためのメソッドを提供します。 特に：  

• moveTo($targetPath) is provided as a safe and recommended alternative to calling move_uploaded_file() directly on the temporary upload file. Implementations will detect the correct operation to use based on environment.

• moveTo($targetPath) は、一時アップロードファイル上でmove_uploaded_file() を直接呼び出すより安全で推奨される代替手段として提供されています。 実装は、環境に基づいて使用する正しい操作を検出します。

• getStream() will return a StreamInterface instance. In non-SAPI environments, one proposed possibility is to parse individual upload files into php:temp streams instead of directly to files; in such cases, no upload file is present. getStream() is therefore guaranteed to work regardless of environment. * getStream() はStreamInterfaceインスタンスを返します。 非SAPIの環境下では、個々のアップロードファイルを解析して直接ファイルにではなくphp:tempストリームにすることが提案されています。 このような場合、アップロードファイルは存在しないことになり、 したがって、getStream() は環境に関係なく動作することが保証されています。

As examples:

例として：

// Move a file to an upload directory
// ファイルをアップロードディレクトリに移動する
$filename = sprintf(
    '%s.%s',
    create_uuid(),
    pathinfo($file0->getClientFilename(), PATHINFO_EXTENSION)
);
$file0->moveTo(DATA_DIR . '/' . $filename);
 
// Stream a file to Amazon S3.
// Assume $s3wrapper is a PHP stream that will write to S3, and that
// Psr7StreamWrapper is a class that will decorate a StreamInterface as a PHP
// StreamWrapper.
// ファイルをAmazon S3にストリーミングします。
// $s3wrapperがS3に書き込むPHPストリームであり、Psr7StreamWrapperがStreamInterfaceを
// PHP StreamWrapperとして装飾するクラスであると想定します。
$stream = new Psr7StreamWrapper($file1->getStream());
stream_copy_to_stream($stream, $s3wrapper);

説明されているインターフェースとクラスは、psr/http-message パッケージの一部として提供されます。

ここでは、原本に記載されているインターフェースの要約とメソッド一覧を示します。詳細はphp-fig.orgを参照してください。

完全クラス名

要約

参照

完全クラス名

要約

完全クラス名

要約

完全クラス名

要約

完全クラス名

要約

完全クラス名

要約

参照

完全クラス名

要約