From 961ab2bc573155005d411e78955ac105e09d2c61 Mon Sep 17 00:00:00 2001 From: soufiane ghzal Date: Fri, 22 Jan 2016 22:49:25 +0100 Subject: [PATCH] Header plugin --- plugins/headers.rst | 142 ++++++++++++++++++++++++++++++++++++++++++++ plugins/index.rst | 1 + 2 files changed, 143 insertions(+) create mode 100644 plugins/headers.rst diff --git a/plugins/headers.rst b/plugins/headers.rst new file mode 100644 index 0000000..0a36a49 --- /dev/null +++ b/plugins/headers.rst @@ -0,0 +1,142 @@ +Header Plugins +============== + +Header plugins are useful to manage request headers. Many operations are possible: + +Default headers values +---------------------- + +The plugin ``HeaderDefaultPlugin`` allows to set default values for given headers. +That means if a header is not set, it will be added. +However, if the header already is present, the request is left unchanged. + +.. 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 plugin ``HeaderSetPlugin`` allows to fix values of given header. That means that any request passing through +this plugin will have the given value for given header. + +.. 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 plugin ``HeaderRemovePlugin`` allows to remove given headers from the request. + +.. 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 plugin ``HeaderAppendPlugin`` allows to set headers or to add values to existing headers. +That means if the request already has the given headers then the value will be appended to the current value +but if the request does not already have the given header, it will be added to the request with the given value. + +.. note:: + + This plugin 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 plugins can be mixed to achieve different behaviors +and you can use the same plugin for identical operations. + +The following example will force the ``User-Agent`` and the ``Accept`` header values while removing ``Cookie`` header: + +.. 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 + ] + ); + + diff --git a/plugins/index.rst b/plugins/index.rst index 84ab79f..a047d8f 100644 --- a/plugins/index.rst +++ b/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