Update plugin documentation

_static/custom.css

@@ -1,3 +1,7 @@
 .row-even .line-block, .row-odd .line-block {
     margin-left: 0;
 }
+
+.versionmodified {
+    font-weight: bold;
+}

components/client-common.rst

@@ -76,3 +76,8 @@ If one or more of the requests throw exceptions, they are added to the
     } catch (BatchException $e) {
         var_dump($e->getResult()->getExceptions());
     }
+
+PluginClient
+------------
+
+See :doc:`/plugins/introduction`

index.rst

@@ -37,13 +37,13 @@ Packages
 
 PHP-HTTP offers several packages:
 
-=============== =========================================================== =============================
+=============== =========================================================== ====================================
 Type            Description                                                 Namespace
-=============== =========================================================== =============================
+=============== =========================================================== ====================================
 Clients         HTTP clients: Socket, cURL and others                       ``Http\Client\[Name]``
 Client adapters Adapters for other clients: Guzzle, React and others        ``Http\Adapter\[Name]``
-Plugins         Implementation-independent authentication, cookies and more ``Http\Client\Plugin\[Name]``
-=============== =========================================================== =============================
+Plugins         Implementation-independent authentication, cookies and more ``Http\Client\Common\Plugin\[Name]``
+=============== =========================================================== ====================================
 
 Read more about :doc:`clients and adapters <clients>` and :doc:`plugins <plugins/index>`.
 

plugins/authentication.rst

@@ -6,8 +6,8 @@ from ``php-http/message`` to authenticate requests sent through the client::
 
     use Http\Discovery\HttpClientDiscovery;
     use Http\Message\Authentication\BasicAuth;
-    use Http\Client\Plugin\PluginClient;
-    use Http\Client\Plugin\AuthenticationPlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\AuthenticationPlugin;
 
     $authentication = new BasicAuth('username', 'password');
     $authenticationPlugin = new AuthenticationPlugin($authentication);

plugins/build-your-own.rst

@@ -4,7 +4,13 @@ Building Custom Plugins
 When writing your own Plugin, you need to be aware that the Plugin Client is async first.
 This means that every plugin must be written with Promises. More about this later.
 
-Each plugin must implement the ``Http\Client\Plugin\Plugin`` interface.
+Each plugin must implement the ``Http\Client\Common\Plugin`` interface.
+
+.. versionadded:: 1.1
+    The plugins were moved to the `client-common` package in version 1.1.
+    If you work with version 1.0, the interface is called ``Http\Client\Plugin\Plugin`` and
+    you need to require the separate `php-http/plugins` package.
+    The old interface will keep extending ``Http\Client\Common\Plugin``, but relying on it is deprecated.
 
 This interface defines the ``handleRequest`` method that allows to modify behavior of the call::
 
@@ -84,18 +90,18 @@ You can manipulate the ``ResponseInterface`` or the ``Exception`` by using the
     deprecate the old contract.
 
 To better understand the whole process check existing implementations in the
-`plugin repository`_.
+`client-common package`_.
 
 Contributing Your Plugins to PHP-HTTP
 -------------------------------------
 
-We are open to contributions. If the plugin is of general interest and is not too complex, the best
-is to do a Pull Request to ``php-http/plugins``. Please see the :doc:`contribution guide <../development/contributing>`.
+We are open to contributions. If the plugin is of general interest, is not too complex and does not have dependencies, the best
+is to do a Pull Request to ``php-http/client-common``. Please see the :doc:`contribution guide <../development/contributing>`.
 We don't promise that every plugin gets merged into the core. We need to keep the core as small as
 possible with only the most widely used plugins to keep it maintainable.
 
 The alternative is providing your plugins in your own repository. Please let us know when you do,
 we would like to add a list of existing third party plugins to the list of plugins.
 
 .. _PSR: https://groups.google.com/forum/?fromgroups#!topic/php-fig/wzQWpLvNSjs
-.. _plugin repository: https://github.com/php-http/plugins
+.. _client-common package: https://github.com/php-http/client-common

plugins/cache.rst

@@ -1,14 +1,24 @@
 Cache Plugin
 ============
 
+Install
+-------
+
+.. code-block:: bash
+
+    $ composer require php-http/cache-plugin
+
+Usage
+-----
+
 The ``CachePlugin`` allows you to cache responses from the server. It can use
 any PSR-6 compatible caching engine. By default, the plugin respects the cache
 control headers from the server as specified in :rfc:`7234`. It needs a
 :ref:`stream <stream-factory>` and a `PSR-6`_ implementation::
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Client\Plugin\PluginClient;
-    use Http\Client\Plugin\CachePlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\CachePlugin;
 
     /** @var \Psr\Cache\CacheItemPoolInterface $pool */
     $pool...

plugins/content-length.rst

@@ -5,8 +5,8 @@ The ``ContentLengthPlugin`` sets the correct ``Content-Length`` header value bas
 request. This helps HTTP servers to handle the request::
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Client\Plugin\PluginClient;
-    use Http\Client\Plugin\ContentLengthPlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\ContentLengthPlugin;
 
     $contentLengthPlugin = new ContentLengthPlugin();
 

plugins/cookie.rst

@@ -6,8 +6,8 @@ to :rfc:`6265#section-4` specification::
 
     use Http\Discovery\HttpClientDiscovery;
     use Http\Message\CookieJar;
-    use Http\Client\Plugin\PluginClient;
-    use Http\Client\Plugin\CookiePlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\CookiePlugin;
 
     $cookiePlugin = new CookiePlugin(new CookieJar());
 

plugins/decoder.rst

@@ -5,8 +5,8 @@ The ``DecoderPlugin`` decodes the body of the response with filters coming from
 or ``Content-Encoding`` headers::
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Client\Plugin\PluginClient;
-    use Http\Client\Plugin\DecoderPlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\DecoderPlugin;
 
     $decoderPlugin = new DecoderPlugin();
 

plugins/error.rst

@@ -3,16 +3,16 @@ Error Plugin
 
 The ``ErrorPlugin`` transforms responses with HTTP error status codes into exceptions:
 
- * 400-499 status code are transformed into ``Http\Client\Plugin\Exception\ClientErrorException``;
- * 500-599 status code are transformed into ``Http\Client\Plugin\Exception\ServerErrorException``
+ * 400-499 status code are transformed into ``Http\Client\Common\Exception\ClientErrorException``;
+ * 500-599 status code are transformed into ``Http\Client\Common\Exception\ServerErrorException``
 
 Both exceptions extend the ``Http\Client\Exception\HttpException`` class, so you can fetch the request
 and the response coming from them::
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Client\Plugin\PluginClient;
-    use Http\Client\Plugin\ErrorPlugin;
-    use Http\Client\Plugin\Exception\ClientErrorException;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\ErrorPlugin;
+    use Http\Client\Common\Exception\ClientErrorException;
 
     $errorPlugin = new ErrorPlugin();
 

plugins/headers.rst

@@ -13,8 +13,8 @@ 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;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\HeaderDefaultPlugin;
 
     $defaultUserAgent = 'Mozilla/5.0 (Windows NT 6.1; WOW64; rv:40.0) Gecko/20100101 Firefox/40.1';
 
@@ -36,8 +36,8 @@ this plugin will have the given value for given header.
 .. code:: php
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Plugins\PluginClient;
-    use Http\Plugins\HeaderSetPlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\HeaderSetPlugin;
 
     $userAgent = 'Mozilla/5.0 (Windows NT 6.1; WOW64; rv:40.0) Gecko/20100101 Firefox/40.1';
 
@@ -61,8 +61,8 @@ The plugin ``HeaderRemovePlugin`` allows to remove given headers from the reques
 .. code:: php
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Plugins\PluginClient;
-    use Http\Plugins\HeaderRemovePlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\HeaderRemovePlugin;
 
     $userAgent = 'Mozilla/5.0 (Windows NT 6.1; WOW64; rv:40.0) Gecko/20100101 Firefox/40.1';
 
@@ -90,8 +90,8 @@ but if the request does not already have the given header, it will be added to t
 .. code:: php
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Plugins\PluginClient;
-    use Http\Plugins\HeaderAppendPlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\HeaderAppendPlugin;
 
     $myIp = '100.100.100.100';
 
@@ -116,9 +116,9 @@ The following example will force the ``User-Agent`` and the ``Accept`` header va
 .. code:: php
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Plugins\PluginClient;
-    use Http\Plugins\HeaderSetPlugin;
-    use Http\Plugins\HeaderRemovePlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\HeaderSetPlugin;
+    use Http\Client\Common\Plugin\HeaderRemovePlugin;
 
     $userAgent = 'Mozilla/5.0 (Windows NT 6.1; WOW64; rv:40.0) Gecko/20100101 Firefox/40.1';
 

plugins/history.rst

@@ -1,12 +1,12 @@
 History Plugin
 ==============
 
-The ``HistoryPlugin`` notifies a ``Http\Client\Plugin\Journal`` of all
+The ``HistoryPlugin`` notifies a ``Http\Client\Common\Plugin\Journal`` of all
 successful and failed calls::
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Client\Plugin\PluginClient;
-    use Http\Client\Plugin\HistoryPlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\HistoryPlugin;
 
     $historyPlugin = new HistoryPlugin(new \My\Journal\Implementation());
 

plugins/introduction.rst

@@ -4,11 +4,19 @@ Introduction
 Install
 -------
 
-Install the plugin client in your project with Composer_:
+The plugin client and the core plugins are available in the `php-http/client-common`_ package:
 
 .. code-block:: bash
 
-    $ composer require php-http/plugins
+    $ composer require php-http/client-common
+
+.. _php-http/client-common: https://github.com/php-http/client-common
+
+.. versionadded:: 1.1
+    The plugins were moved to the clients-common package in version 1.1.
+    If you work with version 1.0, you need to require the separate `php-http/plugins` package
+    and the namespace is ``Http\Client\Plugin`` instead of ``Http\Client\Common``
+
 
 How it works
 ------------
@@ -24,9 +32,9 @@ The Plugin Client accepts an HTTP Client implementation and an array of plugins.
 Let’s see an example::
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Client\Plugin\PluginClient;
-    use Http\Client\Plugin\RetryPlugin;
-    use Http\Client\Plugin\RedirectPlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\RetryPlugin;
+    use Http\Client\Common\Plugin\RedirectPlugin;
 
     $retryPlugin = new RetryPlugin();
     $redirectPlugin = new RedirectPlugin();
@@ -99,6 +107,8 @@ plugins or configure a different client. For example::
     $myApiClient = new My\Api\Client('https://api.example.org', My\Api\HttpClientFactory::create('john', 's3cr3t'));
 
     use Http\Client\HttpClient;
+    use Http\Client\Common\Plugin\AuthenticationPlugin;
+    use Http\Client\Common\Plugin\ErrorPlugin;
     use Http\Discovery\HttpClientDiscovery;
 
     class HttpClientFactory
@@ -118,7 +128,7 @@ plugins or configure a different client. For example::
                 $client = HttpClientDiscovery::find();
             }
             return new PluginClient($client, [
-                new Http\Client\Plugin\ErrorPlugin(),
+                new ErrorPlugin(),
                 new AuthenticationPlugin(
                      // This API has it own authentication algorithm
                     new ApiAuthentication(Client::AUTH_OAUTH_TOKEN, $user, $pass)

plugins/logger.rst

@@ -1,12 +1,22 @@
 Logger Plugin
 =============
 
+Install
+-------
+
+.. code-block:: bash
+
+    $ composer require php-http/logger-plugin
+
+Usage
+-----
+
 The ``LoggerPlugin`` converts requests, responses and exceptions to strings and logs them with a PSR3_
 compliant logger::
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Client\Plugin\PluginClient;
-    use Http\Client\Plugin\LoggerPlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\LoggerPlugin;
     use Monolog\Logger;
 
     $loggerPlugin = new LoggerPlugin(new Logger('http'));

plugins/redirect.rst

@@ -12,8 +12,8 @@ situation is caught by the plugin client itself and can be controlled through th
 Initiate the redirect plugin as follows::
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Client\Plugin\PluginClient;
-    use Http\Client\Plugin\RedirectPlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\RedirectPlugin;
 
     $redirectPlugin = new RedirectPlugin();
 
@@ -41,4 +41,4 @@ request.
 ``use_default_for_multiple``: bool (default: true)
 
 Whether to follow the default direction on the multiple redirection status code 300. If set to
-false, a status of 300 will raise the ``MultipleRedirectionException``.
+false, a status of 300 will raise the ``Http\Client\Common\Exception\MultipleRedirectionException``.

plugins/retry.rst

@@ -6,9 +6,9 @@ unreliable connections and servers. It relies on errors to throw exceptions, so
 to place the :doc:`error` later in the plugin chain::
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Client\Plugin\PluginClient;
-    use Http\Client\Plugin\ErrorPlugin;
-    use Http\Client\Plugin\RetryPlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\ErrorPlugin;
+    use Http\Client\Common\Plugin\RetryPlugin;
 
     $pluginClient = new PluginClient(
         HttpClientDiscovery::find(),

plugins/stopwatch.rst

@@ -1,12 +1,22 @@
 Stopwatch Plugin
 ================
 
+Install
+-------
+
+.. code-block:: bash
+
+    $ composer require php-http/stopwatch-plugin
+
+Usage
+-----
+
 The ``StopwatchPlugin`` records the duration of HTTP requests with a
 ``Symfony\Component\Stopwatch\Stopwatch`` instance::
 
     use Http\Discovery\HttpClientDiscovery;
-    use Http\Client\Plugin\PluginClient;
-    use Http\Client\Plugin\StopwatchPlugin;
+    use Http\Client\Common\PluginClient;
+    use Http\Client\Common\Plugin\StopwatchPlugin;
     use Symfony\Component\Stopwatch\Stopwatch;
 
     $stopwatch = new Stopwatch();