From 9a867f8feb371060fafb3baf7e67a7d9243ce601 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rk=20S=C3=A1gi-Kaz=C3=A1r?= Date: Tue, 3 May 2016 01:06:33 +0200 Subject: [PATCH] Update plugin documentation --- _static/custom.css | 4 ++++ components/client-common.rst | 5 +++++ index.rst | 8 ++++---- plugins/authentication.rst | 4 ++-- plugins/build-your-own.rst | 16 +++++++++++----- plugins/cache.rst | 14 ++++++++++++-- plugins/content-length.rst | 4 ++-- plugins/cookie.rst | 4 ++-- plugins/decoder.rst | 4 ++-- plugins/error.rst | 10 +++++----- plugins/headers.rst | 22 +++++++++++----------- plugins/history.rst | 6 +++--- plugins/introduction.rst | 22 ++++++++++++++++------ plugins/logger.rst | 14 ++++++++++++-- plugins/redirect.rst | 6 +++--- plugins/retry.rst | 6 +++--- plugins/stopwatch.rst | 14 ++++++++++++-- 17 files changed, 109 insertions(+), 54 deletions(-) diff --git a/_static/custom.css b/_static/custom.css index 4c4a0d4..7bbb870 100644 --- a/_static/custom.css +++ b/_static/custom.css @@ -1,3 +1,7 @@ .row-even .line-block, .row-odd .line-block { margin-left: 0; } + +.versionmodified { + font-weight: bold; +} diff --git a/components/client-common.rst b/components/client-common.rst index 213b6f8..334e6bf 100644 --- a/components/client-common.rst +++ b/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` diff --git a/index.rst b/index.rst index 73acc2d..d7b23d0 100644 --- a/index.rst +++ b/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 ` and :doc:`plugins `. diff --git a/plugins/authentication.rst b/plugins/authentication.rst index 6dee325..f584e51 100644 --- a/plugins/authentication.rst +++ b/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); diff --git a/plugins/build-your-own.rst b/plugins/build-your-own.rst index 4267826..459f7ce 100644 --- a/plugins/build-your-own.rst +++ b/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,13 +90,13 @@ 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. @@ -98,4 +104,4 @@ The alternative is providing your plugins in your own repository. Please let us 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 diff --git a/plugins/cache.rst b/plugins/cache.rst index edfd2f3..3fd459c 100644 --- a/plugins/cache.rst +++ b/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 ` 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... diff --git a/plugins/content-length.rst b/plugins/content-length.rst index 18beb56..b8f0098 100644 --- a/plugins/content-length.rst +++ b/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(); diff --git a/plugins/cookie.rst b/plugins/cookie.rst index 69ae613..67af19c 100644 --- a/plugins/cookie.rst +++ b/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()); diff --git a/plugins/decoder.rst b/plugins/decoder.rst index 9de0a2f..207bdab 100644 --- a/plugins/decoder.rst +++ b/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(); diff --git a/plugins/error.rst b/plugins/error.rst index e900c53..eede57c 100644 --- a/plugins/error.rst +++ b/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(); diff --git a/plugins/headers.rst b/plugins/headers.rst index 0a36a49..7855a53 100644 --- a/plugins/headers.rst +++ b/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'; diff --git a/plugins/history.rst b/plugins/history.rst index d0f8348..eb46e7d 100644 --- a/plugins/history.rst +++ b/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()); diff --git a/plugins/introduction.rst b/plugins/introduction.rst index c704509..07f4b07 100644 --- a/plugins/introduction.rst +++ b/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) diff --git a/plugins/logger.rst b/plugins/logger.rst index 6d8be69..9265c12 100644 --- a/plugins/logger.rst +++ b/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')); diff --git a/plugins/redirect.rst b/plugins/redirect.rst index 78d5617..cb41652 100644 --- a/plugins/redirect.rst +++ b/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``. diff --git a/plugins/retry.rst b/plugins/retry.rst index 9050d7d..c914404 100644 --- a/plugins/retry.rst +++ b/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(), diff --git a/plugins/stopwatch.rst b/plugins/stopwatch.rst index 48cf01c..bb16816 100644 --- a/plugins/stopwatch.rst +++ b/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();