Merge pull request #76 from php-http/feature/plugins-doc

Feature/plugins doc

Author: ddeboer

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);

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.

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]
+    );

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.

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
+        }
+    }

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.

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/