-
Notifications
You must be signed in to change notification settings - Fork 56
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
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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'); | ||
|
||
// 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/ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 👍 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Let’s do that in subsequent PRs for the adapters. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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 😉).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Cool.