diff --git a/plugins/authentication.rst b/plugins/authentication.rst index f4ead22..6dee325 100644 --- a/plugins/authentication.rst +++ b/plugins/authentication.rst @@ -6,8 +6,8 @@ from ``php-http/message`` to authenticate requests sent through the client:: use Http\Discovery\HttpClientDiscovery; use Http\Message\Authentication\BasicAuth; - use Http\Plugins\PluginClient; - use Http\Plugins\AuthenticationPlugin; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\AuthenticationPlugin; $authentication = new BasicAuth('username', 'password'); $authenticationPlugin = new AuthenticationPlugin($authentication); diff --git a/plugins/content-length.rst b/plugins/content-length.rst index 636e995..18beb56 100644 --- a/plugins/content-length.rst +++ b/plugins/content-length.rst @@ -1,4 +1,35 @@ Content-Length Plugin ===================== -TODO +The ``ContentLengthPlugin`` sets the correct ``Content-Length`` header value based on the size of the body stream of the +request. This helps HTTP servers to handle the request:: + + use Http\Discovery\HttpClientDiscovery; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\ContentLengthPlugin; + + $contentLengthPlugin = new ContentLengthPlugin(); + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [$contentLengthPlugin] + ); + +If the size of the stream can not be determined, the plugin sets the Encoding header to ``chunked``, as defined in +:rfc:`7230#section-4.1` + +This is useful when you want to transfer data of unknown size to an HTTP application without consuming memory. + +As an example, let's say you want to send a tar archive of the current directory to an API. Normally you would +end up doing this in 2 steps, first saving the result of the tar archive into a file or into the memory of +PHP with a variable, then sending this content with an HTTP Request. + +With this plugin you can achieve this behavior without doing the first step:: + + proc_open("/usr/bin/env tar c .", [["pipe", "r"], ["pipe", "w"], ["pipe", "w"]], $pipes, "/path/to/directory"); + $tarResource = $pipes[1]; + + $request = MessageFactoryDiscovery::find()->createRequest('POST', '/url/to/api/endpoint', [], $tarResource); + $response = $pluginClient->sendRequest($request); + +In this case the tar output is directly streamed to the server without using memory on the PHP side. diff --git a/plugins/cookie.rst b/plugins/cookie.rst index d6fa4f2..69ae613 100644 --- a/plugins/cookie.rst +++ b/plugins/cookie.rst @@ -1,4 +1,17 @@ Cookie Plugin ============= -TODO: explain the cookie plugin +The ``CookiePlugin`` allow you to store cookies in a ``CookieJar`` and reuse them on consequent requests according +to :rfc:`6265#section-4` specification:: + + use Http\Discovery\HttpClientDiscovery; + use Http\Message\CookieJar; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\CookiePlugin; + + $cookiePlugin = new CookiePlugin(new CookieJar()); + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [$cookiePlugin] + ); diff --git a/plugins/decoder.rst b/plugins/decoder.rst index dc19809..9de0a2f 100644 --- a/plugins/decoder.rst +++ b/plugins/decoder.rst @@ -1,4 +1,31 @@ Decoder Plugin ============== -TODO +The ``DecoderPlugin`` decodes the body of the response with filters coming from the ``Transfer-Encoding`` +or ``Content-Encoding`` headers:: + + use Http\Discovery\HttpClientDiscovery; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\DecoderPlugin; + + $decoderPlugin = new DecoderPlugin(); + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [$decoderPlugin] + ); + +The plugin can handle the following encodings: + + * ``chunked``: Decode a stream with a ``chunked`` encoding (no size in the ``Content-Length`` header of the response) + * ``compress``: Decode a stream encoded with the ``compress`` encoding according to :rfc:`1950` + * ``deflate``: Decode a stream encoded with the ``inflate`` encoding according to :rfc:`1951` + * ``gzip``: Decode a stream encoded with the ``gzip`` encoding according to :rfc:`1952` + +You can also use the decoder plugin to decode only the ``Transfer-Encoding`` header and not the ``Content-Encoding`` one +by setting the ``use_content_encoding`` configuration option to false:: + + $decoderPlugin = new DecoderPlugin(['use_content_encoding' => false]); + +Not decoding content is useful when you don't want to get the encoded response body, or acting as a proxy but sill +be able to decode message from the ``Transfer-Encoding`` header value. diff --git a/plugins/error.rst b/plugins/error.rst index 9ee9579..e900c53 100644 --- a/plugins/error.rst +++ b/plugins/error.rst @@ -1,4 +1,32 @@ Error Plugin ============ -TODO: explain the error plugin +The ``ErrorPlugin`` transforms responses with HTTP error status codes into exceptions: + + * 400-499 status code are transformed into ``Http\Client\Plugin\Exception\ClientErrorException``; + * 500-599 status code are transformed into ``Http\Client\Plugin\Exception\ServerErrorException`` + +Both exceptions extend the ``Http\Client\Exception\HttpException`` class, so you can fetch the request +and the response coming from them:: + + use Http\Discovery\HttpClientDiscovery; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\ErrorPlugin; + use Http\Client\Plugin\Exception\ClientErrorException; + + $errorPlugin = new ErrorPlugin(); + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [$errorPlugin] + ); + + ... + + try { + $response = $pluginClient->sendRequest($request); + } catch (ClientErrorException $e) { + if ($e->getResponse()->getStatusCode() == 404) { + // Something has not been found + } + } diff --git a/plugins/history.rst b/plugins/history.rst index 3f45ad6..a0e8831 100644 --- a/plugins/history.rst +++ b/plugins/history.rst @@ -1,4 +1,22 @@ History Plugin ============== -TODO: explain the error plugin +The ``HistoryPlugin`` notifies a Http\Client\Plugin\Journal of all successful and failed calls:: + + use Http\Discovery\HttpClientDiscovery; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\HistoryPlugin; + + $historyPlugin = new HistoryPlugin(new \My\Journal\Implementation()); + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [$historyPlugin] + ); + + +As an example, HttplugBundle uses this plugin to collect responses or exceptions associated with +requests for the debug toolbar + +This plugin only collect data after resolution. For logging purposes it's best to use the `LoggerPlugin` which logs +as soon as possible. diff --git a/plugins/logger.rst b/plugins/logger.rst index 108f5ff..6d8be69 100644 --- a/plugins/logger.rst +++ b/plugins/logger.rst @@ -1,4 +1,26 @@ Logger Plugin ============= -TODO +The ``LoggerPlugin`` converts requests, responses and exceptions to strings and logs them with a PSR3_ +compliant logger:: + + use Http\Discovery\HttpClientDiscovery; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\LoggerPlugin; + use Monolog\Logger; + + $loggerPlugin = new LoggerPlugin(new Logger('http')); + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [$loggerPlugin] + ); + +By default it uses ``Http\Message\Formatter\SimpleFormatter`` to format the request or the response into a string. +You can use any formatter implementing the ``Http\Message\Formatter`` interface:: + + $formatter = new \My\Formatter\Implemenation(); + + $loggerPlugin = new LoggerPlugin(new Logger('http'), $formatter); + +.. _PSR3: http://www.php-fig.org/psr/psr-3/