first commit

modules/psaddonsconnect/vendor/guzzlehttp/ringphp/docs/client_middleware.rst

@@ -0,0 +1,165 @@
+=================
+Client Middleware
+=================
+
+Middleware intercepts requests before they are sent over the wire and can be
+used to add functionality to handlers.
+
+Modifying Requests
+------------------
+
+Let's say you wanted to modify requests before they are sent over the wire
+so that they always add specific headers. This can be accomplished by creating
+a function that accepts a handler and returns a new function that adds the
+composed behavior.
+
+.. code-block:: php
+
+    use GuzzleHttp\Ring\Client\CurlHandler;
+
+    $handler = new CurlHandler();
+
+    $addHeaderHandler = function (callable $handler, array $headers = []) {
+        return function (array $request) use ($handler, $headers) {
+            // Add our custom headers
+            foreach ($headers as $key => $value) {
+                $request['headers'][$key] = $value;
+            }
+
+            // Send the request using the handler and return the response.
+            return $handler($request);
+        }
+    };
+
+    // Create a new handler that adds headers to each request.
+    $handler = $addHeaderHandler($handler, [
+        'X-AddMe'       => 'hello',
+        'Authorization' => 'Basic xyz'
+    ]);
+
+    $response = $handler([
+        'http_method' => 'GET',
+        'headers'     => ['Host' => ['httpbin.org']]
+    ]);
+
+Modifying Responses
+-------------------
+
+You can change a response as it's returned from a middleware. Remember that
+responses returned from an handler (including middleware) must implement
+``GuzzleHttp\Ring\Future\FutureArrayInterface``. In order to be a good citizen,
+you should not expect that the responses returned through your middleware will
+be completed synchronously. Instead, you should use the
+``GuzzleHttp\Ring\Core::proxy()`` function to modify the response when the
+underlying promise is resolved. This function is a helper function that makes it
+easy to create a new instance of ``FutureArrayInterface`` that wraps an existing
+``FutureArrayInterface`` object.
+
+Let's say you wanted to add headers to a response as they are returned from
+your middleware, but you want to make sure you aren't causing future
+responses to be dereferenced right away. You can achieve this by modifying the
+incoming request and using the ``Core::proxy`` function.
+
+.. code-block:: php
+
+    use GuzzleHttp\Ring\Core;
+    use GuzzleHttp\Ring\Client\CurlHandler;
+
+    $handler = new CurlHandler();
+
+    $responseHeaderHandler = function (callable $handler, array $headers) {
+        return function (array $request) use ($handler, $headers) {
+            // Send the request using the wrapped handler.
+            return Core::proxy($handler($request), function ($response) use ($headers) {
+                // Add the headers to the response when it is available.
+                foreach ($headers as $key => $value) {
+                    $response['headers'][$key] = (array) $value;
+                }
+                // Note that you can return a regular response array when using
+                // the proxy method.
+                return $response;
+            });
+        }
+    };
+
+    // Create a new handler that adds headers to each response.
+    $handler = $responseHeaderHandler($handler, ['X-Header' => 'hello!']);
+
+    $response = $handler([
+        'http_method' => 'GET',
+        'headers'     => ['Host' => ['httpbin.org']]
+    ]);
+
+    assert($response['headers']['X-Header'] == 'hello!');
+
+Built-In Middleware
+-------------------
+
+RingPHP comes with a few basic client middlewares that modify requests
+and responses.
+
+Streaming Middleware
+~~~~~~~~~~~~~~~~~~~~
+
+If you want to send all requests with the ``streaming`` option to a specific
+handler but other requests to a different handler, then use the streaming
+middleware.
+
+.. code-block:: php
+
+    use GuzzleHttp\Ring\Client\CurlHandler;
+    use GuzzleHttp\Ring\Client\StreamHandler;
+    use GuzzleHttp\Ring\Client\Middleware;
+
+    $defaultHandler = new CurlHandler();
+    $streamingHandler = new StreamHandler();
+    $streamingHandler = Middleware::wrapStreaming(
+        $defaultHandler,
+        $streamingHandler
+    );
+
+    // Send the request using the streaming handler.
+    $response = $streamingHandler([
+        'http_method' => 'GET',
+        'headers'     => ['Host' => ['www.google.com']],
+        'stream'      => true
+    ]);
+
+    // Send the request using the default handler.
+    $response = $streamingHandler([
+        'http_method' => 'GET',
+        'headers'     => ['Host' => ['www.google.com']]
+    ]);
+
+Future Middleware
+~~~~~~~~~~~~~~~~~
+
+If you want to send all requests with the ``future`` option to a specific
+handler but other requests to a different handler, then use the future
+middleware.
+
+.. code-block:: php
+
+    use GuzzleHttp\Ring\Client\CurlHandler;
+    use GuzzleHttp\Ring\Client\CurlMultiHandler;
+    use GuzzleHttp\Ring\Client\Middleware;
+
+    $defaultHandler = new CurlHandler();
+    $futureHandler = new CurlMultiHandler();
+    $futureHandler = Middleware::wrapFuture(
+        $defaultHandler,
+        $futureHandler
+    );
+
+    // Send the request using the blocking CurlHandler.
+    $response = $futureHandler([
+        'http_method' => 'GET',
+        'headers'     => ['Host' => ['www.google.com']]
+    ]);
+
+    // Send the request using the non-blocking CurlMultiHandler.
+    $response = $futureHandler([
+        'http_method' => 'GET',
+        'headers'     => ['Host' => ['www.google.com']],
+        'future'      => true
+    ]);