diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index 463d83f..0ca45f6 100644 --- a/.github/workflows/spellcheck.yml +++ b/.github/workflows/spellcheck.yml @@ -15,7 +15,7 @@ jobs: python-version: 3.7 - name: Install dependencies run: | - sudo apt update && sudo apt install -y enchant + sudo apt update && sudo apt install -y enchant-2 python -m pip install --upgrade setuptools python -m pip install --upgrade pyenchant sphinx-rtd-theme sphinxcontrib-spelling - name: Check spelling diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 530f402..2bc7396 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,5 +1,10 @@ version: 2 +build: + os: ubuntu-22.04 + tools: + python: "3.11" + sphinx: configuration: conf.py @@ -8,6 +13,5 @@ formats: - pdf python: - version: "3.7" install: - requirements: requirements.txt diff --git a/clients/artax-adapter.rst b/clients/artax-adapter.rst index b7962c5..3a48cc4 100644 --- a/clients/artax-adapter.rst +++ b/clients/artax-adapter.rst @@ -13,10 +13,6 @@ not yet included in your project), run: $ composer require php-http/artax-adapter -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - Usage ----- @@ -28,16 +24,12 @@ Begin by creating a Artax adapter:: $adapter = new ArtaxAdapter(new DefaultClient(), new GuzzleMessageFactory()); -Or if you installed the :doc:`discovery ` layer:: +Or relying on :doc:`discovery `:: use Http\Adapter\Artax\Client as ArtaxAdapter; $adapter = new ArtaxAdapter(); -.. warning:: - - The message factory parameter is mandatory if the discovery layer is not installed. - -.. include:: includes/further-reading-sync.inc +.. include:: includes/further-reading-async.inc .. _Artax HTTP client: https://github.com/amphp/artax diff --git a/clients/buzz-adapter.rst b/clients/buzz-adapter.rst index 8912c38..79bc4e8 100644 --- a/clients/buzz-adapter.rst +++ b/clients/buzz-adapter.rst @@ -1,7 +1,9 @@ -Buzz Adapter -============ +Buzz Adapter (deprecated) +========================= -An HTTPlug adapter for the `Buzz HTTP client`_. +This adapter only implements the PHP-HTTP synchronous interface. This interface +has been superseded by PSR-18, which the `Buzz HTTP client`_ implements +directly. Installation ------------ @@ -13,10 +15,6 @@ not yet included in your project), run: $ composer require php-http/buzz-adapter -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - Usage ----- @@ -44,16 +42,12 @@ Then create the adapter:: $adapter = new BuzzAdapter($browser, new GuzzleMessageFactory()); -Or if you installed the :doc:`discovery ` layer:: +Or relying on :doc:`discovery `:: use Http\Adapter\Buzz\Client as BuzzAdapter; $adapter = new BuzzAdapter($browser); -.. warning:: - - The message factory parameter is mandatory if the discovery layer is not installed. - Be Aware -------- diff --git a/clients/cakephp-adapter.rst b/clients/cakephp-adapter.rst index 027bd1d..8c0742e 100644 --- a/clients/cakephp-adapter.rst +++ b/clients/cakephp-adapter.rst @@ -13,10 +13,6 @@ not yet included in your project), run: $ composer require php-http/cakephp-adapter -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - Usage ----- @@ -33,9 +29,8 @@ like:: Then create the adapter:: use Http\Adapter\Cake\Client as CakeAdapter; - use Http\Message\MessageFactory\GuzzleMessageFactory; - $adapter = new CakeAdapter($cakeClient, new GuzzleMessageFactory()); + $adapter = new CakeAdapter($cakeClient); .. note:: @@ -53,6 +48,6 @@ Or if you installed the :doc:`discovery ` layer:: The message factory parameter is mandatory if the discovery layer is not installed. -.. include:: includes/further-reading-sync.inc +.. include:: includes/further-reading-async.inc .. _CakePHP HTTP client: https://book.cakephp.org/3.0/en/core-libraries/httpclient.html diff --git a/clients/curl-client.rst b/clients/curl-client.rst index eb445f2..22822eb 100644 --- a/clients/curl-client.rst +++ b/clients/curl-client.rst @@ -12,16 +12,11 @@ To install the cURL client, run: $ composer require php-http/curl-client -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - Usage ----- -The cURL client needs a :ref:`message factory ` and a -:ref:`stream factory ` in order to to work. You can either specify the factory -explicitly:: +The cURL client needs a PSR-17 message factory and stream factory to work. +You can either specify the factory explicitly:: use Http\Client\Curl\Client; use Http\Message\MessageFactory\DiactorosMessageFactory; @@ -29,13 +24,14 @@ explicitly:: $client = new Client(new DiactorosMessageFactory(), new DiactorosStreamFactory()); -Or you can use :doc:`../discovery`:: +Or you can omit the parameters and let the client use :doc:`../discovery` to +determine a suitable factory:: use Http\Client\Curl\Client; use Http\Discovery\MessageFactoryDiscovery; use Http\Discovery\StreamFactoryDiscovery; - $client = new Client(MessageFactoryDiscovery::find(), StreamFactoryDiscovery::find()); + $client = new Client(); Configuring Client ------------------ @@ -49,7 +45,7 @@ You can use `cURL options `_ to configure Client:: $options = [ CURLOPT_CONNECTTIMEOUT => 10, // The number of seconds to wait while trying to connect. ]; - $client = new Client(MessageFactoryDiscovery::find(), StreamFactoryDiscovery::find(), $options); + $client = new Client(null, null, $options); The following options can not be changed in the set up. Most of them are to be provided with the request instead: @@ -65,4 +61,4 @@ request instead: * CURLOPT_URL * CURLOPT_USERPWD -.. include:: includes/further-reading-sync.inc +.. include:: includes/further-reading-async.inc diff --git a/clients/guzzle5-adapter.rst b/clients/guzzle5-adapter.rst index b0bb481..0ebff38 100644 --- a/clients/guzzle5-adapter.rst +++ b/clients/guzzle5-adapter.rst @@ -1,8 +1,14 @@ -Guzzle5 Adapter -=============== +Guzzle5 Adapter (deprecated) +============================ An HTTPlug adapter for the `Guzzle 5 HTTP client`_. +This adapter only implements the PHP-HTTP synchronous interface. This interface +has been superseded by PSR-18. + +Guzzle 5 is very old and `not maintained anymore`_. We recommend to upgrade to +Guzzle version 7. + Installation ------------ @@ -13,10 +19,6 @@ not yet included in your project), run: $ composer require php-http/guzzle5-adapter -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - Usage ----- @@ -50,3 +52,4 @@ Or if you installed the :doc:`discovery ` layer:: .. include:: includes/further-reading-sync.inc .. _Guzzle 5 HTTP client: http://docs.guzzlephp.org/en/5.3/ +.. _not maintained anymore: https://github.com/guzzle/guzzle#version-guidance diff --git a/clients/guzzle7-adapter.rst b/clients/guzzle7-adapter.rst index dfa7f79..faa133a 100644 --- a/clients/guzzle7-adapter.rst +++ b/clients/guzzle7-adapter.rst @@ -2,8 +2,9 @@ Guzzle 7 Adapter ================ An HTTPlug adapter for the `Guzzle 7 HTTP client`_. Guzzle 7 supports PSR-18 -out of the box. This adapter makes sense if you want to use HTTPlug async interface or to use -Guzzle 7 with a library that did not upgrade to PSR-18 yet and depends on ``php-http/client-implementation``. +out of the box. This adapter makes sense if you want to use HTTPlug async +interface or to use Guzzle 7 with a library that did not upgrade to PSR-18 yet +and depends on ``php-http/client-implementation``. Installation ------------ diff --git a/clients/includes/install-discovery.inc b/clients/includes/install-discovery.inc deleted file mode 100644 index 68c431d..0000000 --- a/clients/includes/install-discovery.inc +++ /dev/null @@ -1,6 +0,0 @@ -Alternatively you can install the :doc:`discovery ` layer -to be able to automatically find installed resources, like factories: - -.. code-block:: bash - - $ composer require php-http/discovery diff --git a/clients/includes/install-message-factory.inc b/clients/includes/install-message-factory.inc deleted file mode 100644 index 2ca6116..0000000 --- a/clients/includes/install-message-factory.inc +++ /dev/null @@ -1,20 +0,0 @@ -This client does not come with a PSR-7 implementation out of the box, so you have -to install one as well (for example `Guzzle PSR-7`_): - -.. code-block:: bash - - $ composer require guzzlehttp/psr7 - -In order to provide full interoperability, message implementations are -accessed through :ref:`factories `. Message factories for -`Laminas Diactoros`_ (and its abandoned predecessor `Zend Diactoros`_), `Guzzle PSR-7`_ and `Slim Framework`_ are available in the -:doc:`message ` component: - -.. code-block:: bash - - $ composer require php-http/message - -.. _Guzzle PSR-7: https://github.com/guzzle/psr7 -.. _Laminas Diactoros: https://github.com/laminas/laminas-diactoros -.. _Slim PSR-7: https://github.com/slimphp/Slim-Psr7 -.. _Zend Diactoros: https://github.com/zendframework/zend-diactoros diff --git a/clients/mock-client.rst b/clients/mock-client.rst index 5f7b927..9ad6e41 100644 --- a/clients/mock-client.rst +++ b/clients/mock-client.rst @@ -1,7 +1,6 @@ Mock Client =========== - The mock client is a special type of client. It is a test double that does not send the requests that you pass to it, but collects them instead. You can then retrieve those request objects and make assertions about them. Additionally, you diff --git a/clients/react-adapter.rst b/clients/react-adapter.rst index 8e96e84..62d56a8 100644 --- a/clients/react-adapter.rst +++ b/clients/react-adapter.rst @@ -13,10 +13,6 @@ dependency. $ composer require php-http/react-adapter -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - Usage ----- diff --git a/clients/socket-client.rst b/clients/socket-client.rst index 4b1c0c4..a90e7e7 100644 --- a/clients/socket-client.rst +++ b/clients/socket-client.rst @@ -1,9 +1,12 @@ -Socket Client -============= +Socket Client (deprecated) +========================== The socket client uses the stream extension from PHP, which is integrated into the core. +This client only implements the PHP-HTTP synchronous interface, which has been +superseded by PSR-18. Use one of the PSR-18 clients instead. + Features -------- @@ -21,7 +24,23 @@ To install the Socket client, run: $ composer require php-http/socket-client -.. include:: includes/install-message-factory.inc +This client does not come with a PSR-7 implementation out of the box, so you have +to install one as well (for example `Guzzle PSR-7`_): + +.. code-block:: bash + + $ composer require guzzlehttp/psr7 + +In order to provide full interoperability, message implementations are accessed +through :ref:`factories `. Message factories for +`Laminas Diactoros`_ (and its abandoned predecessor `Zend Diactoros`_), +`Guzzle PSR-7`_ and `Slim PSR-7`_ are available in the +:doc:`message ` component: + +.. code-block:: bash + + $ composer require php-http/message + Usage ----- @@ -49,8 +68,8 @@ The available options are: :write_buffer_size: When sending the request we need to buffer the body, this option specify the size of this buffer, default is 8192, if you are sending big file with your client it may be interesting to have a bigger value in order to increase performance. -As an example someone may want to pass a client certificate when using the ssl, a valid configuration for this -use case would be:: +As an example someone may want to pass a client certificate when using the ssl, +a valid configuration for this use case would be:: use Http\Client\Socket\Client; @@ -65,9 +84,11 @@ use case would be:: .. warning:: - This client assumes that the request is compliant with HTTP 2.0, 1.1 or 1.0 standard. So a request without a ``Host`` header, or - with a body but without a ``Content-Length`` will certainly fail. - To make sure all requests will be sent out correctly, we recommend to use the ``PluginClient`` with the following plugins: + This client assumes that the request is compliant with HTTP 2.0, 1.1 or 1.0 + standard. So a request without a ``Host`` header, or with a body but + without a ``Content-Length`` will certainly fail. To make sure all requests + will be sent out correctly, we recommend to use the ``PluginClient`` with + the following plugins: * ``ContentLengthPlugin`` sets the correct ``Content-Length`` header, or decorate the stream to use chunked encoding * ``DecoderPlugin`` decodes encoding coming from the response (chunked, gzip, deflate and compress) @@ -75,3 +96,8 @@ use case would be:: :doc:`Read more on plugins ` .. include:: includes/further-reading-sync.inc + +.. _Guzzle PSR-7: https://github.com/guzzle/psr7 +.. _Laminas Diactoros: https://github.com/laminas/laminas-diactoros +.. _Slim PSR-7: https://github.com/slimphp/Slim-Psr7 +.. _Zend Diactoros: https://github.com/zendframework/zend-diactoros diff --git a/clients/symfony-client.rst b/clients/symfony-client.rst index 91a8d98..c490b45 100644 --- a/clients/symfony-client.rst +++ b/clients/symfony-client.rst @@ -12,15 +12,15 @@ To install the Symfony client, run: $ composer require symfony/http-client -This client does not come with a PSR-7 implementation out of the box, so you have -to install one as well. `Nyholm PSR-7`_ is supported natively: +This client does not come with a PSR-7 implementation out of the box. If you do +not require one, `discovery <../discovery>` will install `Nyholm PSR-7`_. If +you do not allow the composer plugin of the ``php-http/discovery`` component, +you need to install a PSR-7 implementation manually: .. code-block:: bash $ composer require nyholm/psr7 -.. include:: includes/install-discovery.inc - Usage ----- .. code-block:: php diff --git a/clients/zend-adapter.rst b/clients/zend-adapter.rst index 322f105..01e12a8 100644 --- a/clients/zend-adapter.rst +++ b/clients/zend-adapter.rst @@ -1,8 +1,15 @@ -Zend Adapter -============ +Zend Adapter (deprecated) +========================= An HTTPlug adapter for the Zend HTTP client. +Zend framework meanwhile has been renamed to Laminas, and the client is no +longer maintained. + +This adapter only implements the PHP-HTTP synchronous interface. This interface +has been superseded by PSR-18, which the `Laminas Diactoros`_ implements +directly. + Installation ------------ @@ -13,11 +20,4 @@ not yet included in your project), run: $ composer require php-http/zend-adapter -.. include:: includes/install-message-factory.inc - -.. include:: includes/install-discovery.inc - -Usage ------ - -To be written... +.. _Laminas Diactoros: https://docs.laminas.dev/laminas-diactoros/ diff --git a/components/promise.rst b/components/promise.rst index 584140b..a68bc81 100644 --- a/components/promise.rst +++ b/components/promise.rst @@ -82,7 +82,7 @@ executed if the request results in an error:: ); The failure callback can also return a ``Promise``. This can be useful to implement a retry -mechanism, as follows: +mechanism, as follows:: use Http\Discovery\HttpAsyncClientDiscovery; use Http\Discovery\Psr17FactoryDiscovery; @@ -103,7 +103,7 @@ mechanism, as follows: // try another execution return $client->sendAsyncRequest($request); }; - + $promise = $client->sendAsyncRequest($request); for ($i=0; $i < $retries; $i++) { $promise = $promise->then($success, $failure); diff --git a/conf.py b/conf.py index 8498f1b..98d2ade 100644 --- a/conf.py +++ b/conf.py @@ -80,7 +80,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: diff --git a/discovery.rst b/discovery.rst index 6875b44..3a79fe6 100644 --- a/discovery.rst +++ b/discovery.rst @@ -30,23 +30,26 @@ implementations but only on the standard. The library should only require the PSR standards. To run tests, you might still need an implementation. We recommend to -explicitly require that, but only for dev. To build a library that needs to -send HTTP requests, you could do: +explicitly require that, but only for development. To build a library that +needs to send HTTP requests, you could do: .. code-block:: bash + $ composer require --dev symfony/http-client $ composer require --dev nyholm/psr7 Then, you can disable the Composer plugin provided by ``php-http/discovery`` -because you just installed the dev dependencies you need for testing: +because you just installed the ``dev`` dependencies you need for testing: .. code-block:: bash + $ composer config allow-plugins.php-http/discovery false Finally, you need to require ``php-http/discovery`` and the generic implementations that your library is going to need: .. code-block:: bash + $ composer require php-http/discovery:^1.17 $ composer require psr/http-client-implementation:* $ composer require psr/http-factory-implementation:* @@ -132,6 +135,7 @@ to prefer. You can specify the implementation for one of the standards: .. code-block:: bash + $ composer config extra.discovery.psr/http-factory-implementation GuzzleHttp\Psr7\HttpFactory This will update your ``composer.json`` file to add the following configuration: @@ -158,6 +162,7 @@ Don't forget to run composer install to apply the changes, and ensure that the composer plugin is enabled: .. code-block:: bash + $ composer config allow-plugins.php-http/discovery true $ composer install @@ -338,7 +343,7 @@ Internally, this class relies on the concrete PSR-17 factories that are installe and can use discovery to find implementations if you do not specify them in the constructor. ``Psr17Factory`` provides two additional methods that allow creating -server requests or URI objects from the PHP super-globals:: +server requests or URI objects from the PHP superglobals:: $serverRequest = $factory->createServerRequestFromGlobals(); $uri = $factory->createUriFromGlobals(); @@ -438,14 +443,14 @@ to the Discovery. Let's take a look:: use MyCustomService; use Http\Mock\Client as MockClient; - use Http\Discovery\HttpClientDiscovery; + use Http\Discovery\Psr18ClientDiscovery; use Http\Discovery\Strategy\MockClientStrategy; class MyCustomServiceTest extends TestCase { public function setUp() { - HttpClientDiscovery::prependStrategy(MockClientStrategy::class); + Psr18ClientDiscovery::prependStrategy(MockClientStrategy::class); $this->service = new MyCustomService; } diff --git a/integrations/symfony-bundle.rst b/integrations/symfony-bundle.rst index 2ab0a86..d7d5ae2 100644 --- a/integrations/symfony-bundle.rst +++ b/integrations/symfony-bundle.rst @@ -84,7 +84,7 @@ Usage .. code-block:: php - $request = $this->container->get('httplug.message_factory')->createRequest('GET', 'http://example.com'); + $request = $this->container->get('httplug.psr17_request_factory')->createRequest('GET', 'http://example.com'); $response = $this->container->get('httplug.client.acme')->sendRequest($request); Autowiring @@ -92,7 +92,7 @@ Autowiring The first configured client is considered the "default" client. The default clients are available for `autowiring`_: The PSR-18 ``Psr\Http\Client\ClientInterface`` -(or the deprecated ``Http\Client\HttpClient``) and the ``Http\Client\HttpAsyncClient``. +and the ``Http\Client\HttpAsyncClient``. Autowiring can be convenient to build your application. However, if you configured several different clients and need to be sure that @@ -110,12 +110,13 @@ When using this bundle with Symfony 5.3 or newer, you can use the Symfony .. code-block:: php + use Psr\Http\Client\ClientInterface; use Symfony\Component\DependencyInjection\Attribute as DI; final class MyService { public function __construct( - #[DI\Target('acme')] HttpClient $client + #[DI\Target('acme')] ClientInterface $client ) {} } @@ -175,8 +176,8 @@ also disable the profiling by configuration. You can configure the bundle to show debug information for clients found with discovery. You may also force a specific client to be found when a third party library is using discovery. The configuration below makes sure the client with -service id ``httplug.client.my_guzzle5`` is returned when calling -``HttpClientDiscovery::find()`` . It does also make sure to show debug info for +service id ``httplug.client.my_guzzle7`` is returned when calling +``Psr18ClientDiscovery::find()`` . It does also make sure to show debug info for asynchronous clients. .. note:: @@ -187,10 +188,10 @@ asynchronous clients. httplug: clients: - my_guzzle5: - factory: 'httplug.factory.guzzle5' + my_guzzle7: + factory: 'httplug.factory.guzzle7' discovery: - client: 'httplug.client.my_guzzle5' + client: 'httplug.client.my_guzzle7' async_client: 'auto' For normal clients, the auto discovery debug info is enabled by default. For @@ -211,10 +212,11 @@ example shows how you configure factory classes using Guzzle: httplug: classes: - client: Http\Adapter\Guzzle6\Client - message_factory: Http\Message\MessageFactory\GuzzleMessageFactory - uri_factory: Http\Message\UriFactory\GuzzleUriFactory - stream_factory: Http\Message\StreamFactory\GuzzleStreamFactory + client: Http\Adapter\Guzzle7\Client + psr17_request_factory: GuzzleHttp\Psr7\HttpFactory + psr17_response_factory: GuzzleHttp\Psr7\HttpFactory + psr17_uri_factory: GuzzleHttp\Psr7\HttpFactory + psr17_stream_factory: GuzzleHttp\Psr7\HttpFactory Configure Clients ````````````````` @@ -227,8 +229,8 @@ services. httplug: clients: - my_guzzle5: - factory: 'httplug.factory.guzzle5' + my_guzzle7: + factory: 'httplug.factory.guzzle7' config: # These options are given to Guzzle without validation. defaults: @@ -244,10 +246,10 @@ services. .. code-block:: php - $httpClient = $this->container->get('httplug.client.my_guzzle5'); + $httpClient = $this->container->get('httplug.client.my_guzzle7'); $httpClient = $this->container->get('httplug.client.acme'); - // will be the same as ``httplug.client.my_guzzle5`` + // will be the same as ``httplug.client.my_guzzle7`` $httpClient = $this->container->get('httplug.client'); The bundle has client factory services that you can use to build your client. @@ -257,11 +259,11 @@ services are: * ``httplug.factory.curl`` * ``httplug.factory.buzz`` -* ``httplug.factory.guzzle5`` * ``httplug.factory.guzzle6`` * ``httplug.factory.guzzle7`` * ``httplug.factory.react`` * ``httplug.factory.socket`` +* ``httplug.factory.symfony`` * ``httplug.factory.mock`` (Install ``php-http/mock-client`` first) .. note:: @@ -405,7 +407,7 @@ Authentication -------------- You can configure a client with authentication. Valid authentication types are -``basic``, ``bearer``, ``service``, ``wsse`` and ``query_param``. See more examples at the +``basic``, ``bearer``, ``service``, ``wsse``, ``query_param`` and ``header``. See more examples at the :doc:`full configuration `. .. code-block:: yaml @@ -479,11 +481,13 @@ List of Services +-------------------------------------+-------------------------------------------------------------------------+ | Service id | Description | +=====================================+=========================================================================+ -| ``httplug.message_factory`` | Service* that provides the `Http\Message\MessageFactory` | +| ``httplug.psr17_request_factory`` | Service* that provides the `Psr\Http\Message\RequestFactoryInterface` | +-------------------------------------+-------------------------------------------------------------------------+ -| ``httplug.uri_factory`` | Service* that provides the `Http\Message\UriFactory` | +| ``httplug.psr17_response_factory`` | Service* that provides the `Psr\Http\Message\ResponseFactoryInterface` | +-------------------------------------+-------------------------------------------------------------------------+ -| ``httplug.stream_factory`` | Service* that provides the `Http\Message\StreamFactory` | +| ``httplug.psr17_uri_factory`` | Service* that provides the `Psr\Http\Message\UriFactoryInterface` | ++-------------------------------------+-------------------------------------------------------------------------+ +| ``httplug.psr17_stream_factory`` | Service* that provides the `Psr\Http\Message\StreamFactoryInterface` | +-------------------------------------+-------------------------------------------------------------------------+ | ``httplug.client.[name]`` | There is one service per named client. | +-------------------------------------+-------------------------------------------------------------------------+ @@ -562,7 +566,7 @@ To mock a response in your tests, do: $client->getContainer()->get('httplug.clients.my_awesome_backend.client')->addResponse($response); If you do not specify the factory in your configuration, you can also directly -overwrite the httplug services: +overwrite the HTTPlug services: .. code-block:: yaml diff --git a/integrations/symfony-full-configuration.rst b/integrations/symfony-full-configuration.rst index e66b5cd..3ab012f 100644 --- a/integrations/symfony-full-configuration.rst +++ b/integrations/symfony-full-configuration.rst @@ -22,15 +22,17 @@ This page shows an example of all configuration values provided by the bundle. # this does NOT change autowiring, which will always go to the "default" client main_alias: client: httplug.client.default - message_factory: httplug.message_factory.default - uri_factory: httplug.uri_factory.default - stream_factory: httplug.stream_factory.default + psr17_request_factory: httplug.psr17_request_factory.default + psr17_response_factory: httplug.psr17_response_factory.default + psr17_uri_factory: httplug.psr17_uri_factory.default + psr17_stream_factory: httplug.psr17_stream_factory.default classes: # uses discovery if not specified client: ~ - message_factory: ~ - uri_factory: ~ - stream_factory: ~ + psr17_request_factory: ~ + psr17_response_factory: ~ + psr17_uri_factory: ~ + psr17_stream_factory: ~ plugins: # Global plugin configuration. When configured here, plugins need to be explicitly added to clients by service name. authentication: @@ -50,6 +52,10 @@ This page shows an example of all configuration values provided by the bundle. type: 'query_param' params: access_token: '9zh987g86fg87gh978hg9g79' + my_header: + type: 'header' + header_name: 'ApiKey' + header_value: '9zh987g86fg87gh978hg9g79' my_service: type: 'service' service: 'my_authentication_service' diff --git a/message.rst b/message.rst index 841d3c8..f369f90 100644 --- a/message.rst +++ b/message.rst @@ -11,6 +11,4 @@ This package contains various PSR-7 tools which might be useful in an HTTP workf * Authentication method implementations * Various Stream encoding tools * Message decorators -* Message factory implementations for Guzzle PSR-7, Diactoros and Slim Framework. -* Stream and URI factory implementations for Guzzle PSR-7 and Diactoros * Cookie implementation diff --git a/message/message-factory.rst b/message/message-factory.rst index c9099a1..9d7b93d 100644 --- a/message/message-factory.rst +++ b/message/message-factory.rst @@ -1,28 +1,26 @@ .. _message-factory: .. _stream-factory: -HTTP Factories -============== +HTTP Factories (deprecated) +=========================== **Factory interfaces for PSR-7 HTTP objects.** +This package has been superseded by `PSR-17`_. Our HTTP-PHP factories have been +retired and the repository archived. The PHP-HTTP libraries switched to use the +PSR-17 factories. Please migrate your code to the PSR-17 factories too. + Rationale --------- -While it should be possible to use every PSR-7 aware HTTP client with any -request, URI and stream implementation, instantiating objects explicitly would -still tie the code to a specific implementation. If each reusable library is -tied to a specific message implementation, an application could end up -installing several message implementations. The factories move instantiation -out of the library code, further decoupling libraries from implementation. - -The FIG was pretty straightforward by NOT putting any construction logic into PSR-7. -The ``MessageFactory`` aims to provide an easy way to construct messages. +At the time of building this, PSR-17 did not yet exist. Read the documentation +of `PSR-17`_ to learn why a standard for factories is useful. Factories --------- -The `php-http/message-factory` package defines interfaces for PSR-7 factories including: +The `php-http/message-factory` package defines interfaces for PSR-7 factories +including: - ``RequestFactory`` - ``ResponseFactory`` @@ -30,7 +28,9 @@ The `php-http/message-factory` package defines interfaces for PSR-7 factories in - ``StreamFactory`` - ``UriFactory`` -Implementations of the interfaces above for `Laminas Diactoros`_ (and its abandoned predecessor `Zend Diactoros`_), `Guzzle PSR-7`_ and the `Slim Framework`_ can be found in ``php-http/message``. +Implementations of the interfaces above for `Laminas Diactoros`_ (and its +abandoned predecessor `Zend Diactoros`_), `Guzzle PSR-7`_ and the +`Slim PSR-7`_ can be found in ``php-http/message``. Usage ----- @@ -127,15 +127,9 @@ automatically find an available factory in the client:: type hint, instead of the ``MessageFactory``. And vice versa if you create responses only. -Server Side Factories ---------------------- - -It would make sense to also provide factories for the server side constructs -``ServerRequestInterface`` and ``UploadedFileInterface``. We did not get around -to do that yet. Contributions are welcome if you want to define the -``ServerRequestFactory`` and ``UploadedFileFactory``. - +.. _PSR-17: https://www.php-fig.org/psr/psr-17/ .. _Guzzle PSR-7: https://github.com/guzzle/psr7 .. _Laminas Diactoros: https://github.com/laminas/laminas-diactoros .. _Slim PSR-7: https://github.com/slimphp/Slim-Psr7 .. _Zend Diactoros: https://github.com/zendframework/zend-diactoros +.. _Slim Framework: https://github.com/slimphp/Slim diff --git a/plugins/cache.rst b/plugins/cache.rst index 5eb611a..06d13c7 100644 --- a/plugins/cache.rst +++ b/plugins/cache.rst @@ -14,7 +14,7 @@ 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:: +`PSR-17`_ StreamFactoryInterface and a `PSR-6`_ implementation:: use Http\Discovery\HttpClientDiscovery; use Http\Client\Common\PluginClient; @@ -22,7 +22,7 @@ control headers from the server as specified in :rfc:`7234`. It needs a /** @var \Psr\Cache\CacheItemPoolInterface $pool */ $pool = ... - /** @var \Http\Message\StreamFactory $streamFactory */ + /** @var \Psr\Http\Message\StreamFactoryInterface $streamFactory */ $streamFactory = ... $options = []; @@ -180,3 +180,4 @@ It does store responses with cookies or a ``Set-Cookie`` header. Be careful with the order of your plugins. .. _PSR-6: http://www.php-fig.org/psr/psr-6/ +.. _PSR-17: http://www.php-fig.org/psr/psr-17/ diff --git a/plugins/logger.rst b/plugins/logger.rst index f755343..278e439 100644 --- a/plugins/logger.rst +++ b/plugins/logger.rst @@ -26,10 +26,10 @@ compliant logger:: [$loggerPlugin] ); -The log level for exceptions is `error`, the request and responses without exceptions are logged at level `info`. -Request and response/errors can be correlated by looking at the `uid` of the log context. -If you don't want to normally log requests, you can set the logger to normally only log `error` but use the -Fingerscrossed logger of monolog to also log the request in case an exception is encountered. +The log level for exceptions is ``error``, the request and responses without exceptions are logged at level ``info``. +Request and response/errors can be correlated by looking at the ``uid`` of the log context. +If you don't want to normally log requests, you can set the logger to normally only log ``error`` but use the +``Fingerscrossed`` logger of Monolog to also log the request in case an exception is encountered. 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:: diff --git a/plugins/redirect.rst b/plugins/redirect.rst index 0dfe8d4..965a953 100644 --- a/plugins/redirect.rst +++ b/plugins/redirect.rst @@ -32,7 +32,7 @@ Initiate the redirect plugin as follows:: .. note:: Depending on the status code, redirecting should change POST/PUT requests to GET requests. This - plugin implements this behaviour - except if you set the ``strict`` option to true, as explained + plugin implements this behavior - except if you set the ``strict`` option to true, as explained below. It removes the request body if the method changes, see ``stream_factory`` below. To understand the exact semantics of which HTTP status changes the method and which not, have a diff --git a/spelling_word_list.txt b/spelling_word_list.txt index a209c06..0383be3 100644 --- a/spelling_word_list.txt +++ b/spelling_word_list.txt @@ -27,6 +27,7 @@ plugin plugins matchers matcher +Monolog multipart natively param @@ -35,11 +36,13 @@ profiler PHP phpdoc rebase +redirections Semver Seekable seekable sexualized sublicense +superglobals sync toolbar typehint