mirror of
https://github.com/guzzle/guzzle.git
synced 2025-02-24 01:53:58 +01:00
c6cf0c6da2
- HTTP method based signatures like get(), put(), etc.. accept a URL, and array of request options. createRequest() is similar but also requires a method string. - Renamed request events to 'before', 'complete', 'error', and 'headers. - Renamed the associated event classes. - Adding more docs.
344 lines
11 KiB
ReStructuredText
344 lines
11 KiB
ReStructuredText
=======
|
|
Clients
|
|
=======
|
|
|
|
Clients are used to create requests, create transactions, send requests
|
|
through an HTTP adapter, and return a response. You can add default request
|
|
options to a client that are applied to every request (e.g., default headers,
|
|
default query string parameters, etc), and you can add event listeners and
|
|
subscribers to every request created by a client.
|
|
|
|
Creating a client
|
|
=================
|
|
|
|
The constructor of a client accepts an associative array of configuration
|
|
options.
|
|
|
|
- **base_url**: Configures a base URL for the client so that requests created
|
|
using a relative URL are combined with the ``base_url`` of the client
|
|
according to section `5.2 of RFC 3986 <http://tools.ietf.org/html/rfc3986#section-5.2>`_.
|
|
|
|
.. code-block:: php
|
|
|
|
// Create a client with a base URL
|
|
$client = new GuzzleHttp\Client(['base_url' => 'https://github.com']);
|
|
// Send a request to https://github.com/notifications
|
|
$response = $client->get('/notifications');
|
|
|
|
`Absolute URLs <http://tools.ietf.org/html/rfc3986#section-4.3>`_ sent
|
|
through a client will not use the base URL of the client.
|
|
|
|
- **adapter**: Configures the HTTP adapter
|
|
(``GuzzleHttp\Adapter\AdapterInterface``) used to transfer the HTTP requests
|
|
of a client. Guzzle will, by default, utilize a stacked adapter that chooses
|
|
the best adapter to use based on the provided request options and based on
|
|
the extensions available in the environment. If cURL is installed, it will be
|
|
used as the default adapter. However, if a request has the ``stream`` request
|
|
option, the PHP stream wrapper adapter will be used (assuming
|
|
``allow_url_fopen`` is enabled in your PHP environment).
|
|
|
|
- **parallel_adapter**: Just like the ``adapter`` option, you can choose to
|
|
specify an adapter that is used to send requests in parallel
|
|
(``GuzzleHttp\Adapter\ParallelAdapterInterface``). Guzzle will by default
|
|
use cURL to send requests in parallel, but if cURL is not available it will
|
|
use the PHP stream wrapper and simply send requests serially.
|
|
|
|
- **message_factory**: Specifies the factory used to create HTTP requests and
|
|
responses (``GuzzleHttp\Message\MessageFactoryInterface``).
|
|
|
|
- **defaults**: Specified an associative array of request options that are
|
|
applied to every request created by the client. This allows you to, for
|
|
example, specifies an array of headers that are sent with every request.
|
|
|
|
Here's an example of creating a client with various options, including using
|
|
a mock adapter that just returns the result of a callable function and a
|
|
base URL that is a URI template with parameters.
|
|
|
|
.. code-block:: php
|
|
|
|
use GuzzleHttp\Client;
|
|
|
|
$client = new Client([
|
|
['https://api.twitter.com/{version}', ['version' => 'v1.1']],
|
|
'defaults' => [
|
|
'headers' => ['Foo' => 'Bar'],
|
|
'query' => ['testing' => '123'],
|
|
'auth' => ['username', 'password'],
|
|
'proxy' => 'tcp://localhost:80'
|
|
]
|
|
]);
|
|
|
|
Sending Requests
|
|
================
|
|
|
|
Requests can be created using various methods of a client. You can create
|
|
**and** send requests using one of the following methods:
|
|
|
|
- ``GuzzleHttp\Client::get``: Sends a GET request.
|
|
- ``GuzzleHttp\Client::head``: Sends a HEAD request
|
|
- ``GuzzleHttp\Client::post``: Sends a POST request
|
|
- ``GuzzleHttp\Client::put``: Sends a PUT request
|
|
- ``GuzzleHttp\Client::delete``: Sends a DELETE request
|
|
- ``GuzzleHttp\Client::options``: Sends an OPTIONS request
|
|
|
|
Each of the above methods accepts a URL and associative array of request
|
|
options.
|
|
|
|
.. code-block:: php
|
|
|
|
$client = new GuzzleHttp\Client();
|
|
|
|
$client->put('http://httpbin.org', [
|
|
'headers' => ['X-Foo' => 'Bar'],
|
|
'body' => 'this is the body!',
|
|
'save_to' => '/path/to/local/file',
|
|
'allow_redirects' => false,
|
|
'timeout' => 5
|
|
]);
|
|
|
|
Creating Requests
|
|
-----------------
|
|
|
|
You can also create a request without sending it. This is useful for building
|
|
up requests over time or sending requests in parallel.
|
|
|
|
.. code-block:: php
|
|
|
|
$request = $client->createRequest('GET', 'http://httpbin.org', [
|
|
'headers' => ['X-Foo' => 'Bar']
|
|
]);
|
|
|
|
// Modify the request as needed
|
|
$request->setHeader('Baz', 'bar');
|
|
|
|
After creating a request, you can send it with the client's ``send()`` method.
|
|
|
|
.. code-block:: php
|
|
|
|
$response = $client->send($request);
|
|
|
|
Sending Requests in Parallel
|
|
----------------------------
|
|
|
|
You can send requests in parallel using a client object's ``sendAll()`` method.
|
|
The ``sendAll()`` method accepts an array or ``\Iterator`` that contains
|
|
``GuzzleHttp\Message\RequestInterface`` objects. In addition to providing the
|
|
requests to send, you can also specify an associative array of options that
|
|
will affect the transfer.
|
|
|
|
.. code-block:: php
|
|
|
|
$requests = [
|
|
$client->createRequest('GET', 'http://httpbin.org'),
|
|
$client->createRequest('DELETE', 'http://httpbin.org/delete'),
|
|
$client->createRequest('PUT', 'http://httpbin.org/put', ['body' => 'test'])
|
|
];
|
|
|
|
$client->sendAll($requests);
|
|
|
|
You can work with the responses for each request as the are received using the
|
|
events emitted from a request. Here we are using the ``complete`` event and
|
|
printing out each request URL and response body.
|
|
|
|
.. code-block:: php
|
|
|
|
use GuzzleHttp\Event\CompleteEvent;
|
|
|
|
$client->sendAll($requests, [
|
|
'complete' => function (CompleteEvent $event) {
|
|
echo 'Completed request to ' . $event->getRequest()->getUrl() . "\n";
|
|
echo 'Response: ' . $event->getResponse()->getBody() . "\n\n";
|
|
}
|
|
]);
|
|
|
|
You can also handle errors using the event system. Here we are adding each
|
|
failed response to an array that we can use to process errors later.
|
|
|
|
.. code-block:: php
|
|
|
|
use GuzzleHttp\Event\ErrorEvent;
|
|
|
|
$errors = [];
|
|
$client->sendAll($requests, [
|
|
'error' => function (ErrorEvent $event) use (&$errors) {
|
|
echo 'Request failed: ' . $event->getRequest()->getUrl() . "\n";
|
|
echo $event->getException();
|
|
$errors[] = $event;
|
|
}
|
|
]);
|
|
|
|
foreach ($errors as $error) {
|
|
// Do something with the errors
|
|
}
|
|
|
|
Request Options
|
|
===============
|
|
|
|
headers
|
|
-------
|
|
|
|
Associative array of headers to add to the request.
|
|
|
|
body
|
|
----
|
|
|
|
string/resource/array/StreamInterface that represents the body to send over the
|
|
wire.
|
|
|
|
query
|
|
-----
|
|
|
|
Associative array of query string values to add to the request.
|
|
|
|
auth
|
|
----
|
|
|
|
Array of HTTP authentication parameters to use with the request. The array must
|
|
contain the username in index [0], the password in index [2], and can optionally
|
|
contain the authentication type in index [3]. The authentication types are:
|
|
"Basic", "Digest", "NTLM", "Any" (defaults to "Basic"). The selected
|
|
authentication type must be supported by the adapter used by a client.
|
|
|
|
cookies
|
|
-------
|
|
|
|
Pass an associative array containing cookies to send in the request and start a
|
|
new cookie session, set to a ``Guzzle\Http\Subscriber\CookieJar\CookieJarInterface``
|
|
object to us an existing cookie jar, or set to ``true`` to use a shared cookie
|
|
session associated with the client.
|
|
|
|
allow_redirects
|
|
---------------
|
|
|
|
Set to false to disable redirects. Set to true to enable normal redirects with
|
|
a maximum number of 5 redirects. Pass an associative array containing the 'max'
|
|
key to specify the maximum number of redirects and optionally provide a 'strict'
|
|
key value to specify whether or not to use strict RFC compliant redirects
|
|
(meaning redirect POST requests with POST requests vs. doing what most browsers
|
|
do which is redirect POST requests with GET requests).
|
|
|
|
save_to
|
|
-------
|
|
|
|
Specify where the body of a response will be saved. Pass a string to specify
|
|
the path to a file that will store the contents of the response body. Pass a
|
|
resource returned from fopen to write the response to a PHP stream. Pass a
|
|
``Guzzle\Stream\StreamInterface`` object to stream the response body to an open
|
|
Guzzle stream.
|
|
|
|
events
|
|
------
|
|
|
|
Associative array mapping event names to a callable or an associative array
|
|
containing the 'fn' key that maps to a callable, an optional 'priority' key
|
|
used to specify the event priority, and an optional 'once' key used to specify
|
|
if the event should remove itself the first time it is triggered.
|
|
|
|
subscribers
|
|
-----------
|
|
|
|
Array of event subscribers to add to the request. Each value in the array must
|
|
be an instance of ``Guzzle\Common\EventSubscriberInterface``.
|
|
|
|
exceptions
|
|
----------
|
|
|
|
Set to false to disable throwing exceptions on an HTTP protocol error (e.g.
|
|
404, 500, etc). Exceptions are thrown by default when HTTP protocol errors are
|
|
encountered.
|
|
|
|
timeout
|
|
-------
|
|
|
|
Float describing the timeout of the request in seconds. Use 0 to wait
|
|
indefinitely.
|
|
|
|
connect_timeout
|
|
---------------
|
|
|
|
Float describing the number of seconds to wait while trying to connect. Use 0 to wait
|
|
indefinitely. This setting must be supported by the adapter used to send a request.
|
|
|
|
verify
|
|
------
|
|
|
|
Set to true to enable SSL cert validation (the default), false to disable
|
|
validation, or supply the path to a CA bundle to enable verification using a
|
|
custom certificate.
|
|
|
|
cert
|
|
----
|
|
|
|
Set to a string to specify the path to a file containing a PEM formatted
|
|
certificate. If a password is required, then set an array containing the path
|
|
to the PEM file followed by the the password required for the certificate.
|
|
|
|
ssl_key
|
|
-------
|
|
|
|
Specify the path to a file containing a private SSL key in PEM format. If a
|
|
password is required, then set an array containing the path to the SSL key
|
|
followed by the password required for the certificate.
|
|
|
|
proxy
|
|
-----
|
|
|
|
Specify an HTTP proxy (e.g. ``"http://username:password@192.168.16.1:10"``)
|
|
|
|
debug
|
|
-----
|
|
|
|
Set to true or a PHP fopen stream resource to enable debug output with the
|
|
adapter used to send a request. For example, when using cURL to transfer
|
|
requests, cURL's verbose output will be emitted. When using the PHP stream
|
|
wrapper, stream wrapper notifications will be emitted. If set to true, the
|
|
output is written to PHP's STDOUT.
|
|
|
|
stream
|
|
------
|
|
|
|
Set to true to stream a response rather than download it all up-front. (Note:
|
|
This option might not be supported by every HTTP adapter, but the interface of
|
|
the response object remains the same.)
|
|
|
|
expect
|
|
------
|
|
|
|
Set to true to enable the "Expect: 100-Continue" header for a request that send
|
|
a body. Set to false to disable "Expect: 100-Continue". Set to a number so that
|
|
the size of the payload must be greater than the number in order to send the
|
|
Expect header. Setting to a number will send the Expect header for all requests
|
|
in which the size of the payload cannot be determined or where the body is not
|
|
rewindable.
|
|
|
|
options
|
|
-------
|
|
|
|
Associative array of options that are forwarded to a request's configuration
|
|
collection. These values are used as configuration options that can be consumed
|
|
by plugins and adapters.
|
|
|
|
Event Subscribers
|
|
=================
|
|
|
|
Requests emit lifecycle events when they are transferred. A client object has a
|
|
``GuzzleHttp\Common\EventEmitter`` object that can be used to add event
|
|
*listeners* and event *subscribers* to all requests created by the client.
|
|
|
|
.. code-block:: php
|
|
|
|
use GuzzleHttp\Client;
|
|
use GuzzleHttp\Event\BeforeEvent;
|
|
|
|
$client = new Client();
|
|
|
|
// Add a listener that will echo out requests before they are sent
|
|
$client->getEmitter()->on('before', function (BeforeEvent $e) {
|
|
echo 'About to send request: ' . $e->getRequest();
|
|
});
|
|
|
|
$client->get('http://httpbin.org/get');
|
|
// Outputs the request as a string because of the event
|
|
|
|
See :doc:`events` for more information on the event system used in Guzzle.
|