Header plugin

Author: gsouf

plugins/headers.rst

@@ -0,0 +1,143 @@
+Header Plugins
+==============
+
+Header plugins are useful to manage request headers. Many operations are possible:
+
+Default headers values
+----------------------
+
+The plugin Http\Plugins\HeaderDefaultPlugin allows to set default values for given headers.
+That means 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 then 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
+    ]);
+
+    $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'
+    ]);
+
+    $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'
+    ]);
+
+    $pluginClient = new PluginClient(
+        HttpClientDiscovery::find(),
+        [$headerRemovePlugin]
+    );
+
+
+Appending header values
+-----------------------
+
+The Http\Plugins\HeaderAppendPlugin allows to set headers or to add values to existing headers.
+That means if the request has already the given headers then the value will be appended to the current value
+but if the request hasn't already the given header the header will be added to the request with the given value.
+
+.. 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([
+        'Forwarded' => 'for=' . $myIp
+    ]);
+
+    $pluginClient = new PluginClient(
+        HttpClientDiscovery::find(),
+        [$headerAppendPlugin]
+    );
+
+
+Mixing operations
+-----------------
+
+Different header operations can be mixed by using the together in the same header plugin
+but you can use the same plugin for identical operations
+
+The following example will set the force the "User-Agent" and the "Accept" headers while removing cookies:
+
+.. code:: php
+
+    use Http\Discovery\HttpClientDiscovery;
+    use Http\Plugins\PluginClient;
+    use Http\Plugins\HeaderSetPlugin;
+    use Http\Plugins\HeaderRemovePlugin;
+
+    $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'
+    ]);
+
+    $headerRemovePlugin = new HeaderRemovePlugin([
+        'Cookie'
+    ]);
+
+    $pluginClient = new PluginClient(
+        HttpClientDiscovery::find(),
+        [
+            $headerSetPlugin,
+            $headerRemovePlugin
+        ]
+    );
+
+

plugins/index.rst

@@ -15,6 +15,7 @@ request or you can even start a completely new request. This gives you full cont
    cookie
    decoder
    error
+   headers
    history
    logger
    redirect