Skip to content

Add Guzzle 6 adapter docs #67

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.

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
merged 1 commit into from
Jan 5, 2016
Merged
Changes from all commits
Commits
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
56 changes: 54 additions & 2 deletions clients/guzzle6-adapter.rst
Original file line number Diff line number Diff line change
@@ -1,2 +1,54 @@
Guzzle6 Adapter
===============
Guzzle 6 Adapter
================

An HTTPlug adapter for the `Guzzle 6 HTTP client`_.

To install the Guzzle adapter, which will also install Guzzle itself (if it was
not yet included in your project), run:

.. code-block:: bash

$ composer require php-http/guzzle6-adapter

Then begin by creating a Guzzle client, passing any configuration parameters you
like::

use GuzzleHttp\Client as GuzzleClient;

$config = [
// Config params
];
$guzzle = new GuzzleClientClient($config);

Then create the adapter::

use Http\Adapter\Guzzle6\Client as GuzzleAdapter;

$adapter = new GuzzleAdapter($guzzle);

And use it to send synchronous requests::

use GuzzleHttp\Psr7\Request;

$request = new Request('GET', 'http://httpbin.org');
Copy link
Contributor

Choose a reason for hiding this comment

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

should we promote this or use the message factory?

Copy link
Member

Choose a reason for hiding this comment

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

I think it rather matters in a library, then an application. I would keep both and state that message factory should be used in a library.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I wanted to keep things as easy as possible for new users.

And because guzzle6-adapter requires guzzle which requires guzzle/psr7, I thought it made sense to just use Guzzle’s PSR-7 Request object here.

Added a reference to the message factory doc chapter.

Copy link
Member

Choose a reason for hiding this comment

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

Makes sense. Wouldn't it end up too much duplicated documentation if we have this in each client documentation?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

That’s a good argument, too. Let’s try to minimize duplication where possible.

Copy link
Member

Choose a reason for hiding this comment

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

I think only the configuration can be different for clients. So every other usage should be the same hence the interface.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

That’s true, but it makes sense to have complete example per adapter. Later we can extract this duplicated bit and make it an include (long live Sphinx 😉).

Copy link
Member

Choose a reason for hiding this comment

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

Cool.


// Returns a Psr\Http\Message\ResponseInterface
$response = $adapter->sendRequest($request);

Or send asynchronous ones::

use GuzzleHttp\Psr7\Request;

$request = new Request('GET', 'http://httpbin.org');

// Returns a Http\Promise\Promise
$promise = $adapter->sendAsyncRequest(request);

Further reading
---------------

* Read more about :doc:`promises </components/promise>`.
* Learn how you can decouple your code from any PSR-7 implementation (such as
Guzzle’s above) by using a :ref:`message factory <message-factory>`.

.. _Guzzle 6 HTTP client: http://docs.guzzlephp.org/
Copy link
Contributor Author

Choose a reason for hiding this comment

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

I prefer this bottom section over documentation sprinkled with note and warning boxes, as they can be very distracting.

Copy link
Contributor

Choose a reason for hiding this comment

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

👍
we might want to move this into a partial that we include right away, as this page will be used as template for other adapter / client documentations.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Let’s do that in subsequent PRs for the adapters.