From 20b0de7fe480dc67d8d6ad3e8a41b47784a8f05d Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Mon, 17 Oct 2016 11:30:12 +0200 Subject: [PATCH] cleanup documentation pages --- clients/buzz-adapter.rst | 2 +- clients/curl-client.rst | 2 +- clients/mock-client.rst | 4 +- components/multipart-stream-builder.rst | 2 +- development/contributing.rst | 8 ++-- development/documentation.rst | 4 +- httplug/introduction.rst | 4 +- httplug/library-developers.rst | 8 ++-- httplug/tutorial.rst | 16 ++++---- httplug/usage.rst | 6 +-- httplug/users.rst | 2 +- integrations/symfony-bundle.rst | 2 +- message/authentication.rst | 4 +- plugins/build-your-own.rst | 17 +++++---- plugins/headers.rst | 41 +++++++++------------ plugins/introduction.rst | 49 ++++++++++++++----------- plugins/retry.rst | 13 ++++--- 17 files changed, 94 insertions(+), 90 deletions(-) diff --git a/clients/buzz-adapter.rst b/clients/buzz-adapter.rst index f241dfa..8912c38 100644 --- a/clients/buzz-adapter.rst +++ b/clients/buzz-adapter.rst @@ -54,7 +54,7 @@ Or if you installed the :doc:`discovery ` layer:: The message factory parameter is mandatory if the discovery layer is not installed. -Be aware +Be Aware -------- This adapter violates the Liskov substitution principle in a rare edge case. When the adapter is configured to use diff --git a/clients/curl-client.rst b/clients/curl-client.rst index a337340..0fb7218 100644 --- a/clients/curl-client.rst +++ b/clients/curl-client.rst @@ -37,7 +37,7 @@ Or you can use :doc:`../discovery`:: $client = new Client(MessageFactoryDiscovery::find(), StreamFactoryDiscovery::find()); -Configuring client +Configuring Client ------------------ You can use `cURL options `_ to configure Client:: diff --git a/clients/mock-client.rst b/clients/mock-client.rst index 7190dc4..1a12e8b 100644 --- a/clients/mock-client.rst +++ b/clients/mock-client.rst @@ -14,7 +14,7 @@ To install the Mock client, run: $ composer require php-http/mock-client -Collect requests +Collect Requests ---------------- To make assertions:: @@ -40,7 +40,7 @@ To make assertions:: } } -Fake responses and exceptions +Fake Responses and Exceptions ----------------------------- Test how your code behaves when the HTTP client throws exceptions or returns diff --git a/components/multipart-stream-builder.rst b/components/multipart-stream-builder.rst index 120e508..54d6534 100644 --- a/components/multipart-stream-builder.rst +++ b/components/multipart-stream-builder.rst @@ -34,7 +34,7 @@ A multipart stream is a special kind of stream that is used to transfer files ov In the request above you see a set of HTTP headers and a body with two streams. The body starts and ends with a "boundary" and it is also this boundary that separates the streams. That boundary also needs to be specified in the ``Content-Type`` header. -Building a multipart stream +Building a Multipart Stream ``````````````````````````` To build a multipart stream you may use the ``MultipartStreamBuilder``. It is not coupled to any stream implementation so it needs a ``StreamFactory`` to create the streams. diff --git a/development/contributing.rst b/development/contributing.rst index 10f5865..a45b199 100644 --- a/development/contributing.rst +++ b/development/contributing.rst @@ -3,7 +3,7 @@ Contributing If you're here, you would like to contribute to this project and you're really welcome! -Bug reports +Bug Reports ----------- If you find a bug or a documentation issue, please report it or even better: fix it :). If you report it, @@ -14,7 +14,7 @@ please be as precise as possible. Here is a little list of required information: - Backtrace which might help identifying the bug -Security issues +Security Issues --------------- If you discover any security related issues, @@ -22,7 +22,7 @@ please contact us at security@php-http.org instead of submitting an issue on Git This allows us to fix the issue and release a security hotfix without publicly disclosing the vulnerability. -Feature requests +Feature Requests ---------------- If you think a feature is missing, please report it or even better: implement it :). If you report it, describe the more @@ -86,7 +86,7 @@ If your branch conflicts with the master branch, you will need to rebase and re- $ git pull --rebase upstream master $ git push -f origin feature-or-bug-fix-description -Coding standard +Coding Standard --------------- This repository follows the `PSR-2 standard`_ and so, if you want to contribute, diff --git a/development/documentation.rst b/development/documentation.rst index dc98466..d10a681 100644 --- a/development/documentation.rst +++ b/development/documentation.rst @@ -8,7 +8,7 @@ Install Sphinx -------------- -Install on local machine +Install on Local Machine ~~~~~~~~~~~~~~~~~~~~~~~~ The installation for Sphinx differs between system. See `Sphinx installation page`_ for details. When Sphinx is @@ -42,7 +42,7 @@ without entering the container shell: on the host too. -Build documentation +Build Documentation ------------------- Before we can build the documentation we have to make sure to install all requirements. diff --git a/httplug/introduction.rst b/httplug/introduction.rst index 43120f3..52b9dff 100644 --- a/httplug/introduction.rst +++ b/httplug/introduction.rst @@ -7,8 +7,8 @@ When all packages used in an application only specify HTTPlug, the application developers can choose the client that best fits their project and use the same client with all packages. -The client interfaces ---------------------- +Client Interfaces +----------------- HTTPlug defines two HTTP client interfaces that we kept as simple as possible: diff --git a/httplug/library-developers.rst b/httplug/library-developers.rst index 1c59bb8..4b3f32d 100644 --- a/httplug/library-developers.rst +++ b/httplug/library-developers.rst @@ -1,4 +1,4 @@ -HTTPlug for library developers +HTTPlug for Library Developers ============================== If you’re developing a library or framework that performs HTTP requests, you @@ -7,7 +7,7 @@ Instead, you should only make sure that *some* HTTP client is available. It is then up to your users to decide which HTTP client they want to include in their projects. This complies with the `dependency inversion principle`_. -Manage dependencies +Manage Dependencies ------------------- To depend on *some* HTTP client, specify either @@ -78,14 +78,14 @@ If your library relies on specific plugins, the recommended way is to provide a your users, so they can create the correct client from a base HttpClient. See :ref:`plugin-client.libraries` for a concrete example. -User documentation +User Documentation ------------------ To explain to your users that they need to install a concrete HTTP client, you can point them to :doc:`users`. -Your final ``composer.json`` +Your Final ``composer.json`` ---------------------------- Putting it all together your final ``composer.json`` is much likely to look similar to this: diff --git a/httplug/tutorial.rst b/httplug/tutorial.rst index 98b41a9..5c0d321 100644 --- a/httplug/tutorial.rst +++ b/httplug/tutorial.rst @@ -1,4 +1,4 @@ -HTTPlug tutorial +HTTPlug Tutorial ================ This tutorial should give you an idea how to use HTTPlug in your project. HTTPlug has two main use cases: @@ -17,7 +17,7 @@ We use Composer_ for dependency management. Install it if you don't have it yet. there is an integration available. Framework integrations will simplify the way you set up clients, letting you focus on handling the requests. -Setting up the project +Setting up the Project ---------------------- .. code-block:: bash @@ -32,7 +32,7 @@ The last command will install Guzzle as well as the Guzzle HTTPlug adapter and t We are now ready to start coding. -Writing some simple code +Writing Some Simple Code ------------------------ Create a file ``demo.php`` in the root folder and write the following code:: @@ -43,7 +43,7 @@ Create a file ``demo.php`` in the root folder and write the following code:: TODO: create client instance with discovery and do some requests -Using an asynchronous client +Using an Asynchronous Client ---------------------------- Asynchronous client accepts a PSR-7 ``RequestInterface`` and returns a ``Http\Promise\Promise``:: @@ -53,10 +53,10 @@ Asynchronous client accepts a PSR-7 ``RequestInterface`` and returns a ``Http\Pr $httpAsyncClient = HttpAsyncClientDiscovery::find(); $promise = $httpAsyncClient->sendAsyncRequest($request); -Using callback system -^^^^^^^^^^^^^^^^^^^^^ +Using the Callback System +^^^^^^^^^^^^^^^^^^^^^^^^^ -This promise allows you to add callbacks for when the response is available or an errors happens by using the then method:: +The promise allows you to add callbacks for when the response is available or an errors happens by using the then method:: $promise->then(function (ResponseInterface $response) { // onFulfilled callback @@ -161,7 +161,7 @@ Here is a full example of a classic usage when using the ``sendAsyncRequest`` me // Do your stuff with the response ... -Handling errors +Handling Errors --------------- TODO: explain how to handle exceptions, distinction between network exception and HttpException. diff --git a/httplug/usage.rst b/httplug/usage.rst index d4197f6..b327989 100644 --- a/httplug/usage.rst +++ b/httplug/usage.rst @@ -6,7 +6,7 @@ HTTPlug is relevant for three groups of users: .. toctree:: :maxdepth: 1 - Library users - Application developers - Library developers + Library Users + Application Developers + Library Developers diff --git a/httplug/users.rst b/httplug/users.rst index 906f9bf..f0ef522 100644 --- a/httplug/users.rst +++ b/httplug/users.rst @@ -71,7 +71,7 @@ HTTP client in your project, Composer will throw an error: You can solve this by including a HTTP client or adapter, as described above. -No message factories +No Message Factories ````````````````````` You may get an exception telling you that "No message factories found", this diff --git a/integrations/symfony-bundle.rst b/integrations/symfony-bundle.rst index b348aeb..85eec5d 100644 --- a/integrations/symfony-bundle.rst +++ b/integrations/symfony-bundle.rst @@ -223,7 +223,7 @@ You can configure a client with authentication. Valid authentication types are ` factory: 'httplug.factory.guzzle6' plugins: ['httplug.plugin.authentication.my_wsse'] -Special HTTP clients +Special HTTP Clients ```````````````````` If you want to use the ``FlexibleHttpClient`` or ``HttpMethodsClient`` from the ``php-http/message`` package you may specify that on the client configuration. diff --git a/message/authentication.rst b/message/authentication.rst index 48657b9..4ea6f2c 100644 --- a/message/authentication.rst +++ b/message/authentication.rst @@ -14,7 +14,7 @@ Installation $ composer require php-http/message -Authentication methods +Authentication Methods ^^^^^^^^^^^^^^^^^^^^^^ +----------------+---------------------------------------------------+-----------------------------------------------------+ @@ -149,7 +149,7 @@ The first argument is an authentication method, the second is a regular expressi $authentication = Matching::createUrlMatcher(new AuthenticationMethod(), '\/api'); -Implement your own +Implement Your Own ^^^^^^^^^^^^^^^^^^ Implementing an authentication method is easy: only one method needs to be implemented:: diff --git a/plugins/build-your-own.rst b/plugins/build-your-own.rst index 178ed6f..f3ce7ba 100644 --- a/plugins/build-your-own.rst +++ b/plugins/build-your-own.rst @@ -100,13 +100,16 @@ To better understand the whole process check existing implementations in the Contributing Your Plugins to PHP-HTTP ------------------------------------- -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. +We are open to contributions. If the plugin is of general interest, 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 .. _client-common package: https://github.com/php-http/client-common diff --git a/plugins/headers.rst b/plugins/headers.rst index d39c4d1..ce55d69 100644 --- a/plugins/headers.rst +++ b/plugins/headers.rst @@ -1,16 +1,15 @@ Header Plugins ============== -Header plugins are useful to manage request headers. Many operations are possible: +Header plugins are useful to manage request headers. Many operations are +possible with the provided plugins. -Default headers values +Default Headers Values ---------------------- -The plugin ``HeaderDefaultsPlugin`` allows you to set default values for given headers. -That means if a header is not set, it will be added. -However, if the header is already present, the request is left unchanged. - -.. code:: php +The plugin ``HeaderDefaultsPlugin`` allows you to define default values for +given headers. If a header is not set, it will be added. However, if the header +is already present, the request is left unchanged:: use Http\Discovery\HttpClientDiscovery; use Http\Client\Common\PluginClient; @@ -27,11 +26,12 @@ However, if the header is already present, the request is left unchanged. [$headerDefaultsPlugin] ); -Mandatory headers values +Mandatory Headers Values ------------------------ -The plugin ``HeaderSetPlugin`` allows you to fix values of given headers. That means that any request passing through -this plugin will have the given value for the given header. +The plugin ``HeaderSetPlugin`` allows you to fix values of given headers. That +means that any request passing through this plugin will be set to the specified +value. Existing values of the header will be overwritten. .. code:: php @@ -51,12 +51,10 @@ this plugin will have the given value for the given header. [$headerSetPlugin] ); - - -Removing headers +Removing Headers ---------------- -The plugin ``HeaderRemovePlugin`` allows you to remove given headers from the request. +The plugin ``HeaderRemovePlugin`` allows you to remove headers from the request. .. code:: php @@ -64,8 +62,6 @@ The plugin ``HeaderRemovePlugin`` allows you to remove given headers from the re 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'; - $headerRemovePlugin = new HeaderRemovePlugin([ 'User-Agent' ]); @@ -75,17 +71,17 @@ The plugin ``HeaderRemovePlugin`` allows you to remove given headers from the re [$headerRemovePlugin] ); - -Appending header values +Appending Header Values ----------------------- -The plugin ``HeaderAppendPlugin`` allows you 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. +The plugin ``HeaderAppendPlugin`` allows you to add headers. The header will be +created if not existing yet. If the header already exists, the value will be +appended to the list of values for this header. .. note:: - This plugin is very specific and is mostly useful for headers like "forwarded" + The use cases for this plugin are limited. One real world example of + headers that can have multiple values is "Forwarded". .. code:: php @@ -104,7 +100,6 @@ but if the request does not already have the given header, it will be added to t [$headerAppendPlugin] ); - Mixing operations ----------------- diff --git a/plugins/introduction.rst b/plugins/introduction.rst index ffdf7cd..5426faf 100644 --- a/plugins/introduction.rst +++ b/plugins/introduction.rst @@ -23,12 +23,11 @@ How it works In the plugin package, you can find the following content: -- the Plugin Client itself which acts as a wrapper around any kind of HTTP Client (sync/async) -- a Plugin interface -- a set of core plugins (see the full list in the left side navigation) - -The Plugin Client accepts an HTTP Client implementation and an array of plugins. +- the ``PluginClient`` itself which acts as a wrapper around any kind of HTTP client (sync/async); +- the ``Plugin`` interface; +- a set of core plugins (see the full list in the left side navigation). +The ``PluginClient`` accepts an HTTP client implementation and an array of plugins. Let’s see an example:: use Http\Discovery\HttpClientDiscovery; @@ -47,31 +46,37 @@ Let’s see an example:: ] ); -The Plugin Client accepts and implements both ``Http\Client\HttpClient`` and ``Http\Client\HttpAsyncClient``, so you can use -both ways to send a request. In case the passed client implements only one of these interfaces, the Plugin Client +The ``PluginClient`` accepts and implements both ``Http\Client\HttpClient`` and +``Http\Client\HttpAsyncClient``, so you can use both ways to send a request. In +case the passed client implements only one of these interfaces, the ``PluginClient`` "emulates" the other behavior as a fallback. -It is important, that the order of plugins matters. During the request, plugins are called in the order they have -been added, from first to last. Once a response has been received, they are called again in reversed order, -from last to first. +It is important to note that the order of plugins matters. During the request, +plugins are executed in the order they have been specified in the constructor, +from first to last. Once a response has been received, the plugins are called +again in reversed order, from last to first. + +For our previous example, the execution chain will look like this: -In case of our previous example, the execution chain will look like this:: +.. code:: Request ---> PluginClient ---> RetryPlugin ---> RedirectPlugin ---> HttpClient ---- | (processing call) Response <--- PluginClient <--- RetryPlugin <--- RedirectPlugin <--- HttpClient <--- -In order to have correct behavior over the global process, you need to understand well how each plugin is used, -and manage a correct order when passing the array to the Plugin Client. +In order to achieve the intended behavior in the global process, you need to +pay attention to what each plugin does and define the correct order accordingly. -Retry Plugin will be best at the end to optimize the retry process, but it can also be good -to have it as the first plugin, if one of the plugins is inconsistent and may need a retry. +For example, the ``RetryPlugin`` should probably be at the end of the chain to +keep the retry process as short as possible. However, if one of the other +plugins is doing a fragile operation that might need a retry, place the retry +plugin before that. The recommended way to order plugins is the following: - 1. Plugins that modify the request should be at the beginning (like Authentication or Cookie Plugin) - 2. Plugins which intervene in the workflow should be in the "middle" (like Retry or Redirect Plugin) - 3. Plugins which log information should be last (like Logger or History Plugin) + 1. Plugins that modify the request should be at the beginning (like Authentication or Cookie Plugin); + 2. Plugins which intervene in the workflow should be in the "middle" (like Retry or Redirect Plugin); + 3. Plugins which log information should be last (like Logger or History Plugin). .. note:: @@ -79,11 +84,10 @@ The recommended way to order plugins is the following: to log the authentication information (like ``Authorization`` header) and choose to put the :doc:`Authentication Plugin ` after the doc:`Logger Plugin `. - Configuration Options --------------------- -The PluginClient accepts an array of configuration options that can tweak its behavior. +The ``PluginClient`` accepts an array of configuration options to tweak its behavior. .. _plugin-client.max-restarts: @@ -99,8 +103,8 @@ that value, execution is aborted and an error is raised. ``debug_plugins``: array of Plugin ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Debug plugins are injected between each normal plugin. This could be used to log the changes each -plugin does on the Request and Response objects. +The debug plugins are injected between each normal plugin. This can be used to +log the changes each plugin does on the request and response objects. .. _plugin-client.libraries: @@ -144,3 +148,4 @@ plugins or configure a different client. For example:: ); return new PluginClient($client, $plugins); } + } diff --git a/plugins/retry.rst b/plugins/retry.rst index c914404..969b426 100644 --- a/plugins/retry.rst +++ b/plugins/retry.rst @@ -2,8 +2,8 @@ Retry Plugin ============ The ``RetryPlugin`` can automatically attempt to re-send a request that failed, to work around -unreliable connections and servers. It relies on errors to throw exceptions, so you probably want -to place the :doc:`error` later in the plugin chain:: +unreliable connections and servers. It relies on errors to throw exceptions, so you need to +place something like the :doc:`ErrorPlugin ` later in the plugin chain:: use Http\Discovery\HttpClientDiscovery; use Http\Client\Common\PluginClient; @@ -20,11 +20,12 @@ to place the :doc:`error` later in the plugin chain:: .. warning:: - You should keep an eye on retried requests, as they add overhead. If some request fails due to - a client side mistake, retrying is only a waste of time and resources. + You should keep an eye on retried requests, as they add overhead. If a + request fails due to a client side mistake, retrying is only a waste of + time and resources. -Contrary to the :doc:`redirect` the retry plugin does not restart the chain but simply try again -from the current position. +Contrary to the :doc:`redirect`, the retry plugin does not restart the chain +but simply tries again from the current position. Options -------