Add plugin documentation

Author: joelwurtz

docs/plugins.md

@@ -1,5 +1,202 @@
 # Plugin System
 
-The plugin system will allow to manipulate requests and responses inside a `HttpClient`.
+The plugin system allow to manipulate requests and responses inside a `HttpClient`.
 
-TODO: finalize system and document.
+By using the `Http\Client\Plugin\PluginClient` you can inject a `HttpClient` or a `HttpAsyncClient`, and an array
+of plugins implementing the `Http\Client\Plugin\Plugin` interface.
+
+Each plugin can modify the `RequestInterface` sent or the `ResponseInterface` received. It can also change the behavior of a call
+like retrying the request or emit another one when a redirection is present.
+
+## Install
+
+Install the plugin client in your project with composer:
+
+``` bash
+composer require "php-http/plugins:^1.0"
+```
+
+## Usage
+
+First you need to have some plugins:
+
+```php
+use Http\Client\Plugin\RetryPlugin;
+use Http\Client\Plugin\RedirectPlugin;
+
+$retryPlugin = new RetryPlugin();
+$redirectPlugin = new RedirectPlugin();
+```
+
+Then you can create a `PluginClient`:
+
+```php
+use Http\Discovery\HttpClientDiscovery;
+use Http\Client\Plugin\PluginClient;
+
+...
+
+$pluginClient = new PluginClient(HttpClientDiscovery::find(), [
+    $retryPlugin,
+    $redirectPlugin
+]);
+```
+
+After you can use this plugin client like a classic `Http\Client\HttpClient` or `Http\Client\HttpAsyncClient` one:
+
+```php
+// Send a request
+$response = $pluginClient->sendRequest($request);
+
+// Send an asynchronous request
+$promise  = $pluginClient->sendAsyncRequest($request);
+```
+
+Read the [tutorial](tutorial.md) to know more about `HttpClient` and `HttpAsyncClient`
+
+## Available plugins
+
+Each plugin have its own configuration and dependencies, check the documentation for each of the available plugin:
+
+ - [Authentication](plugins/authentication.md): Add authentication header on a request
+ - [Cookie](plugins/cookie.md): Add cookie to request and save them from the response by using a CookieJar
+ - [Encoding](plugins/encoding.md): Add support for receiving chunked, deflate or gzip response 
+ - [Error](plugins/error.md): Transform bad response (400 to 599) to exception
+ - [Redirect](plugins/redirect.md): Follow redirection coming from 3XX responses
+ - [Retry](plugins/retry.md): Retry a failed call
+ - [Stopwatch](plugins/stopwatch.md): Log time of a request call by using the Stopwatch component
+
+## Order of plugins
+
+When you inject an array of plugins into the `PluginClient`, order of the plugins in array matters.
+
+Plugins are transformed into a plugin chain, where the first element in array will be called first, and, 
+obviously, the last element will be called at the end. However when the `ResponseInterface` or the `Promise` is
+received from the underlying client, this execution chain is revert and the last plugin defined will be called first.
+
+i.e. with the following code: 
+
+```php
+use Http\Discovery\HttpClientDiscovery;
+use Http\Client\Plugin\PluginClient;
+use Http\Client\Plugin\RetryPlugin;
+use Http\Client\Plugin\RedirectPlugin;
+
+$retryPlugin = new RetryPlugin();
+$redirectPlugin = new RedirectPlugin();
+
+$pluginClient = new PluginClient(HttpClientDiscovery::find(), [
+    $retryPlugin,
+    $redirectPlugin
+]);
+```
+
+The execution chain will look like this:
+
+```
+Request  ---> PluginClient ---> RetryPlugin ---> RedirectPlugin ---> HttpClient ----
+                                                                                   | (processing call)
+Response <--- PluginClient <--- RetryPlugin <--- RedirectPlugin <--- HttpClient <---
+```
+
+In order to have correct behavior over the global process, you need to understand well each plugin used,
+and manage a correct order when passing the array to the `PluginClient`
+
+`RetryPlugin` will be best at then for example if you want to optimize the retry process, but also it can be good 
+to have it in the first plugin, if one is inconsistent and may need a retry.
+
+Our recommendation, which apply to most of the use case, is to organize your plugins with the following rule:
+
+ 1. Plugins that modify the request should be at the beginning (like the `AuthenticationPlugin` or the `CookiePlugin`)
+ 2. Plugins which intervene in the workflow should be in the "middle" (like the `RetryPlugin` or the `RedirectPlugin`)
+ 3. Plugins which log and a debug information about a call should be last (like the `LoggerPlugin` or the `HistoryPlugin`)
+
+However there may be exception in this rule, if, for security reason, you don't want to log the authentication header, it will be better to put
+this plugin after the `LoggerPlugin` one.
+
+## Implementing your own Plugin
+
+When writing your own Plugin, you need to be aware that the `PluginClient` is async first. It means that every plugin must
+be written by respecting the `HttpAsyncClient` contract and use `Promise` as the return.
+
+Each plugin must implement the `Http\Client\Plugin\Plugin` interface.
+
+This interface defined the `handleRequest` method which allow to modify behavior of the call:
+
+```php
+/**
+ * handle the request and return the response coming from the next callable
+ *
+ * @param RequestInterface $request Request to use
+ * @param callable         $next    Callback to call to have the request, it muse have the request as it first argument
+ * @param callable         $first   First element in the plugin chain, used to to restart a request from the beginning
+ *
+ * @return Promise
+ */
+public function handleRequest(RequestInterface $request, callable $next, callable $first);
+```
+
+The `$request` is the one created by the client, you can transform it, or do what you like with it. Always be aware that
+the request is immutable.
+
+```
+public function handleRequest(RequestInterface $request, callable $next, callable $first)
+{
+    $newRequest = $request->withHeader('MyHeader', 'MyValue');
+}
+```
+
+The `$next` callable is the next plugin in the execution chain. When you need to call it, you must pass the `$request` 
+as the first argument of this callable.
+
+```
+public function handleRequest(RequestInterface $request, callable $next, callable $first)
+{
+    $newRequest = $request->withHeader('MyHeader', 'MyValue');
+    
+    return $next($request);
+}
+```
+
+
+The `$first` callable is the first plugin in the execution. It allows you to completely reboot the execution chain, or sends 
+other request if needed while still using all the plugins defined. Like the `$next` callable, you must pass the `$request` 
+as the first argument of this callable.
+
+```
+public function handleRequest(RequestInterface $request, callable $next, callable $first)
+{
+    if ($someCondition) {
+        $newRequest = new Request();
+        $promise    = $first($newRequest);
+        
+        // Use the promise do some jobs ...
+    }
+    
+    return $next($request);
+}
+```
+
+In this example the condition is not superfluous, you need to have some way to not calling the $first callable each time or
+you will end up with a infinite execution loop.
+
+The `$next` and `$first` callable will return a `Promise`, you can manipulate the `ResponseInterface` or the `Exception`
+by using the `then` method of the promise.
+
+```
+public function handleRequest(RequestInterface $request, callable $next, callable $first)
+{
+    $newRequest = $request->withHeader('MyHeader', 'MyValue');
+    
+    return $next($request)->then(function (ResponseInterface $response) {
+        return $response->withHeader('MyResponseHeader', 'value');
+    }, function (Exception $exception) {
+        echo $exception->getMessage();
+        
+        throw $exception;
+    });
+}
+```
+
+Anyway it is always a good practice to read existing implementation inside the [plugin repository](https://github.com/php-http/plugins) to better understand the whole
+process;

docs/plugins/authentication.md

@@ -0,0 +1,3 @@
+# Authentication Plugin
+
+TODO: explain the authentication plugin

docs/plugins/cookie.md

@@ -0,0 +1,3 @@
+# Cookie Plugin
+
+TODO: explain the cookie plugin

docs/plugins/encoding.md

@@ -0,0 +1,3 @@
+# Encoding Plugin
+
+TODO: explain the encoding plugin

docs/plugins/error.md

@@ -0,0 +1,3 @@
+# Error Plugin
+
+TODO: explain the error plugin

docs/plugins/redirect.md

@@ -0,0 +1,3 @@
+# Redirect Plugin
+
+TODO: explain the redirect plugin

docs/plugins/retry.md

@@ -0,0 +1,3 @@
+# Retry Plugin
+
+TODO: explain the retry plugin

docs/plugins/stopwatch.md

@@ -0,0 +1,3 @@
+# Stopwatch Plugin
+
+TODO: explain the stopwatch plugin