Header plugin

Author: gsouf

plugins/header.rst

@@ -0,0 +1,121 @@
+Header Plugin
+=============
+
+Header plugins are useful to manage Request headers. Many operations are possible:
+
+Default headers values
+----------------------
+
+The HeaderDefaultPlugin allows to set default values for given headers. That mean if the request hasn't
+already a given header it will be set, but if the request already has a value for the given header
+the request wont be changed
+
+.. code:: php
+
+    use Http\Discovery\HttpClientDiscovery;
+    use Http\Plugins\PluginClient;
+    use Http\Plugins\HeaderDefaultPlugin;
+
+    $defaultUserAgent = 'Mozilla/5.0 (Windows NT 6.1; WOW64; rv:40.0) Gecko/20100101 Firefox/40.1';
+
+    $headerDefaultPlugin = new HeaderDefaultPlugin([
+        'User-Agent' => $defaultUserAgent
+    ]);
+
+
+    // If a request handled by this client doesn't have a 'User-Agent' header,
+    // then $defaultUserAgent will be used
+    // If a request handled by this client has already a 'User-Agent' header,
+    // then the request wont be changed
+    $pluginClient = new PluginClient(
+        HttpClientDiscovery::find(),
+        [$headerDefaultPlugin]
+    );
+
+Mandatory headers values
+------------------------
+
+The Http\Plugins\HeaderSetPlugin allows to fix values of given header. That mean that any request passing through
+this plugin will have the same values for given headers
+
+.. code:: php
+
+    use Http\Discovery\HttpClientDiscovery;
+    use Http\Plugins\PluginClient;
+    use Http\Plugins\HeaderSetPlugin;
+
+    $userAgent = 'Mozilla/5.0 (Windows NT 6.1; WOW64; rv:40.0) Gecko/20100101 Firefox/40.1';
+
+    $headerSetPlugin = new HeaderSetPlugin([
+        'User-Agent' => $userAgent,
+        'Accept' => 'application/json'
+    ]);
+
+
+    // Every request handled by this client will have the given 'User-Agent' and 'Accept' headers values
+    // If the request already has one of these header then it will be overridden with the given value
+    $pluginClient = new PluginClient(
+        HttpClientDiscovery::find(),
+        [$headerSetPlugin]
+    );
+
+
+
+Removing headers
+----------------
+
+The Http\Plugins\HeaderRemovePlugin allows to remove given headers from the request.
+That mean that any request passing through this plugin will be freed of the given headers
+
+.. code:: php
+
+    use Http\Discovery\HttpClientDiscovery;
+    use Http\Plugins\PluginClient;
+    use Http\Plugins\HeaderRemovePlugin;
+
+    $userAgent = 'Mozilla/5.0 (Windows NT 6.1; WOW64; rv:40.0) Gecko/20100101 Firefox/40.1';
+
+    $headerRemovePlugin = new HeaderRemovePlugin([
+        'User-Agent' => $userAgent
+    ]);
+
+
+    // If a request handled by this client has a 'User-Agent' header,
+    // then the 'User-Agent' header will be removed from the request
+    $pluginClient = new PluginClient(
+        HttpClientDiscovery::find(),
+        [$headerRemovePlugin]
+    );
+
+
+Appending header values
+-----------------------
+
+The Http\Plugins\HeaderAppendPlugin allows to set headers or to add values to existing headers.
+
+.. note::
+
+    This header is very specific and is mostly useful for headers like "forwarded"
+
+.. code:: php
+
+    use Http\Discovery\HttpClientDiscovery;
+    use Http\Plugins\PluginClient;
+    use Http\Plugins\HeaderAppendPlugin;
+
+    $myIp = '100.100.100.100';
+
+    $headerAppendPlugin = new HeaderAppendPlugin([
+        'X-Forwarded-For' => $myIp
+    ]);
+
+
+    // If a request handled by this client has already a 'X-Forwarded-For' header,
+    // then $myIp will be appended to the current 'X-Forwarded-For' header's value
+    // If a request handled by this client hasn't already a 'X-Forwarded-For' header,
+    // then the header 'X-Forwarded-For' header will be added to the request with $myIp as the value
+    $pluginClient = new PluginClient(
+        HttpClientDiscovery::find(),
+        [$headerAppendPlugin]
+    );
+