From a97c580fd7201cedd0113d4ce1d4fe362d244ede Mon Sep 17 00:00:00 2001 From: Joel Wurtz Date: Sun, 17 Jan 2016 17:19:09 +0100 Subject: [PATCH 1/5] Add documentation about content length plugin --- plugins/content-length.rst | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/plugins/content-length.rst b/plugins/content-length.rst index 636e995..08c5fdc 100644 --- a/plugins/content-length.rst +++ b/plugins/content-length.rst @@ -1,4 +1,38 @@ Content-Length Plugin ===================== -TODO +The Content-Length ia Plugin allowing to make your HTTP Request compliant with most of the servers. +It's main purpose is to set the correct `Content-Length` Header value based on your stream. + +However if it's failed to get the size of a stream, it will then set the correct header and stream +decorator to send the body of the request with Chunked transfer encoding as defined in the `RFC 2145`_:: + + use Http\Discovery\HttpClientDiscovery; + use Http\Plugins\PluginClient; + use Http\Plugins\ContentLengthPlugin; + + $contentLengthPlugin = new ContentLengthPlugin(); + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [$contentLengthPlugin] + ); + +One of the main advantage of using this plugin, is when you want to transfer information from a stream +to an http application without consuming memory. + +As an example, let's you want to send an archive tar of the current directory to an api. Normally you will +end up doing this in 2 steps, first saving the result of the tar archive into a file our into the memory of +PHP with a variable, then sending this content with an HTTP Request. + +With this plugin you can achieve this behavior without doing the first step:: + + proc_open("/usr/bin/env tar c .", [["pipe", "r"], ["pipe", "w"], ["pipe", "w"]], $pipes, "/path/to/directory"); + $tarResource = $pipes[1]; + + $request = MessageFactoryDiscovery::find()->createRequest('POST', '/url/to/api/endpoint', [], $tarResource); + $response = $pluginClient->sendRequest($request); + +In this case the tar output is directly streamed to the server without using memory on the PHP side. + +.. _RFC 2145: https://www.ietf.org/rfc/rfc2145.txt From d61e497292858f1ba77f750c746838b0fdf0f1e2 Mon Sep 17 00:00:00 2001 From: Joel Wurtz Date: Sun, 17 Jan 2016 18:02:54 +0100 Subject: [PATCH 2/5] Add cookie documentation --- plugins/cookie.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/plugins/cookie.rst b/plugins/cookie.rst index d6fa4f2..cb590e8 100644 --- a/plugins/cookie.rst +++ b/plugins/cookie.rst @@ -1,4 +1,19 @@ Cookie Plugin ============= -TODO: explain the cookie plugin +Cookie plugins allow you to sore cookies information in a `CookieJar` and reuses them on consequent requests according +to `RFC 6265`_ specification:: + + use Http\Discovery\HttpClientDiscovery; + use Http\Message\CookieJar; + use Http\Plugins\PluginClient; + use Http\Plugins\CookiePlugin; + + $cookiePlugin = new CookiePlugin(new CookieJar()); + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [$cookiePlugin] + ); + +.. _RFC 6265: https://tools.ietf.org/html/rfc6265 From dfae08383c0ca5d67b7efa7b287a053974db41c2 Mon Sep 17 00:00:00 2001 From: Joel Wurtz Date: Sun, 17 Jan 2016 18:10:41 +0100 Subject: [PATCH 3/5] Add decoder plugin documentation --- plugins/decoder.rst | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/plugins/decoder.rst b/plugins/decoder.rst index dc19809..083d6c9 100644 --- a/plugins/decoder.rst +++ b/plugins/decoder.rst @@ -1,4 +1,34 @@ Decoder Plugin ============== -TODO +Decoder Plugin decodes the body of the response with filters coming from the `Transfer-Encoding` or `Content-Encoding` +headers:: + + use Http\Discovery\HttpClientDiscovery; + use Http\Plugins\PluginClient; + use Http\Plugins\DecoderPlugin; + + $decoderPlugin = new DecoderPlugin(); + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [$decoderPlugin] + ); + +Actually it can decodes 4 different filters: + + * chunked: Decode a stream with a chunked encoding (no size in the `Content-Length` header of the response) + * compress: Decode a stream encoded with the compress filter according to `RFC 1950`_ + * Deflate: Decode a stream encoded with the inflate filter according to `RFC 1951`_ + * gzip: Decode a stream encoded with the gzip filter according to `RFC 1952`_ + +You can also use the decoder plugin to only decodes the `Transfer-Encoding` header and not the `Content-Encoding` one +by setting the first parameter of the constructor to false:: + + $decoderPlugin = new DecoderPlugin(false); + +This is useful when you want to get the encoded response body, or acting as a proxy. + +.. _RFC 1950: https://tools.ietf.org/html/rfc1950 +.. _RFC 1951: https://tools.ietf.org/html/rfc1951 +.. _RFC 1952: https://tools.ietf.org/html/rfc1952 From b9aceb30991f770518e9f4aa220547c9d024277d Mon Sep 17 00:00:00 2001 From: Joel Wurtz Date: Sun, 17 Jan 2016 18:19:36 +0100 Subject: [PATCH 4/5] Add error plugin documentation --- plugins/authentication.rst | 4 ++-- plugins/content-length.rst | 16 ++++++++-------- plugins/cookie.rst | 4 ++-- plugins/decoder.rst | 4 ++-- plugins/error.rst | 30 +++++++++++++++++++++++++++++- plugins/history.rst | 15 ++++++++++++++- 6 files changed, 57 insertions(+), 16 deletions(-) diff --git a/plugins/authentication.rst b/plugins/authentication.rst index f4ead22..6dee325 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\Plugins\PluginClient; - use Http\Plugins\AuthenticationPlugin; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\AuthenticationPlugin; $authentication = new BasicAuth('username', 'password'); $authenticationPlugin = new AuthenticationPlugin($authentication); diff --git a/plugins/content-length.rst b/plugins/content-length.rst index 08c5fdc..6e7b0c1 100644 --- a/plugins/content-length.rst +++ b/plugins/content-length.rst @@ -1,15 +1,15 @@ Content-Length Plugin ===================== -The Content-Length ia Plugin allowing to make your HTTP Request compliant with most of the servers. -It's main purpose is to set the correct `Content-Length` Header value based on your stream. +The Content-Length Plugin allows you to make your HTTP Request compliant with most of the servers. +It's main purpose is to set the correct `Content-Length` Header value based on your stream size. -However if it's failed to get the size of a stream, it will then set the correct header and stream -decorator to send the body of the request with Chunked transfer encoding as defined in the `RFC 2145`_:: +However if it's failed to get the size of a stream, it will set the correct header and decorate the body of the request +with Chunked transfer encoding as defined in the `RFC 2145`_:: use Http\Discovery\HttpClientDiscovery; - use Http\Plugins\PluginClient; - use Http\Plugins\ContentLengthPlugin; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\ContentLengthPlugin; $contentLengthPlugin = new ContentLengthPlugin(); @@ -18,10 +18,10 @@ decorator to send the body of the request with Chunked transfer encoding as defi [$contentLengthPlugin] ); -One of the main advantage of using this plugin, is when you want to transfer information from a stream +One of the main advantage of using this plugin, is when you want to transfer information from an existing stream to an http application without consuming memory. -As an example, let's you want to send an archive tar of the current directory to an api. Normally you will +As an example, let's say you want to send an archive tar of the current directory to an api. Normally you will end up doing this in 2 steps, first saving the result of the tar archive into a file our into the memory of PHP with a variable, then sending this content with an HTTP Request. diff --git a/plugins/cookie.rst b/plugins/cookie.rst index cb590e8..51ad87d 100644 --- a/plugins/cookie.rst +++ b/plugins/cookie.rst @@ -6,8 +6,8 @@ to `RFC 6265`_ specification:: use Http\Discovery\HttpClientDiscovery; use Http\Message\CookieJar; - use Http\Plugins\PluginClient; - use Http\Plugins\CookiePlugin; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\CookiePlugin; $cookiePlugin = new CookiePlugin(new CookieJar()); diff --git a/plugins/decoder.rst b/plugins/decoder.rst index 083d6c9..bb65e40 100644 --- a/plugins/decoder.rst +++ b/plugins/decoder.rst @@ -5,8 +5,8 @@ Decoder Plugin decodes the body of the response with filters coming from the `Tr headers:: use Http\Discovery\HttpClientDiscovery; - use Http\Plugins\PluginClient; - use Http\Plugins\DecoderPlugin; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\DecoderPlugin; $decoderPlugin = new DecoderPlugin(); diff --git a/plugins/error.rst b/plugins/error.rst index 9ee9579..d60a7f6 100644 --- a/plugins/error.rst +++ b/plugins/error.rst @@ -1,4 +1,32 @@ Error Plugin ============ -TODO: explain the error plugin +Error plugin will transform response with specific status code into exception: + + * 400-499 status code are transformed into `Http\Client\Plugin\Exception\ClientErrorException`; + * 500-599 status code are transformed into `Http\Client\Plugin\Exception\ServerErrorException` + +Both of this exceptions extends the `Http\Client\Exception\HttpException` exception class, so you can fetch the request +and the response coming from this exception:: + + use Http\Discovery\HttpClientDiscovery; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\ErrorPlugin; + use Http\Client\Plugin\Exception\ClientErrorException; + + $errorPlugin = new ErrorPlugin(); + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [$errorPlugin] + ); + + ... + + try { + $response = $pluginClient->sendRequest($request); + } catch (ClientErrorException $e) { + if ($e->getResponse()->getStatusCode() == 404) { + // Something has not been found + } + } diff --git a/plugins/history.rst b/plugins/history.rst index 3f45ad6..953cb7d 100644 --- a/plugins/history.rst +++ b/plugins/history.rst @@ -1,4 +1,17 @@ History Plugin ============== -TODO: explain the error plugin +History plugin use a `Http\Client\Plugin\Journal` to collect successful or failed calls of an Http Client. This is +mainly used for debugging like in the Symfony Bundle to get information in the debug toolbar with a DataCollector:: + + use Http\Discovery\HttpClientDiscovery; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\HistoryPlugin; + + $historyPlugin = new HistoryPlugin(new \My\Journal\Implementation()); + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [$historyPlugin] + ); + From c5b27952b68f7f9ee61559341fc914429cfcf600 Mon Sep 17 00:00:00 2001 From: Joel Wurtz Date: Sun, 17 Jan 2016 19:01:49 +0100 Subject: [PATCH 5/5] Add documentation for the logger plugin --- plugins/content-length.rst | 19 ++++++++----------- plugins/cookie.rst | 6 ++---- plugins/decoder.rst | 27 ++++++++++++--------------- plugins/error.rst | 10 +++++----- plugins/history.rst | 9 +++++++-- plugins/logger.rst | 24 +++++++++++++++++++++++- 6 files changed, 57 insertions(+), 38 deletions(-) diff --git a/plugins/content-length.rst b/plugins/content-length.rst index 6e7b0c1..18beb56 100644 --- a/plugins/content-length.rst +++ b/plugins/content-length.rst @@ -1,11 +1,8 @@ Content-Length Plugin ===================== -The Content-Length Plugin allows you to make your HTTP Request compliant with most of the servers. -It's main purpose is to set the correct `Content-Length` Header value based on your stream size. - -However if it's failed to get the size of a stream, it will set the correct header and decorate the body of the request -with Chunked transfer encoding as defined in the `RFC 2145`_:: +The ``ContentLengthPlugin`` sets the correct ``Content-Length`` header value based on the size of the body stream of the +request. This helps HTTP servers to handle the request:: use Http\Discovery\HttpClientDiscovery; use Http\Client\Plugin\PluginClient; @@ -18,11 +15,13 @@ with Chunked transfer encoding as defined in the `RFC 2145`_:: [$contentLengthPlugin] ); -One of the main advantage of using this plugin, is when you want to transfer information from an existing stream -to an http application without consuming memory. +If the size of the stream can not be determined, the plugin sets the Encoding header to ``chunked``, as defined in +:rfc:`7230#section-4.1` + +This is useful when you want to transfer data of unknown size to an HTTP application without consuming memory. -As an example, let's say you want to send an archive tar of the current directory to an api. Normally you will -end up doing this in 2 steps, first saving the result of the tar archive into a file our into the memory of +As an example, let's say you want to send a tar archive of the current directory to an API. Normally you would +end up doing this in 2 steps, first saving the result of the tar archive into a file or into the memory of PHP with a variable, then sending this content with an HTTP Request. With this plugin you can achieve this behavior without doing the first step:: @@ -34,5 +33,3 @@ With this plugin you can achieve this behavior without doing the first step:: $response = $pluginClient->sendRequest($request); In this case the tar output is directly streamed to the server without using memory on the PHP side. - -.. _RFC 2145: https://www.ietf.org/rfc/rfc2145.txt diff --git a/plugins/cookie.rst b/plugins/cookie.rst index 51ad87d..69ae613 100644 --- a/plugins/cookie.rst +++ b/plugins/cookie.rst @@ -1,8 +1,8 @@ Cookie Plugin ============= -Cookie plugins allow you to sore cookies information in a `CookieJar` and reuses them on consequent requests according -to `RFC 6265`_ specification:: +The ``CookiePlugin`` allow you to store cookies in a ``CookieJar`` and reuse them on consequent requests according +to :rfc:`6265#section-4` specification:: use Http\Discovery\HttpClientDiscovery; use Http\Message\CookieJar; @@ -15,5 +15,3 @@ to `RFC 6265`_ specification:: HttpClientDiscovery::find(), [$cookiePlugin] ); - -.. _RFC 6265: https://tools.ietf.org/html/rfc6265 diff --git a/plugins/decoder.rst b/plugins/decoder.rst index bb65e40..9de0a2f 100644 --- a/plugins/decoder.rst +++ b/plugins/decoder.rst @@ -1,8 +1,8 @@ Decoder Plugin ============== -Decoder Plugin decodes the body of the response with filters coming from the `Transfer-Encoding` or `Content-Encoding` -headers:: +The ``DecoderPlugin`` decodes the body of the response with filters coming from the ``Transfer-Encoding`` +or ``Content-Encoding`` headers:: use Http\Discovery\HttpClientDiscovery; use Http\Client\Plugin\PluginClient; @@ -15,20 +15,17 @@ headers:: [$decoderPlugin] ); -Actually it can decodes 4 different filters: +The plugin can handle the following encodings: - * chunked: Decode a stream with a chunked encoding (no size in the `Content-Length` header of the response) - * compress: Decode a stream encoded with the compress filter according to `RFC 1950`_ - * Deflate: Decode a stream encoded with the inflate filter according to `RFC 1951`_ - * gzip: Decode a stream encoded with the gzip filter according to `RFC 1952`_ + * ``chunked``: Decode a stream with a ``chunked`` encoding (no size in the ``Content-Length`` header of the response) + * ``compress``: Decode a stream encoded with the ``compress`` encoding according to :rfc:`1950` + * ``deflate``: Decode a stream encoded with the ``inflate`` encoding according to :rfc:`1951` + * ``gzip``: Decode a stream encoded with the ``gzip`` encoding according to :rfc:`1952` -You can also use the decoder plugin to only decodes the `Transfer-Encoding` header and not the `Content-Encoding` one -by setting the first parameter of the constructor to false:: +You can also use the decoder plugin to decode only the ``Transfer-Encoding`` header and not the ``Content-Encoding`` one +by setting the ``use_content_encoding`` configuration option to false:: - $decoderPlugin = new DecoderPlugin(false); + $decoderPlugin = new DecoderPlugin(['use_content_encoding' => false]); -This is useful when you want to get the encoded response body, or acting as a proxy. - -.. _RFC 1950: https://tools.ietf.org/html/rfc1950 -.. _RFC 1951: https://tools.ietf.org/html/rfc1951 -.. _RFC 1952: https://tools.ietf.org/html/rfc1952 +Not decoding content is useful when you don't want to get the encoded response body, or acting as a proxy but sill +be able to decode message from the ``Transfer-Encoding`` header value. diff --git a/plugins/error.rst b/plugins/error.rst index d60a7f6..e900c53 100644 --- a/plugins/error.rst +++ b/plugins/error.rst @@ -1,13 +1,13 @@ Error Plugin ============ -Error plugin will transform response with specific status code into exception: +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\Plugin\Exception\ClientErrorException``; + * 500-599 status code are transformed into ``Http\Client\Plugin\Exception\ServerErrorException`` -Both of this exceptions extends the `Http\Client\Exception\HttpException` exception class, so you can fetch the request -and the response coming from this exception:: +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; diff --git a/plugins/history.rst b/plugins/history.rst index 953cb7d..a0e8831 100644 --- a/plugins/history.rst +++ b/plugins/history.rst @@ -1,8 +1,7 @@ History Plugin ============== -History plugin use a `Http\Client\Plugin\Journal` to collect successful or failed calls of an Http Client. This is -mainly used for debugging like in the Symfony Bundle to get information in the debug toolbar with a DataCollector:: +The ``HistoryPlugin`` notifies a Http\Client\Plugin\Journal of all successful and failed calls:: use Http\Discovery\HttpClientDiscovery; use Http\Client\Plugin\PluginClient; @@ -15,3 +14,9 @@ mainly used for debugging like in the Symfony Bundle to get information in the d [$historyPlugin] ); + +As an example, HttplugBundle uses this plugin to collect responses or exceptions associated with +requests for the debug toolbar + +This plugin only collect data after resolution. For logging purposes it's best to use the `LoggerPlugin` which logs +as soon as possible. diff --git a/plugins/logger.rst b/plugins/logger.rst index 108f5ff..6d8be69 100644 --- a/plugins/logger.rst +++ b/plugins/logger.rst @@ -1,4 +1,26 @@ Logger Plugin ============= -TODO +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 Monolog\Logger; + + $loggerPlugin = new LoggerPlugin(new Logger('http')); + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [$loggerPlugin] + ); + +By default it uses ``Http\Message\Formatter\SimpleFormatter`` to format the request or the response into a string. +You can use any formatter implementing the ``Http\Message\Formatter`` interface:: + + $formatter = new \My\Formatter\Implemenation(); + + $loggerPlugin = new LoggerPlugin(new Logger('http'), $formatter); + +.. _PSR3: http://www.php-fig.org/psr/psr-3/