Fix typos

Author: joelwurtz

docs/plugins.md

@@ -1,12 +1,12 @@
 # Plugin System
 
-The plugin system allow to manipulate requests and responses inside an `HttpClient`.
+The plugin system allows to look at requests and responses and replace them if needed, inside an `HttpClient`.
 
-By using the `Http\Client\Plugin\PluginClient` you can inject an `HttpClient` or an `HttpAsyncClient`, and an array
+Using the `Http\Client\Plugin\PluginClient`, you can inject an `HttpClient`, or an `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.
+Each plugin can replace 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 response was received.
 
 ## Install
 
@@ -42,7 +42,7 @@ $pluginClient = new PluginClient(HttpClientDiscovery::find(), [
 ]);
 ```
 
-After you can use this plugin client like a classic `Http\Client\HttpClient` or `Http\Client\HttpAsyncClient` one:
+You can use the plugin client like a classic `Http\Client\HttpClient` or `Http\Client\HttpAsyncClient` one:
 
 ```php
 // Send a request
@@ -56,25 +56,24 @@ Go to the [tutorial](tutorial.md) to read more about using `HttpClient` and `Htt
 
 ## Available plugins
 
-Each plugin have its own configuration and dependencies, check the documentation for each of the available plugin:
+Each plugin has its own configuration and dependencies, check the documentation for each of the available plugins:
 
  - [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 
+ - [Cookie](plugins/cookie.md): Add cookies to request and save them from the response
+ - [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
+ - [Stopwatch](plugins/stopwatch.md): Log time of a request call by using [the Symfony Stopwatch component](http://symfony.com/doc/current/components/stopwatch.html)
 
 ## Order of plugins
 
-When you inject an array of plugins into the `PluginClient`, order of the plugins in array matters.
+When you inject an array of plugins into the `PluginClient`, the order of the plugins,  injected into the `PluginClient`, 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.
+During the request, plugins are called in the order they have in the array, from first to last plugin. Once a response has been received,
+they are called again in inverse order, from last to first.
 
-i.e. with the following code: 
+i.e. with the following code:
 
 ```php
 use Http\Discovery\HttpClientDiscovery;
@@ -102,26 +101,26 @@ 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 the end to optimize the retry process, but it can also be good 
+`RetryPlugin` will be best at the end to optimize the retry process, but it can also be good
 to have it as the first plugin, if one in the chain is inconsistent and may need a retry.
 
-Our recommendation, which apply to most of use cases, is to organize your plugins with following rules:
+The recommended way to order plugins is the following rules:
 
  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`)
+ 3. Plugins which log information 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.
+However, there can be exceptions to these rules. For example, for security reasons you might not want to log the authentication header
+and chose to put the AuthenticationPlugin after the LoggerPlugin.
 
 ## 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.
+When writing your own Plugin, you need to be aware that the `PluginClient` is async first. This means that every plugin must
+be written by respecting the `HttpAsyncClient` contract and returns a `Promise`.
 
 Each plugin must implement the `Http\Client\Plugin\Plugin` interface.
 
-This interface defined the `handleRequest` method which allow to modify behavior of the call:
+This interface defines the `handleRequest` method that allows to modify behavior of the call:
 
 ```php
 /**
@@ -136,31 +135,24 @@ This interface defined the `handleRequest` method which allow to modify behavior
 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` comes from upstream. You can replace it and pass a new version downstream if you need. 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` 
+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);
+
+    return $next($newRequest);
 }
 ```
 
 
-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` 
+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.
 
 ```
@@ -169,10 +161,10 @@ public function handleRequest(RequestInterface $request, callable $next, callabl
     if ($someCondition) {
         $newRequest = new Request();
         $promise    = $first($newRequest);
-        
+
         // Use the promise do some jobs ...
     }
-    
+
     return $next($request);
 }
 ```
@@ -187,12 +179,12 @@ 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;
     });
 }