Skip to content

adjust documentation to PSR-17 and PSR-18#310

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dbu merged 1 commit into from
Jan 6, 2024
Merged

adjust documentation to PSR-17 and PSR-18 #310

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 2 additions & 10 deletions clients/artax-adapter.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
-----

Expand All@@ -28,16 +24,12 @@ Begin by creating a Artax adapter::

$adapter = new ArtaxAdapter(new DefaultClient(), new GuzzleMessageFactory());

Or if you installed the :doc:`discovery </discovery>` layer::
Or relying on :doc:`discovery </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
18 changes: 6 additions & 12 deletions clients/buzz-adapter.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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
------------
Expand All@@ -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
-----

Expand DownExpand Up@@ -44,16 +42,12 @@ Then create the adapter::

$adapter = new BuzzAdapter($browser, new GuzzleMessageFactory());

Or if you installed the :doc:`discovery </discovery>` layer::
Or relying on :doc:`discovery </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
--------

Expand Down
9 changes: 2 additions & 7 deletions clients/cakephp-adapter.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
-----

Expand All@@ -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::

Expand All@@ -53,6 +48,6 @@ Or if you installed the :doc:`discovery </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
18 changes: 7 additions & 11 deletions clients/curl-client.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -12,30 +12,26 @@ 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 <message-factory>` and a
:ref:`stream factory <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;
use Http\Message\StreamFactory\DiactorosStreamFactory;

$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
------------------
Expand All@@ -49,7 +45,7 @@ You can use `cURL options <http://php.net/curl_setopt>`_ 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:
Expand All@@ -65,4 +61,4 @@ request instead:
* CURLOPT_URL
* CURLOPT_USERPWD

.. include:: includes/further-reading-sync.inc
.. include:: includes/further-reading-async.inc
15 changes: 9 additions & 6 deletions clients/guzzle5-adapter.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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
------------

Expand All@@ -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
-----

Expand DownExpand Up@@ -50,3 +52,4 @@ Or if you installed the :doc:`discovery </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
5 changes: 3 additions & 2 deletions clients/guzzle7-adapter.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
------------
Expand Down
6 changes: 0 additions & 6 deletions clients/includes/install-discovery.inc
View file
Open in desktop

This file was deleted.

21 changes: 0 additions & 21 deletions clients/includes/install-message-factory.inc
View file
Open in desktop

This file was deleted.

1 change: 0 additions & 1 deletion clients/mock-client.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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
Expand Down
4 changes: 0 additions & 4 deletions clients/react-adapter.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -13,10 +13,6 @@ dependency.

$ composer require php-http/react-adapter

.. include:: includes/install-message-factory.inc

.. include:: includes/install-discovery.inc

Usage
-----

Expand Down
42 changes: 34 additions & 8 deletions clients/socket-client.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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.

@dbudbuMay 15, 2023

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@joelwurtz@Nyholm i think you 2 mostly worked on the socket client. as it does not implement async and is quite inactive, i think we should deprecate it in favor of using PSR-18 clients.

@ro0NLro0NLMay 30, 2023

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the package should be updated, or marked abondonded. Not sure what we're waiting for 🤷

@dbudbuMay 31, 2023

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i wanted to give some time to react for the authors of the package who are part of the php-http group.

but no reaction is also a kind of statement on priorities. i can't promise that i can get to it very soon however, as i have a holidays coming up.

@dbudbuJan 6, 2024

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

php-http/socket-client#70


Features
--------

Expand All@@ -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-factory>`. Message factories for
`Laminas Diactoros`_ (and its abandoned predecessor `Zend Diactoros`_),
`Guzzle PSR-7`_ and `Slim PSR-7`_ are available in the
:doc:`message </message>` component:

.. code-block:: bash

$ composer require php-http/message


Usage
-----
Expand DownExpand Up@@ -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;

Expand All@@ -65,13 +84,20 @@ 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)

:doc:`Read more on plugins </plugins/introduction>`

.. 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
8 changes: 4 additions & 4 deletions clients/symfony-client.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
20 changes: 10 additions & 10 deletions clients/zend-adapter.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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
------------

Expand All@@ -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/
2 changes: 0 additions & 2 deletions message.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Loading