— 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-18: HTTP Client 2020-08-25 現在

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

このPSRの目標は、開発者がHTTPクライアントの実装から分離されたライブラリを作成できるようにすることです。これにより、依存関係の数が減り、バージョンの競合の可能性が低くなるため、ライブラリの再利用性が高まります。

2番目の目標は、リスコフの置換原理に従ってHTTPクライアントを置き換えることができることです。これは、リクエストを送信するときに全てのクライアントが同じように動作する必要があること( MUST )を意味します。

• クライアント — クライアントは、PSR-7互換のHTTPリクエストメッセージを送信し、PSR-7互換のHTTPレスポンスメッセージを呼び出し側ライブラリに返す目的でこの仕様を実装するライブラリです。
  
  
• 呼び出しライブラリ — 呼び出しライブラリは、このPSRで定義されているHTTPクライアントを利用するコードで、この仕様のインターフェースは実装していませんが、それらを実装するオブジェクト（HTTPクライアント）を使用しています。

A Client is an object implementing ClientInterface.

クライアントは、ClientInterface を実装するオブジェクトです。

A Client MAY:

クライアントのMAY-DO：

• Choose to send an altered HTTP request from the one it was provided. For example, it could compress an outgoing message body.
• Choose to alter a received HTTP response before returning it to the calling library. For example, it could decompress an incoming message body.

• クライアントは、提供されたものから変更されたHTTPリクエストを送信することを選択できます( MAY )。例えば、送信メッセージの本文を圧縮できます。
• クライアントは、呼び出したライブラリに返す前に、受信したHTTPレスポンスを変更することを選択できます( MAY )。例えば、受信メッセージの本文を解凍できます。

If a Client chooses to alter either the HTTP request or HTTP response, it MUST ensure that the object remains internally consistent. For example, if a Client chooses to decompress the message body then it MUST also remove the Content-Encoding header and adjust the Content-Length header.

クライアントがHTTPリクエストまたはHTTPレスポンスのいずれかを変更することを選択した場合、オブジェクトが内部的に一貫していることを保証する必要があります( MUST )。例えば、クライアントがメッセージ本文を解凍することを選択した場合は、Content-Encoding ヘッダーも削除して、Content-Length ヘッダーを調整する必要があります。

Note that as a result, since PSR-7 objects are immutable, the Calling Library MUST NOT assume that the object passed to ClientInterface::sendRequest() will be the same PHP object that is actually sent. For example, the Request object that is returned by an exception MAY be a different object than the one passed to sendRequest(), so comparison by reference ( === ) is not possible.

その結果、PSR-7オブジェクトは不変であるため、呼び出し側ライブラリは、ClientInterface::sendRequest() に渡されたオブジェクトが実際に送信されるPHPオブジェクトと同じであることを想定してはなりません。例えば、例外によって返されるRequestオブジェクトは、sendRequest() に渡されるオブジェクトとは異なるオブジェクトになる可能性があるため、参照による比較( === )はできません。

A Client MUST:

クライアントのMUST-DO：

• Reassemble a multi-step HTTP 1xx response itself so that what is returned to the Calling Library is a valid HTTP response of status code 200 or higher.

• クライアントは、呼び出し元ライブラリに返されるものがステータスコード200以上の有効なHTTPレスポンスになるように、マルチステップHTTP 1xxレスポンス自体を再構成する必要があります( MUST )。

A Client MUST NOT treat a well-formed HTTP request or HTTP response as an error condition. For example, response status codes in the 400 and 500 range MUST NOT cause an exception and MUST be returned to the Calling Library as normal.

クライアントは、整形式のHTTPリクエストまたはHTTPレスポンスをエラー状態として扱わないでください( MUST NOT )。例えば、400と500の範囲のレスポンスステータスコードは例外を発生させてはならず( MUST NOT )、通常どおり呼び出しライブラリに返される必要があります( MUST )。

A Client MUST throw an instance of Psr\Http\Client\ClientExceptionInterface if and only if it is unable to send the HTTP request at all or if the HTTP response could not be parsed into a PSR-7 response object.

クライアントは、HTTPリクエストをまったく送信できない場合、またはHTTPレスポンスをPSR-7レスポンスオブジェクトにパースできなかった場合にのみ、Psr\Http\Client\ClientExceptionInterface のインスタンスをスローする必要があります( MUST )。

If a request cannot be sent because the request message is not a well-formed HTTP request or is missing some critical piece of information (such as a Host or Method), the Client MUST throw an instance of Psr\Http\Client\RequestExceptionInterface.

リクエストメッセージが整形式のHTTPリクエストではないか、重要な情報（ホストやメソッドなど）がないためにリクエストを送信できない場合、クライアントは Psr\Http\Client\RequestExceptionInterface のインスタンスをスローする必要があります( MUST )。

If the request cannot be sent due to a network failure of any kind, including a timeout, the Client MUST throw an instance of Psr\Http\Client\NetworkExceptionInterface.

タイムアウトを含むあらゆる種類のネットワーク障害が原因でリクエストを送信できない場合、クライアントは Psr\Http\Client\NetworkExceptionInterface のインスタンスをスローする必要があります( MUST )。

Clients MAY throw more specific exceptions than those defined here (a TimeOutException or HostNotFoundException for example), provided they implement the appropriate interface defined above.

クライアントは、上記で定義された適切なインターフェースを実装している場合、ここで定義されたものよりも具体的な例外（例えば、 TimeOutException または HostNotFoundException ）をスローできます( MAY )。

ClientInterface.php

namespace Psr\Http\Client;
 
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
 
interface ClientInterface
{
    /**
     * Sends a PSR-7 request and returns a PSR-7 response.
     * PSR-7リクエストを送信し、PSR-7レスポンスを返します。
     *
     * @param RequestInterface $request
     *
     * @return ResponseInterface
     *
     * @throws \Psr\Http\Client\ClientExceptionInterface If an error happens while processing the request.
     *                                                   リクエストの処理中にエラーが発生した場合。
     */
    public function sendRequest(RequestInterface $request): ResponseInterface;
}

ClientExceptionInterface.php

namespace Psr\Http\Client;
 
/**
 * Every HTTP client related exception MUST implement this interface.
 * すべてのHTTPクライアント関連の例外は、このインターフェイスを実装する必要があります。
 */
interface ClientExceptionInterface extends \Throwable
{
}

RequestExceptionInterface.php

namespace Psr\Http\Client;
 
use Psr\Http\Message\RequestInterface;
 
/**
 * Exception for when a request failed.
 * リクエストが失敗した場合の例外。
 *
 * Examples:
 *      - Request is invalid (e.g. method is missing)
 *      - Runtime request errors (e.g. the body stream is not seekable)
 * 例：
 *      -リクエストが無効です（メソッドが見つからないなど）
 *      -ランタイムリクエストエラー（ボディストリームがシークできないなど）
 */
interface RequestExceptionInterface extends ClientExceptionInterface
{
    /**
     * Returns the request.
     * リクエストを返します。
     *
     * The request object MAY be a different object from the one passed to ClientInterface::sendRequest()
     * リクエストオブジェクトは、ClientInterface::sendRequest()に渡されるオブジェクトとは
     * 異なるオブジェクトである可能性があります
     *
     * @return RequestInterface
     */
    public function getRequest(): RequestInterface;
}

NetworkExceptionInterface.php

namespace Psr\Http\Client;
 
use Psr\Http\Message\RequestInterface;
 
/**
 * Thrown when the request cannot be completed because of network issues.
 * ネットワークの問題のためにリクエストを完了できない場合にスローされます。
 *
 * There is no response object as this exception is thrown when no response has been received.
 * この例外は、応答が受信されなかった場合にスローされるため、応答オブジェクトはありません。
 *
 * Example: the target host name can not be resolved or the connection failed.
 * 例：ターゲットホスト名を解決できないか、接続が失敗しました。
 */
interface NetworkExceptionInterface extends ClientExceptionInterface
{
    /**
     * Returns the request.
     * リクエストを返します。
     *
     * The request object MAY be a different object from the one passed to ClientInterface::sendRequest()
     * リクエストオブジェクトは、ClientInterface::sendRequest()に渡されるオブジェクトとは
     * 異なるオブジェクトである可能性があります
     *
     * @return RequestInterface
     */
    public function getRequest(): RequestInterface;
}