例のPSR-7

PSR-7標準は正常に完了しました。 今週、最後の仕上げが追加されました。 これで、 http-messageパッケージのバージョン0.6.0を使用する準備が整いました。 アプリケーションでこの標準に従うようにしてください。

あまりにも単純すぎるプレゼンテーションと複雑すぎるプレゼンテーションの両方について、私はまだ意見を聞いています。 それが、この投稿が書かれた理由です-公開された推奨事項の使用を実証し、同時にそれらが提供するシンプルさと完全性と信頼性を同時に示すためです。

まず、この標準を規制するものについて簡単に説明します。

HTTPメッセージ

HTTPはかなり単純なプロトコルです。 それが何年もの間首尾よく使用されてきた理由です。 その中のメッセージの構造は次のとおりです。

<message line> Header: value Another-Header: value Message body 

見出しはキーと値のペアです。 キーでは大文字と小文字が区別されます。 値は文字列です。 1つのタイトルにはいくつかの意味があります。 この場合、値は通常、コンマ区切りリストで表されます。
メッセージ本文は文字列です。 通常、サーバーとクライアントによってストリームとして扱われ、メモリ消費量と処理負荷が削減されます。 これは、大きなデータセットを転送する場合、特にファイルを転送する場合に非常に重要です。 たとえば、そのまま使用できるPHPは、着信要求本文をphp：//入力ストリームとして表し、出力バッファー（正式にはストリーム）を使用して応答を返します。
メッセージ行は、HTTPリクエストとレスポンスを区別する場所です。
要求のメッセージ行（以降、要求行と呼びます）の形式は次のとおりです。

 METHOD request-target HTTP/VERSION 

メソッド（「METHOD」）がリクエストのタイプを決定する場合：GET、POST、PUT、PATCH、DELETE、OPTIONS、HEADなど、プロトコルバージョン（「VERSION」）は通常1.0または1.1（最新のWebクライアントでは1.1）です。 そして、リクエスト（「リクエストターゲット」）の目的に関して、私たちはより詳細に説明します。
要求の目的は次のように表すことができます。

• パスとクエリ文字列（提供されている場合）である標準形式、つまり URI （Universal Resource Identifier）。
• 絶対URIである絶対形式。
• 承認に必要なURIの一部である承認フォーム（ユーザー情報（提供されている場合）、ホスト、およびポート（標準でない場合））。
• *の形式、つまり、文字「*」で構成される文字列。

通常、クライアントは、HTTPサーバーに接続する最初の要求でのみ、承認のためにデータを転送します。 次に、リソース（認証データなしのURI）への相対（または絶対）パスが要求ターゲットとして送信されます。 したがって、認証データは接続要求（CONNECTメソッド）に対してのみ送信されます。これは通常、プロキシサーバーで作業するときに実行されます。 「*」文字はOPTIONSメソッドで使用され、Webサーバーに関する一般情報を取得します。
要するに、クエリの目的には多くの用途があります。
さて、あなたを完全に混乱させるために、URIを考慮してください。 以下が表示されます。

 <scheme>://<authority>[/<path>][?<query string>] 

httpリクエストの「スキーム」は、httpまたはhttpsになります。 「パス」は誰にとっても理解可能な部分でもあります。 しかし、「権限」とは何ですか？

 [user-info@]host[:port] 

「権限」には常にホストが含まれます。ホストはドメイン名またはIPアドレスです。 ポートはオプションであり、この回線の標準ではない場合（または回線が不明な場合）にのみ必要です。 ユーザー情報は次のように表示されます

 user[:pass] 

パスワードはオプションです。 実際、既存の仕様では、URIでパスワードをまったく使用しないことをお勧めします。 クライアントからパスワードを強制することをお勧めします。
クエリ文字列は、アンパサンドで区切られたキーと値のペアのセットです。

 ?foo=bar&baz&quz=1 

実装言語に応じて、リストまたは配列をモデル化することもできます。

 ?sort[]=ASC&sort[]=date&filter[product]=name 

PHPは、この文字列を2次元配列に変換します。

 [ 'sort' => [ 'ASC', 'date' ], 'filter' => [ 'product' => 'name' ], ] 

そのため、リクエストの目標を形成する柔軟性が十分でない場合、URIは独自に提供します。
幸いなことに、HTTPサーバーの応答は簡単です。 応答行は次のとおりです。

 HTTP/VERSION <status>[ <reason>] 

前述のように、「バージョン」は通常1.0、またはより頻繁に1.1です。 「ステータス」は100から599までの数字です。 「理由」は、各ステータスのステータス説明標準です。
したがって、これはHTTPメッセージの簡単な概要でした。 PSR-7がどのようにモデル化するかを見てみましょう。

メッセージヘッダー

メッセージヘッダーの名前は、最初は大文字と小文字が区別されません。 残念ながら、ほとんどの言語とライブラリはそれらを同じレジスタに導きます。 例として、PHPは、大文字の$ _SERVER配列にHTTP_プレフィックスを付けて_forを置き換えて保存します（これは、 Common Gateway Interface （CGI）仕様に準拠するためです）。
PSR-7は、ヘッダーの上にオブジェクト指向レイヤーを提供することにより、ヘッダーへのアクセスを簡素化します

 //  null,   : $header = $message->getHeader('Accept'); // ,   : if (! $message->hasHeader('Accept')) { } //     , //   : $values = $message->getHeaderLines('X-Foo'); 

上記のロジックはすべて、ヘッダーの指定方法に依存しません。 accept、ACCEEPT、またはaCCePtも有効なヘッダー名であり、同じ結果を返します。
PSR-7は、すべてのヘッダーを解析すると構造体が配列として返されると想定しています。

 /* Returns the following structure: [ 'Header' => [ 'value1' 'value2' ] ] */ foreach ($message->getAllHeaders() as $header => $values) { } 

構造が定義されると、ユーザーは受信内容を正確に把握し、実装に関係なく、ユーザーにとって便利な方法でヘッダーを処理できます。
しかし、たとえば、リクエストを作成してHTTPクライアントに送信するなど、メッセージにヘッダーを追加する場合はどうでしょうか。
PSR-7のメッセージは、 値オブジェクトとしてモデル化されます 。 つまり、状態の変化は実際には別の意味です。 したがって、新しいヘッダーを定義すると、新しいメッセージオブジェクトが作成されます。

 $new = $message->withHeader('Location', 'http://example.com'); 

値を更新するだけの場合は、単にオーバーライドできます。

 $message = $message->withHeader('Location', 'http://example.com'); 

既存のヘッダーに別の値を追加する場合は、次を実行できます。

 $message = $message->withAddedHeader('X-Foo', 'bar'); 

または、タイトルを削除することもできます。

 $message = $message->withoutHeader('X-Foo'); 

メッセージ本文

前述のように、メッセージ本文は通常、パフォーマンスを改善するためのストリームとして扱われます。 これは、HTTPを使用してファイルを転送する場合に特に重要です。 現在のプロセスで使用可能なすべてのメモリを使用する場合を除きます。 私が見たHTTPメッセージのほとんどの実装は、それを忘れるか、事後に振る舞いを変更しようとします（はい、ZF2もこれを犯します！）。 このアプローチの利点について詳しく知りたい場合は、Michael Dowlingの記事を読んでください。 彼はブログで、昨夏のPSR-7でのストリームの使用について書いています。
そのため、PSR-7のメッセージ本文はストリームとしてモデル化されます 。
「しかし、これは行でうまくいく場合の80％の場合には複雑すぎます！」メッセージ本文処理のこの実装を批判する人々の間で最も頻繁に議論されています。 では、次を見てみましょう。

 $body = new Stream('php://temp'); $body->write('Here is the content for my message!'); 

この例、およびこの投稿でHTTPメッセージを操作するすべての後続の例では、PSR-7の開発を反映した、私が作成したphly / httpライブラリを使用します。 この場合、StreamはStreamableInterfaceを実装します。
基本的に、メッセージ本文と対話するためのオブジェクト指向の薄いインターフェイスを取得します。これにより、情報を追加したり、読んだりすることができます。 メッセージを変更したいですか？ 新しいメッセージ本文を作成します。

 $message = $message->withBody(new Stream('php://temp')); 

私の意見では、ストリームとしてのメッセージ本文の表示は複雑に思えますが、実際には、実装と使用は非常にシンプルで理解しやすいものです。
PSR-7でStreamableInterfaceを使用する利点は、さまざまなデザインパターンの実装を簡素化する柔軟性を提供することです。 たとえば、read（）またはgetContents（）メソッドが呼び出されたときにメッセージのコンテンツを返す「コールバック」関数を実装できます（特に、Drupalはこのテンプレートを使用します）。 または、イテレータ。Traversableを使用してコンテンツを返したりマージしたりする実装。 重要なのは、このようなインターフェイスを使用すると、メッセージ本文を操作するための多くのテンプレートを実装するための幅広い範囲が提供されるということです。 また、単に行やファイルに限定するものではありません。
StreamableInterfaceは、HTTPメッセージの本文を操作するときに最も頻繁に使用される一連のメソッドを提供します。 これは、絶対にすべてを提供するという意味ではなく、潜在的に必要な操作の大規模なセットを対象としています。
個人的には、php：// tempストリームを使用します。これは、十分に大きくなるまでメモリ内にあるためです（この場合、ディスク上の一時ファイルに書き込まれます）。 この方法は非常に効果的です。

答え

これまで、すべてのメッセージに共通の機能を検討してきました。 ここで、特に答えを詳しく説明します。
答えには、ステータスコードと説明フレーズがあります。

 $status = $response->getStatusCode(); $reason = $response->getReasonPhrase(); 

覚えやすいです。 では、私たち自身が答えを形成したらどうなるでしょうか？
説明句はオプションと見なされます（ただし、同時に各ステータスコードの標準）。 そのために、インターフェースは応答固有のミューテーターwithStatus（）を提供します：

 $response = $response->withStatus(418, "I'm a teapot"); 

繰り返しますが、メッセージは値オブジェクトとしてモデル化されます。 値を変更すると、応答または要求に関連付けられる新しいインスタンスが作成されます。 ただし、ほとんどの場合、単に現在のインスタンスを再割り当てします。

お問い合わせ

クエリには次が含まれます。

• 方法。
• URI /リクエストの目的。

後者はモデル化が少し難しいです。 おそらく99％のケースでは、リクエストのターゲットとして標準URIが表示されます。 しかし、これは、他のタイプの要求目標を提供する必要があるという事実を否定するものではありません。 したがって、クエリインターフェイスは次のことを行います。

• 要求URIをモデル化するUriInterfaceのインスタンスを作成します。
• 要求ターゲットに2つのメソッドを提供します。getRequestTarget（）。要求ターゲットを返し、提供されない場合は評価します（提案されたURIを使用して元のフォームに戻るか、URIが提供されないかパスが含まれない場合に「/」を返します）; withRequestTarget（）は、リクエストの特定の目的のために新しいインスタンスを作成します。

これにより、必要に応じて、リクエストの任意の目的でリクエストに対処することができます（たとえば、リクエスト内のURI情報を使用してHTTPクライアントとの接続を確立します）。
リクエストからメソッドとURIを取得しましょう：

 $method = $request->getMethod(); $uri = $request->getUri(); 

この場合の$ uriはUriInterfaceのインスタンスであり、URIを使用できます。

 //  URI: $scheme = $uri->getScheme(); $userInfo = $uri->getUserInfo(); $host = $uri->getHost(); $port = $uri->getPort(); $path = $uri->getPath(); $query = $uri->getQuery(); //   $authority = $uri->getAuthority(); // [user-info@]host[:port] 

HTTPメッセージと同様に、URIは値オブジェクトとして表され、URIの一部を変更すると値が変更され、メソッドを変更すると新しいインスタンスが返されます。

 $uri = $uri ->withScheme('http') ->withHost('example.com') ->withPath('/foo/bar') ->withQuery('?baz=bat'); 

URIの変更は新しいインスタンスの作成を意味するため、変更をリクエストに反映する場合は、変更をリクエストオブジェクトに報告する必要があります。 また、他のメッセージと同様に、特定のインスタンスのメソッドまたはURIを変更する必要がある場合は、次のメソッドを使用する必要があります。

 $request = $request ->withMethod('POST') ->withUri($uri->withPath('/api/user')); 

サーバーリクエスト

サーバー要求には、標準のHTTP要求メッセージとは若干異なるタスクがあります。 PHPサーバーAPI（SAPI）のネイティブは、PHP開発者向けの一連の通常の機能を提供します。

• クエリ文字列の引数の逆シリアル化（$ _GET）。
• POSTメソッド（$ _POST）によって送信されたエンコードデータの逆シリアル化。
• Cookieデシリアライゼーション（$ _COOKIE）。
• ダウンロードしたファイル（$ _FILES）の表示と処理。
• CGI / SAPIパラメーターのカプセル化（$ _SERVER）。

クエリ文字列からの引数、リクエスト本文からのデータ、Cookieはリクエストのさまざまな部分から取得できますが、これが実装されていれば便利です。 これらの値を使用する必要がある場合があります。

• APIの場合、データはXMLまたはJSON形式にすることができ、POSTメソッドだけでなく送信することもできます。 つまり、データを復号化してから、リクエストに再度埋め込む必要があります。
• 多くのフレームワークはCookieを暗号化するようになりました。これは、Cookieを復号化してリクエストに埋め込む必要があることを意味します。

そのため、PSR-7は特別なインターフェイス、ServerRequestInterfaceを提供します。これは、ベースRequestInterfaceを拡張し、同様のデータを操作するための機能を記述します。

 $query = $request->getQueryParams(); $body = $request->getBodyParams(); $cookies = $request->getCookieParams(); $files = $request->getFileParams(); $server = $request->getServerParams(); 

APIを記述していて、JSON形式のリクエストを受け入れたいと想像してください。 これを行うと、次のようになります。

 $accept = $request->getHeader('Accept'); if (! $accept || ! preg_match('#^application/([^+\s]+\+)?json#', $accept)) { $response->getBody()->write(json_encode([ 'status' => 405, 'detail' => 'This API can only provide JSON representations', ])); emit($response ->withStatus(405, 'Not Acceptable') ->withHeader('Content-Type', 'application/problem+json') ); exit(); } $body = (string) $request->getBody(); $request = $request ->withBodyParams(json_decode($body)); 

上記の例は、いくつかの機能を示しています。 最初に、リクエストからヘッダーを抽出し、そのヘッダーに基づいて分岐ロジックを示します。 第二に、エラーが発生した場合のリクエストオブジェクトの形成を示します（emit（）関数は仮想的であり、リクエストオブジェクトを取得し、リクエストのヘッダーと本文を提供します）。 最後に、この例では、リクエスト本文を取得し、それをデシリアライズし、リクエストに再度埋め込むことを示しています。

属性

サーバー要求のもう1つの機能は属性です。 これらは、現在のリクエストから取得した値を格納するように設計されています。 一般的な使用例は、ルーティング結果の保存です（URIをキーと値のペアに分割します）。
属性の操作は、次のメソッドで構成されています。

• getAttribute（$ name、$ default = null）特定の属性を取得し、属性が見つからない場合はデフォルト値を返します。
• getAttributes（）は、すべての属性を取得します。
• withAttribute（$ name、$ value）は、この属性を含む新しいServerRequestInterfaceインスタンスを返します。
• withoutAttribute（（$ name）は、指定された属性なしでServerRequestInterfaceのインスタンスを返します。

例として、リクエストインスタンスでAura Routerを見てみましょう。

 use Aura\Router\Generator; use Aura\Router\RouteCollection; use Aura\Router\RouteFactory; use Aura\Router\Router; $router = new Router( new RouteCollection(new RouteFactory()), new Generator() ); $path = $request->getUri()->getPath(); $route = $router->match($path, $request->getServerParams()); foreach ($route->params as $param => $value) { $request = $request->withAttribute($param, $value); } 

この場合のクエリインスタンスは、データの整理とルートの送信に使用されます。 その後、ルーティング結果を使用して、応答をインスタンス化します。

ユースケース

ここで、PSR-7のさまざまなコンポーネントのクイックツアーの後、特定のユースケースに戻りましょう。

お客さま

私にとって、PSR-7標準の主な作成者は、人気のあるGuzzle HTTPクライアントの作成者であるMichael Dowlingです。 したがって、PSR-7がHTTPクライアントに改善をもたらすことは明らかです。 方法を説明しましょう。
まず、これは開発者がクエリ実行のためのユニークなメッセージインターフェースを持つことを意味します。 PSR-7標準に従って要求オブジェクトをクライアントに送信し、同じ標準に従って応答オブジェクトを受信できます。

 $response = $client->send($request); 

メッセージとURIは値オブジェクトとしてモデル化されるため、開発者は基本的なクエリインスタンスとURIを作成し、それらから個別のリクエストとURIを作成できることも意味します。

 $baseUri = new Uri('https://api.example.com'); $baseRequest = (new Request()) ->withUri($baseUri) ->withHeader('Authorization', $apiToken); while ($action = $queue->dequeue()) { //   !   // URI      . $request = $baseRequest ->withMethod($action->method) ->withUri($baseUri->withPath($action->path)); //  URI! foreach ($action->headers as $header => $value) { //      ,    //     ! $request = $request->withHeader($header, $value); } $response = $client->send($request); $status = $response->getStatusCode(); if (! in_array($status, range(200, 204))) { //  ! break; } //  ! $data->enqueue(json_decode((string) $response->getBody())); } 

PSR-7が提供するのは、クライアントから送信されたリクエストや受信した応答とやり取りする標準的な方法です。 値オブジェクトを実装することにより、「リセットリクエスト」テンプレートの単純化を目的としたいくつかの興味深いユースケースの可能性を開きます。リクエストを変更すると、常に新しいインスタンスが作成され、常に拡張可能な既知の状態のベースインスタンスを持つことができます。

リンク

私は長い間これにこだわらない すでに記事でこれを行いました。 要するに、主なアイデアは次のとおりです。

 function ( ServerRequestInterface $request, ResponseInterface $response, callable $next = null ) { } 

この関数は2つのHTTPメッセージを受け入れ、それらを使用していくつかの変換を実行します（次に使用可能なリンクへの委任が含まれる場合があります）。 通常、これらのリンクは応答オブジェクトを返します。
よく使用される別のオプションは、ラムダ式です（この用語をメールで送ってくれたLarry Garfieldに感謝します！）：

 /* response = */ function (ServerRequestInterface $request) { /* ... */ return $response; } 

ラムダリンクでは、互いに構成します。

 $inner = function (ServerRequestInterface $request) { /* ... */ return $response; }; $outer = function (ServerRequestInterface $request) use ($inner) { /* ... */ $response = $inner($request); /* ... */ return $response; }; $response = $outer($request); 

そして最後に、RackとWSGIによってプロモートされるメソッドがあります。各リンクはオブジェクトであり、出口に移動します。

 class Command { private $wrapped; public function __construct(callable $wrapped) { $this->wrapped = $wrapped; } public function __invoke( ServerRequestInterface $request, ResponseInterface $response ) { //   $new = $request->withAttribute('foo', 'bar'); //  ,   : $result = ($this->wrapped)($new, $response); // ,      if ($result instanceof ResponseInterface) { $response = $result; } //      return $reponse->withHeader('X-Foo', 'Bar'); } } 

中間リンクの使用は、要求と応答の関係を実装し、標準、つまり予測可能な動作を備えた予測可能なパターンに従うことです。 これは、再利用可能なWebコンポーネントを作成するための優れた方法です。

フレームワーク

フレームワークが長年にわたって提供してきたことの1つは、... HTTPメッセージの抽象化レイヤーです。 PSR-7の目標は、フレームワークに同じ抽象化を使用できるように、フレームワークに共通のインターフェイスセットを提供することです。 これにより、開発者は、再利用可能な、フレームワークに依存しないコードを作成できます。少なくとも、それが私が見たいものです！
Zend Framework 2を検討してください。Zend\ Stdlib \ DispatchableInterfaceインターフェイスを定義します。これは、フレームワークで使用するコントローラーのベースです。

 use Zend\Http\RequestInterface; use Zend\Http\ResponseInterface; interface DispatchableInterface { public function dispatch( RequestInterface $request, ResponseInterface $response ); } 

これは、前述の中間リンクにすぎません。 唯一の違いは、このフレームワークに固有のHTTPメッセージの実装を使用することです。 代わりにPSR-7をサポートする場合はどうなりますか？
フレームワークでのHTTPメッセージのほとんどの実装は、いつでもメッセージの状態を変更できるように設計されています。特にメッセージの状態がすでに無効であると仮定した場合、これは完全に真実ではない場合があります。しかし、これはおそらくこの方法の唯一の欠点です。
PSR-7メッセージは値オブジェクトです。これにより、メッセージの変更についてアプリケーションに通知する必要がなくなります。これにより、実装がより明確になり、コード内で追跡しやすくなります（デバッガーでの段階的なステップと静的コードアナライザーの使用の両方）。
例として、PSF-7に従ってZF2が更新された場合、開発者は通過する顧客に渡したい変更をMvcEventに通知する必要はありません。

 //   $request = $request->withAttribute('foo', 'bar'); $response = $response->withHeader('X-Foo', 'bar'); $event = $this->getEvent(); $event->setRequest($request) ->setResponse($response); 

上記のコードは、アプリケーションの状態を変更していることを明確に示しています。
値オブジェクトを使用すると、1つの特定のプラクティス、サブクエリの割り当てまたは階層MVC（HMVC）の実装が容易になります。この場合、アプリケーションに通知せずに、現在のクエリに基づいて新しいクエリを作成し、アプリケーションの状態が変わらないことを確認できます。
一般に、ほとんどのフレームワークでは、PSR-7メッセージを使用すると、HTTPメッセージを介したポータブルな抽象化に変換されます。これにより、ユニバーサル中間リンクを実装できます。ただし、メッセージを調整するには、小さな変更が必要です。開発者は、アプリケーションのステータスを監視するコードを更新する必要があります。

ソース

PSR-7標準が提供する利点をご覧ください：HTTPメッセージに対する統一された完全な抽象化。さらに、この抽象化は、HTTPトランザクションの各部分（HTTPクライアントを介してリクエストを送信するか、サーバーリクエストを解析する）に使用できます。
PSR-7仕様はまだ完全ではありません。しかし、私が上で概説したことは、投票なしでは大きな変化を経験しないでしょう。次のリンクで、仕様について詳しく知ることができます。

• https://github.com/php-fig/fig-standards/blob/master/proposed/http-message.md

また、アイデア、開発されたソリューション、および2年間にわたる（無限の）紛争の結果について説明している「説明用のメモ」を読むことをお勧めします。

• https://github.com/php-fig/fig-standards/blob/master/proposed/http-message-meta.md

最新の更新はpsr / http-messageパッケージで公開され、composerを使用してインストールできます。これらは常に最新の更新されたオファーです。
ライブラリphly / httpを作成し、提案されたインターフェイスの具体的な実装を提供します。composerを介してインストールすることもできます。
最後に、PSR-7ベースの中間体を試してみたい場合は、次のオプションをお勧めします。

• phly / conduit。Senchaから移植されたConnectライブラリで、コアでphly / httpおよびpsr / http-messageを使用します。
• Stacker、StackPHPは、 Larry Garfieldによって書かれた同様の実装です。

PSR-7での開発の未来が見えます。そして、それはまったく新しい世代のPHPアプリケーションを生み出すと信じています。