scratch – Blame information for rev 87

Subversion Repositories:
Rev:
Rev Author Line No. Line
87 office 1 =======
2 Clients
3 =======
4  
5 Clients are used to create requests, create transactions, send requests
6 through an HTTP adapter, and return a response. You can add default request
7 options to a client that are applied to every request (e.g., default headers,
8 default query string parameters, etc.), and you can add event listeners and
9 subscribers to every request created by a client.
10  
11 Creating a client
12 =================
13  
14 The constructor of a client accepts an associative array of configuration
15 options.
16  
17 base_url
18 Configures a base URL for the client so that requests created
19 using a relative URL are combined with the ``base_url`` of the client
20 according to section `5.2 of RFC 3986 <http://tools.ietf.org/html/rfc3986#section-5.2>`_.
21  
22 .. code-block:: php
23  
24 // Create a client with a base URL
25 $client = new GuzzleHttp\Client(['base_url' => 'https://github.com']);
26 // Send a request to https://github.com/notifications
27 $response = $client->get('/notifications');
28  
29 `Absolute URLs <http://tools.ietf.org/html/rfc3986#section-4.3>`_ sent
30 through a client will not use the base URL of the client.
31  
32 adapter
33 Configures the HTTP adapter (``GuzzleHttp\Adapter\AdapterInterface``) used
34 to transfer the HTTP requests of a client. Guzzle will, by default, utilize
35 a stacked adapter that chooses the best adapter to use based on the provided
36 request options and based on the extensions available in the environment. If
37 cURL is installed, it will be used as the default adapter. However, if a
38 request has the ``stream`` request option, the PHP stream wrapper adapter
39 will be used (assuming ``allow_url_fopen`` is enabled in your PHP
40 environment).
41  
42 parallel_adapter
43 Just like the ``adapter`` option, you can choose to specify an adapter
44 that is used to send requests in parallel
45 (``GuzzleHttp\Adapter\ParallelAdapterInterface``). Guzzle will by default
46 use cURL to send requests in parallel, but if cURL is not available it will
47 use the PHP stream wrapper and simply send requests serially.
48  
49 message_factory
50 Specifies the factory used to create HTTP requests and responses
51 (``GuzzleHttp\Message\MessageFactoryInterface``).
52  
53 defaults
54 Associative array of :ref:`request-options` that are applied to every
55 request created by the client. This allows you to specify things like
56 default headers (e.g., User-Agent), default query string parameters, SSL
57 configurations, and any other supported request options.
58  
59 emitter
60 Specifies an event emitter (``GuzzleHttp\Event\EmitterInterface``) instance
61 to be used by the client to emit request events. This option is useful if
62 you need to inject an emitter with listeners/subscribers already attached.
63  
64 Here's an example of creating a client with various options, including using
65 a mock adapter that just returns the result of a callable function and a
66 base URL that is a URI template with parameters.
67  
68 .. code-block:: php
69  
70 use GuzzleHttp\Client;
71  
72 $client = new Client([
73 'base_url' => ['https://api.twitter.com/{version}/', ['version' => 'v1.1']],
74 'defaults' => [
75 'headers' => ['Foo' => 'Bar'],
76 'query' => ['testing' => '123'],
77 'auth' => ['username', 'password'],
78 'proxy' => 'tcp://localhost:80'
79 ]
80 ]);
81  
82 Sending Requests
83 ================
84  
85 Requests can be created using various methods of a client. You can create
86 **and** send requests using one of the following methods:
87  
88 - ``GuzzleHttp\Client::get``: Sends a GET request.
89 - ``GuzzleHttp\Client::head``: Sends a HEAD request
90 - ``GuzzleHttp\Client::post``: Sends a POST request
91 - ``GuzzleHttp\Client::put``: Sends a PUT request
92 - ``GuzzleHttp\Client::delete``: Sends a DELETE request
93 - ``GuzzleHttp\Client::options``: Sends an OPTIONS request
94  
95 Each of the above methods accepts a URL as the first argument and an optional
96 associative array of :ref:`request-options` as the second argument.
97  
98 .. code-block:: php
99  
100 $client = new GuzzleHttp\Client();
101  
102 $client->put('http://httpbin.org', [
103 'headers' => ['X-Foo' => 'Bar'],
104 'body' => 'this is the body!',
105 'save_to' => '/path/to/local/file',
106 'allow_redirects' => false,
107 'timeout' => 5
108 ]);
109  
110 Error Handling
111 --------------
112  
113 When a recoverable error is encountered while calling the ``send()`` method of
114 a client, a ``GuzzleHttp\Exception\RequestException`` is thrown.
115  
116 .. code-block:: php
117  
118 use GuzzleHttp\Client;
119 use GuzzleHttp\Exception\RequestException;
120  
121 $client = new Client();
122  
123 try {
124 $client->get('http://httpbin.org');
125 } catch (RequestException $e) {
126 echo $e->getRequest() . "\n";
127 if ($e->hasResponse()) {
128 echo $e->getResponse() . "\n";
129 }
130 }
131  
132 ``GuzzleHttp\Exception\RequestException`` always contains a
133 ``GuzzleHttp\Message\RequestInterface`` object that can be accessed using the
134 exception's ``getRequest()`` method.
135  
136 A response might be present in the exception. In the event of a networking
137 error, no response will be received. You can check if a ``RequestException``
138 has a response using the ``hasResponse()`` method. If the exception has a
139 response, then you can access the associated
140 ``GuzzleHttp\Message\ResponseInterface`` using the ``getResponse()`` method of
141 the exception.
142  
143 HTTP Errors
144 ~~~~~~~~~~~
145  
146 If the ``exceptions`` request option is not set to ``false``, then exceptions
147 are thrown for HTTP protocol errors as well:
148 ``GuzzleHttp\Exception\ClientErrorResponseException`` for 4xx level HTTP
149 responses and ``GuzzleHttp\Exception\ServerException`` for 5xx level responses,
150 both of which extend from ``GuzzleHttp\Exception\BadResponseException``.
151  
152 Creating Requests
153 -----------------
154  
155 You can create a request without sending it. This is useful for building up
156 requests over time or sending requests in parallel.
157  
158 .. code-block:: php
159  
160 $request = $client->createRequest('GET', 'http://httpbin.org', [
161 'headers' => ['X-Foo' => 'Bar']
162 ]);
163  
164 // Modify the request as needed
165 $request->setHeader('Baz', 'bar');
166  
167 After creating a request, you can send it with the client's ``send()`` method.
168  
169 .. code-block:: php
170  
171 $response = $client->send($request);
172  
173 Sending Requests in Parallel
174 ============================
175  
176 You can send requests in parallel using a client object's ``sendAll()`` method.
177 The ``sendAll()`` method accepts an array or ``\Iterator`` that contains
178 ``GuzzleHttp\Message\RequestInterface`` objects. In addition to providing the
179 requests to send, you can also specify an associative array of options that
180 will affect the transfer.
181  
182 .. code-block:: php
183  
184 $requests = [
185 $client->createRequest('GET', 'http://httpbin.org'),
186 $client->createRequest('DELETE', 'http://httpbin.org/delete'),
187 $client->createRequest('PUT', 'http://httpbin.org/put', ['body' => 'test'])
188 ];
189  
190 $client->sendAll($requests);
191  
192 The ``sendAll()`` method accepts the following associative array of options:
193  
194 - **parallel**: Integer representing the maximum number of requests that are
195 allowed to be sent in parallel.
196 - **before**: Callable or array representing the event listeners to add to
197 each request's :ref:`before_event` event.
198 - **complete**: Callable or array representing the event listeners to add to
199 each request's :ref:`complete_event` event.
200 - **error**: Callable or array representing the event listeners to add to
201 each request's :ref:`error_event` event.
202  
203 The "before", "complete", and "error" event options accept a callable or an
204 array of associative arrays where each associative array contains a "fn" key
205 with a callable value, an optional "priority" key representing the event
206 priority (with a default value of 0), and an optional "once" key that can be
207 set to true so that the event listener will be removed from the request after
208 it is first triggered.
209  
210 .. code-block:: php
211  
212 use GuzzleHttp\Event\CompleteEvent;
213  
214 // Add a single event listener using a callable.
215 $client->sendAll($requests, [
216 'complete' => function (CompleteEvent $event) {
217 echo 'Completed request to ' . $event->getRequest()->getUrl() . "\n";
218 echo 'Response: ' . $event->getResponse()->getBody() . "\n\n";
219 }
220 ]);
221  
222 // The above is equivalent to the following, but the following structure
223 // allows you to add multiple event listeners to the same event name.
224 $client->sendAll($requests, [
225 'complete' => [
226 [
227 'fn' => function (CompleteEvent $event) { /* ... */ },
228 'priority' => 0, // Optional
229 'once' => false // Optional
230 ]
231 ]
232 ]);
233  
234 Asynchronous Response Handling
235 ------------------------------
236  
237 When sending requests in parallel, the request/response/error lifecycle must be
238 handled asynchronously. This means that you give the ``sendAll()`` method
239 multiple requests and handle the response or errors that is associated with the
240 request using event callbacks.
241  
242 .. code-block:: php
243  
244 use GuzzleHttp\Event\ErrorEvent;
245  
246 $client->sendAll($requests, [
247 'complete' => function (CompleteEvent $event) {
248 echo 'Completed request to ' . $event->getRequest()->getUrl() . "\n";
249 echo 'Response: ' . $event->getResponse()->getBody() . "\n\n";
250 // Do something with the completion of the request...
251 },
252 'error' => function (ErrorEvent $event) {
253 echo 'Request failed: ' . $event->getRequest()->getUrl() . "\n";
254 echo $event->getException();
255 // Do something to handle the error...
256 }
257 ]);
258  
259 The ``GuzzleHttp\Event\ErrorEvent`` event object is emitted when an error
260 occurs during a transfer. With this event, you have access to the request that
261 was sent, the response that was received (if one was received), access to
262 transfer statistics, and the ability to intercept the exception with a
263 different ``GuzzleHttp\Message\ResponseInterface`` object. See :doc:`events`
264 for more information.
265  
266 Handling Errors After Transferring
267 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
268  
269 It sometimes might be easier to handle all of the errors that occurred during a
270 transfer after all of the requests have been sent. Here we are adding each
271 failed request to an array that we can use to process errors later.
272  
273 .. code-block:: php
274  
275 use GuzzleHttp\Event\ErrorEvent;
276  
277 $errors = [];
278 $client->sendAll($requests, [
279 'error' => function (ErrorEvent $event) use (&$errors) {
280 $errors[] = $event;
281 }
282 ]);
283  
284 foreach ($errors as $error) {
285 // Handle the error...
286 }
287  
288 Throwing Errors Immediately
289 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
290  
291 It sometimes is useful to throw exceptions immediately when they occur. The
292 following example shows how to use an event listener to throw exceptions
293 immediately and prevent subsequent requests from being sent.
294  
295 .. code-block:: php
296  
297 use GuzzleHttp\Event\ErrorEvent;
298  
299 $client->sendAll($requests, [
300 'error' => function (ErrorEvent $event) {
301 $event->throwImmediately(true);
302 }
303 ]);
304  
305 Calling the ``ErrorEvent::throwImmediately()`` instructs the
306 ``ParallelAdapterInterface`` sending the request to stop sending subsequent
307 requests, clean up any opened resources, and throw the exception associated
308 with the event as soon as possible. If the error event was not sent by a
309 ``ParallelAdapterInterface``, then calling ``throwImmediately()`` has no
310 effect.
311  
312 .. note::
313  
314 Subsequent listeners of the "error" event can still intercept the error
315 event with a response if needed, which will, as per the standard behavior,
316 prevent the exception from being thrown.
317  
318 .. _batch-requests:
319  
320 Batching Requests
321 -----------------
322  
323 Sometimes you just want to send a few requests in parallel and then process
324 the results all at once after they've been sent. Guzzle provides a convenience
325 function ``GuzzleHttp\batch()`` that makes this very simple:
326  
327 .. code-block:: php
328  
329 $client = new GuzzleHttp\Client();
330  
331 $requests = [
332 $client->createRequest('GET', 'http://httpbin.org/get'),
333 $client->createRequest('HEAD', 'http://httpbin.org/get'),
334 $client->createRequest('PUT', 'http://httpbin.org/put'),
335 ];
336  
337 $results = GuzzleHttp\batch($client, $requests);
338  
339 // Results is an SplObjectStorage object where each request is a key
340 foreach ($requests as $request) {
341 echo $request->getUrl() . "\n";
342 // Get the result (either a ResponseInterface or RequestException)
343 $result = $results[$request];
344 if ($result instanceof ResponseInterface) {
345 // Interact with the response directly
346 echo $result->getStatusCode();
347 } else {
348 // Get the exception message
349 echo $result->getMessage();
350 }
351 }
352  
353 ``GuzzleHttp\batch()`` accepts an optional associative array of options in the
354 third argument that allows you to specify the 'before', 'complete' and 'error'
355 events as well as specify the maximum number of requests to send in parallel
356 using the 'parallel' option key. This options array is the exact same format as
357 the options array exposed in ``GuzzleHttp\ClientInterface::sendAll()``.
358  
359 .. _request-options:
360  
361 Request Options
362 ===============
363  
364 You can customize requests created by a client using **request options**.
365 Request options control various aspects of a request including, headers,
366 query string parameters, timeout settings, the body of a request, and much
367 more.
368  
369 All of the following examples use the following client:
370  
371 .. code-block:: php
372  
373 $client = new GuzzleHttp\Client(['base_url' => 'http://httpbin.org']);
374  
375 headers
376 -------
377  
378 :Summary: Associative array of headers to add to the request. Each key is the
379 name of a header, and each value is a string or array of strings
380 representing the header field values.
381 :Types: array
382 :Defaults: None
383  
384 .. code-block:: php
385  
386 // Set various headers on a request
387 $client->get('/get', [
388 'headers' => [
389 'User-Agent' => 'testing/1.0',
390 'Accept' => 'application/json',
391 'X-Foo' => ['Bar', 'Baz']
392 ]
393 ]);
394  
395 body
396 ----
397  
398 :Summary: The ``body`` option is used to control the body of an entity
399 enclosing request (e.g., PUT, POST, PATCH).
400 :Types:
401 - string
402 - ``fopen()`` resource
403 - ``GuzzleHttp\Stream\StreamInterface``
404 - ``GuzzleHttp\Post\PostBodyInterface``
405 :Default: None
406  
407 This setting can be set to any of the following types:
408  
409 - string
410  
411 .. code-block:: php
412  
413 // You can send requests that use a string as the message body.
414 $client->put('/put', ['body' => 'foo']);
415  
416 - resource returned from ``fopen()``
417  
418 .. code-block:: php
419  
420 // You can send requests that use a stream resource as the body.
421 $resource = fopen('http://httpbin.org', 'r');
422 $client->put('/put', ['body' => $resource]);
423  
424 - Array
425  
426 Use an array to send POST style requests that use a
427 ``GuzzleHttp\Post\PostBodyInterface`` object as the body.
428  
429 .. code-block:: php
430  
431 // You can send requests that use a POST body containing fields & files.
432 $client->post('/post', [
433 'body' => [
434 'field' => 'abc',
435 'other_field' => '123',
436 'file_name' => fopen('/path/to/file', 'r')
437 ]
438 ]);
439  
440 - ``GuzzleHttp\Stream\StreamInterface``
441  
442 .. code-block:: php
443  
444 // You can send requests that use a Guzzle stream object as the body
445 $stream = GuzzleHttp\Stream\Stream::factory('contents...');
446 $client->post('/post', ['body' => $stream]);
447  
448 json
449 ----
450  
451 :Summary: The ``json`` option is used to easily upload JSON encoded data as the
452 body of a request. A Content-Type header of ``application/json`` will be
453 added if no Content-Type header is already present on the message.
454 :Types:
455 Any PHP type that can be operated on by PHP's ``json_encode()`` function.
456 :Default: None
457  
458 .. code-block:: php
459  
460 $request = $client->createRequest('/put', ['json' => ['foo' => 'bar']]);
461 echo $request->getHeader('Content-Type');
462 // application/json
463 echo $request->getBody();
464 // {"foo":"bar"}
465  
466 .. note::
467  
468 This request option does not support customizing the Content-Type header
469 or any of the options from PHP's `json_encode() <http://www.php.net/manual/en/function.json-encode.php>`_
470 function. If you need to customize these settings, then you must pass the
471 JSON encoded data into the request yourself using the ``body`` request
472 option and you must specify the correct Content-Type header using the
473 ``headers`` request option.
474  
475 query
476 -----
477  
478 :Summary: Associative array of query string values to add to the request.
479 :Types:
480 - array
481 - ``GuzzleHttp\Query``
482 :Default: None
483  
484 .. code-block:: php
485  
486 // Send a GET request to /get?foo=bar
487 $client->get('/get', ['query' => ['foo' => 'bar']]);
488  
489 Query strings specified in the ``query`` option are combined with any query
490 string values that are parsed from the URL.
491  
492 .. code-block:: php
493  
494 // Send a GET request to /get?abc=123&foo=bar
495 $client->get('/get?abc=123', ['query' => ['foo' => 'bar']]);
496  
497 auth
498 ----
499  
500 :Summary: Pass an array of HTTP authentication parameters to use with the
501 request. The array must contain the username in index [0], the password in
502 index [1], and you can optionally provide a built-in authentication type in
503 index [2]. Pass ``null`` to disable authentication for a request.
504 :Types:
505 - array
506 - string
507 - null
508 :Default: None
509  
510 The built-in authentication types are as follows:
511  
512 basic
513 Use `basic HTTP authentication <http://www.ietf.org/rfc/rfc2069.txt>`_ in
514 the ``Authorization`` header (the default setting used if none is
515 specified).
516  
517 .. code-block:: php
518  
519 $client->get('/get', ['auth' => ['username', 'password']]);
520  
521 digest
522 Use `digest authentication <http://www.ietf.org/rfc/rfc2069.txt>`_ (must be
523 supported by the HTTP adapter).
524  
525 .. code-block:: php
526  
527 $client->get('/get', ['auth' => ['username', 'password', 'digest']]);
528  
529 *This is currently only supported when using the cURL adapter, but creating
530 a replacement that can be used with any HTTP adapter is planned.*
531  
532 .. important::
533  
534 The authentication type (whether it's provided as a string or as the third
535 option in an array) is always converted to a lowercase string. Take this
536 into account when implementing custom authentication types and when
537 implementing custom message factories.
538  
539 Custom Authentication Schemes
540 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
541  
542 You can also provide a string representing a custom authentication type name.
543 When using a custom authentication type string, you will need to implement
544 the authentication method in an event listener that checks the ``auth`` request
545 option of a request before it is sent. Authentication listeners that require
546 a request is not modified after they are signed should have a very low priority
547 to ensure that they are fired last or near last in the event chain.
548  
549 .. code-block:: php
550  
551 use GuzzleHttp\Event\BeforeEvent;
552 use GuzzleHttp\Event\RequestEvents;
553  
554 /**
555 * Custom authentication listener that handles the "foo" auth type.
556 *
557 * Listens to the "before" event of a request and only modifies the request
558 * when the "auth" config setting of the request is "foo".
559 */
560 class FooAuth implements GuzzleHttp\Event\SubscriberInterface
561 {
562 private $password;
563  
564 public function __construct($password)
565 {
566 $this->password = $password;
567 }
568  
569 public function getEvents()
570 {
571 return ['before' => ['sign', RequestEvents::SIGN_REQUEST]];
572 }
573  
574 public function sign(BeforeEvent $e)
575 {
576 if ($e->getRequest()->getConfig()['auth'] == 'foo') {
577 $e->getRequest()->setHeader('X-Foo', 'Foo ' . $this->password);
578 }
579 }
580 }
581  
582 $client->getEmitter()->attach(new FooAuth('password'));
583 $client->get('/', ['auth' => 'foo']);
584  
585 Adapter Specific Authentication Schemes
586 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
587  
588 If you need to use authentication methods provided by cURL (e.g., NTLM, GSS,
589 etc.), then you need to specify a curl adapter option in the ``options``
590 request option array. See :ref:`config-option` for more information.
591  
592 .. _cookies-option:
593  
594 cookies
595 -------
596  
597 :Summary: Specifies whether or not cookies are used in a request or what cookie
598 jar to use or what cookies to send.
599 :Types:
600 - bool
601 - array
602 - ``GuzzleHttp\Cookie\CookieJarInterface``
603 :Default: None
604  
605 Set to ``true`` to use a shared cookie session associated with the client.
606  
607 .. code-block:: php
608  
609 // Enable cookies using the shared cookie jar of the client.
610 $client->get('/get', ['cookies' => true]);
611  
612 Pass an associative array containing cookies to send in the request and start a
613 new cookie session.
614  
615 .. code-block:: php
616  
617 // Enable cookies and send specific cookies
618 $client->get('/get', ['cookies' => ['foo' => 'bar']]);
619  
620 Set to a ``GuzzleHttp\Cookie\CookieJarInterface`` object to use an existing
621 cookie jar.
622  
623 .. code-block:: php
624  
625 $jar = new GuzzleHttp\Cookie\CookieJar();
626 $client->get('/get', ['cookies' => $jar]);
627  
628 .. _allow_redirects-option:
629  
630 allow_redirects
631 ---------------
632  
633 :Summary: Describes the redirect behavior of a request
634 :Types:
635 - bool
636 - array
637 :Default: ``['max' => 5, 'strict' => false, 'referer' => true]``
638  
639 Set to ``false`` to disable redirects.
640  
641 .. code-block:: php
642  
643 $res = $client->get('/redirect/3', ['allow_redirects' => false]);
644 echo $res->getStatusCode();
645 // 302
646  
647 Set to ``true`` (the default setting) to enable normal redirects with a maximum
648 number of 5 redirects.
649  
650 .. code-block:: php
651  
652 $res = $client->get('/redirect/3');
653 echo $res->getStatusCode();
654 // 200
655  
656 Pass an associative array containing the 'max' key to specify the maximum
657 number of redirects, optionally provide a 'strict' key value to specify
658 whether or not to use strict RFC compliant redirects (meaning redirect POST
659 requests with POST requests vs. doing what most browsers do which is redirect
660 POST requests with GET requests), and optionally provide a 'referer' key to
661 specify whether or not the "Referer" header should be added when redirecting.
662  
663 .. code-block:: php
664  
665 $res = $client->get('/redirect/3', [
666 'allow_redirects' => [
667 'max' => 10,
668 'strict' => true,
669 'referer' => true
670 ]
671 ]);
672 echo $res->getStatusCode();
673 // 200
674  
675 decode_content
676 --------------
677  
678 :Summary: Specify whether or not ``Content-Encoding`` responses (gzip,
679 deflate, etc.) are automatically decoded.
680 :Types:
681 - string
682 - bool
683 :Default: ``true``
684  
685 This option can be used to control how content-encoded response bodies are
686 handled. By default, ``decode_content`` is set to true, meaning any gzipped
687 or deflated response will be decoded by Guzzle.
688  
689 When set to ``false``, the body of a response is never decoded, meaning the
690 bytes pass through the adapter unchanged.
691  
692 .. code-block:: php
693  
694 // Request gzipped data, but do not decode it while downloading
695 $client->get('/foo.js', [
696 'headers' => ['Accept-Encoding' => 'gzip'],
697 'decode_content' => false
698 ]);
699  
700 When set to a string, the bytes of a response are decoded and the string value
701 provided to the ``decode_content`` option is passed as the ``Accept-Encoding``
702 header of the request.
703  
704 .. code-block:: php
705  
706 // Pass "gzip" as the Accept-Encoding header.
707 $client->get('/foo.js', ['decode_content' => 'gzip']);
708  
709 .. _save_to-option:
710  
711 save_to
712 -------
713  
714 :Summary: Specify where the body of a response will be saved.
715 :Types:
716 - string
717 - ``fopen()`` resource
718 - ``GuzzleHttp\Stream\StreamInterface``
719 :Default: PHP temp stream
720  
721 Pass a string to specify the path to a file that will store the contents of the
722 response body:
723  
724 .. code-block:: php
725  
726 $client->get('/stream/20', ['save_to' => '/path/to/file']);
727  
728 Pass a resource returned from ``fopen()`` to write the response to a PHP stream:
729  
730 .. code-block:: php
731  
732 $resource = fopen('/path/to/file', 'w');
733 $client->get('/stream/20', ['save_to' => $resource]);
734  
735 Pass a ``GuzzleHttp\Stream\StreamInterface`` object to stream the response body
736 to an open Guzzle stream:
737  
738 .. code-block:: php
739  
740 $resource = fopen('/path/to/file', 'w');
741 $stream = GuzzleHttp\Stream\Stream::factory($resource);
742 $client->get('/stream/20', ['save_to' => $stream]);
743  
744 .. _events-option:
745  
746 events
747 ------
748  
749 :Summary: An associative array mapping event names to a callable. Or an
750 associative array containing the 'fn' key that maps to a callable, an
751 optional 'priority' key used to specify the event priority, and an optional
752 'once' key used to specify if the event should remove itself the first time
753 it is triggered.
754 :Types: array
755 :Default: None
756  
757 .. code-block:: php
758  
759 use GuzzleHttp\Event\BeforeEvent;
760 use GuzzleHttp\Event\HeadersEvent;
761 use GuzzleHttp\Event\CompleteEvent;
762 use GuzzleHttp\Event\ErrorEvent;
763  
764 $client->get('/', [
765 'events' => [
766 'before' => function (BeforeEvent $e) { echo 'Before'; },
767 'headers' => function (HeadersEvent $e) { echo 'Headers'; },
768 'complete' => function (CompleteEvent $e) { echo 'Complete'; },
769 'error' => function (ErrorEvent $e) { echo 'Error'; },
770 ]
771 ]);
772  
773 Here's an example of using the associative array format for control over the
774 priority and whether or not an event should be triggered more than once.
775  
776 .. code-block:: php
777  
778 $client->get('/', [
779 'events' => [
780 'before' => [
781 'fn' => function (BeforeEvent $e) { echo 'Before'; },
782 'priority' => 100,
783 'once' => true
784 ]
785 ]
786 ]);
787  
788 .. _subscribers-option:
789  
790 subscribers
791 -----------
792  
793 :Summary: Array of event subscribers to add to the request. Each value in the
794 array must be an instance of ``GuzzleHttp\Event\SubscriberInterface``.
795 :Types: array
796 :Default: None
797  
798 .. code-block:: php
799  
800 use GuzzleHttp\Subscriber\History;
801 use GuzzleHttp\Subscriber\Mock;
802 use GuzzleHttp\Message\Response;
803  
804 $history = new History();
805 $mock = new Mock([new Response(200)]);
806 $client->get('/', ['subscribers' => [$history, $mock]]);
807  
808 echo $history;
809 // Outputs the request and response history
810  
811 .. _exceptions-option:
812  
813 exceptions
814 ----------
815  
816 :Summary: Set to ``false`` to disable throwing exceptions on an HTTP protocol
817 errors (i.e., 4xx and 5xx responses). Exceptions are thrown by default when
818 HTTP protocol errors are encountered.
819 :Types: bool
820 :Default: ``true``
821  
822 .. code-block:: php
823  
824 $client->get('/status/500');
825 // Throws a GuzzleHttp\Exception\ServerException
826  
827 $res = $client->get('/status/500', ['exceptions' => false]);
828 echo $res->getStatusCode();
829 // 500
830  
831 .. _timeout-option:
832  
833 timeout
834 -------
835  
836 :Summary: Float describing the timeout of the request in seconds. Use ``0``
837 to wait indefinitely (the default behavior).
838 :Types: float
839 :Default: ``0``
840  
841 .. code-block:: php
842  
843 // Timeout if a server does not return a response in 3.14 seconds.
844 $client->get('/delay/5', ['timeout' => 3.14]);
845 // PHP Fatal error: Uncaught exception 'GuzzleHttp\Exception\RequestException'
846  
847 .. _connect_timeout-option:
848  
849 connect_timeout
850 ---------------
851  
852 :Summary: Float describing the number of seconds to wait while trying to connect
853 to a server. Use ``0`` to wait indefinitely (the default behavior).
854 :Types: float
855 :Default: ``0``
856  
857 .. code-block:: php
858  
859 // Timeout if the client fails to connect to the server in 3.14 seconds.
860 $client->get('/delay/5', ['connect_timeout' => 3.14]);
861  
862 .. note::
863  
864 This setting must be supported by the HTTP adapter used to send a request.
865 ``connect_timeout`` is currently only supported by the built-in cURL
866 adapter.
867  
868 .. _verify-option:
869  
870 verify
871 ------
872  
873 :Summary: Describes the SSL certificate verification behavior of a request.
874 Set to ``true`` to enable SSL certificate verification (the default). Set
875 to ``false`` to disable certificate verification (this is insecure!). Set
876 to a string to provide the path to a CA bundle to enable verification using
877 a custom certificate.
878 :Types:
879 - bool
880 - string
881 :Default: ``true``
882  
883 .. code-block:: php
884  
885 // Use a custom SSL certificate
886 $client->get('/', ['verify' => '/path/to/cert.pem']);
887  
888 // Disable validation
889 $client->get('/', ['verify' => false]);
890  
891 .. _cert-option:
892  
893 cert
894 ----
895  
896 :Summary: Set to a string to specify the path to a file containing a PEM
897 formatted client side certificate. If a password is required, then set to
898 an array containing the path to the PEM file in the first array element
899 followed by the password required for the certificate in the second array
900 element.
901 :Types:
902 - string
903 - array
904 :Default: None
905  
906 .. code-block:: php
907  
908 $client->get('/', ['cert' => ['/path/server.pem', 'password']]);
909  
910 .. _ssl_key-option:
911  
912 ssl_key
913 -------
914  
915 :Summary: Specify the path to a file containing a private SSL key in PEM
916 format. If a password is required, then set to an array containing the path
917 to the SSL key in the first array element followed by the password required
918 for the certificate in the second element.
919 :Types:
920 - string
921 - array
922 :Default: None
923  
924 .. note::
925  
926 ``ssl_key`` is implemented by HTTP adapters. This is currently only
927 supported by the cURL adapter, but might be supported by other third-part
928 adapters.
929  
930 .. _proxy-option:
931  
932 proxy
933 -----
934  
935 :Summary: Pass a string to specify an HTTP proxy, or an array to specify
936 different proxies for different protocols.
937 :Types:
938 - string
939 - array
940 :Default: None
941  
942 Pass a string to specify a proxy for all protocols.
943  
944 .. code-block:: php
945  
946 $client->get('/', ['proxy' => 'tcp://localhost:8125']);
947  
948 Pass an associative array to specify HTTP proxies for specific URI schemes
949 (i.e., "http", "https").
950  
951 .. code-block:: php
952  
953 $client->get('/', [
954 'proxy' => [
955 'http' => 'tcp://localhost:8125', // Use this proxy with "http"
956 'https' => 'tcp://localhost:9124' // Use this proxy with "https"
957 ]
958 ]);
959  
960 .. note::
961  
962 You can provide proxy URLs that contain a scheme, username, and password.
963 For example, ``"http://username:password@192.168.16.1:10"``.
964  
965 .. _debug-option:
966  
967 debug
968 -----
969  
970 :Summary: Set to ``true`` or set to a PHP stream returned by ``fopen()`` to
971 enable debug output with the adapter used to send a request. For example,
972 when using cURL to transfer requests, cURL's verbose of ``CURLOPT_VERBOSE``
973 will be emitted. When using the PHP stream wrapper, stream wrapper
974 notifications will be emitted. If set to true, the output is written to
975 PHP's STDOUT. If a PHP stream is provided, output is written to the stream.
976 :Types:
977 - bool
978 - ``fopen()`` resource
979 :Default: None
980  
981 .. code-block:: php
982  
983 $client->get('/get', ['debug' => true]);
984  
985 Running the above example would output something like the following:
986  
987 ::
988  
989 * About to connect() to httpbin.org port 80 (#0)
990 * Trying 107.21.213.98... * Connected to httpbin.org (107.21.213.98) port 80 (#0)
991 > GET /get HTTP/1.1
992 Host: httpbin.org
993 User-Agent: Guzzle/4.0 curl/7.21.4 PHP/5.5.7
994  
995 < HTTP/1.1 200 OK
996 < Access-Control-Allow-Origin: *
997 < Content-Type: application/json
998 < Date: Sun, 16 Feb 2014 06:50:09 GMT
999 < Server: gunicorn/0.17.4
1000 < Content-Length: 335
1001 < Connection: keep-alive
1002 <
1003 * Connection #0 to host httpbin.org left intact
1004  
1005 .. _stream-option:
1006  
1007 stream
1008 ------
1009  
1010 :Summary: Set to ``true`` to stream a response rather than download it all
1011 up-front.
1012 :Types: bool
1013 :Default: ``false``
1014  
1015 .. code-block:: php
1016  
1017 $response = $client->get('/stream/20', ['stream' => true]);
1018 // Read bytes off of the stream until the end of the stream is reached
1019 $body = $response->getBody();
1020 while (!$body->eof()) {
1021 echo $body->read(1024);
1022 }
1023  
1024 .. note::
1025  
1026 Streaming response support must be implemented by the HTTP adapter used by
1027 a client. This option might not be supported by every HTTP adapter, but the
1028 interface of the response object remains the same regardless of whether or
1029 not it is supported by the adapter.
1030  
1031 .. _expect-option:
1032  
1033 expect
1034 ------
1035  
1036 :Summary: Controls the behavior of the "Expect: 100-Continue" header.
1037 :Types:
1038 - bool
1039 - integer
1040 :Default: ``1048576``
1041  
1042 Set to ``true`` to enable the "Expect: 100-Continue" header for all requests
1043 that sends a body. Set to ``false`` to disable the "Expect: 100-Continue"
1044 header for all requests. Set to a number so that the size of the payload must
1045 be greater than the number in order to send the Expect header. Setting to a
1046 number will send the Expect header for all requests in which the size of the
1047 payload cannot be determined or where the body is not rewindable.
1048  
1049 By default, Guzzle will add the "Expect: 100-Continue" header when the size of
1050 the body of a request is greater than 1 MB and a request is using HTTP/1.1.
1051  
1052 .. note::
1053  
1054 This option only takes effect when using HTTP/1.1. The HTTP/1.0 and
1055 HTTP/2.0 protocols do not support the "Expect: 100-Continue" header.
1056 Support for handling the "Expect: 100-Continue" workflow must be
1057 implemented by Guzzle HTTP adapters used by a client.
1058  
1059 .. _version-option:
1060  
1061 version
1062 -------
1063  
1064 :Summary: Protocol version to use with the request.
1065 :Types: string, float
1066 :Default: ``1.1``
1067  
1068 .. code-block:: php
1069  
1070 // Force HTTP/1.0
1071 $request = $client->createRequest('GET', '/get', ['version' => 1.0]);
1072 echo $request->getProtocolVersion();
1073 // 1.0
1074  
1075 .. _config-option:
1076  
1077 config
1078 ------
1079  
1080 :Summary: Associative array of config options that are forwarded to a request's
1081 configuration collection. These values are used as configuration options
1082 that can be consumed by plugins and adapters.
1083 :Types: array
1084 :Default: None
1085  
1086 .. code-block:: php
1087  
1088 $request = $client->createRequest('GET', '/get', ['config' => ['foo' => 'bar']]);
1089 echo $request->getConfig('foo');
1090 // 'bar'
1091  
1092 Some HTTP adapters allow you to specify custom adapter-specific settings. For
1093 example, you can pass custom cURL options to requests by passing an associative
1094 array in the ``config`` request option under the ``curl`` key.
1095  
1096 .. code-block:: php
1097  
1098 // Use custom cURL options with the request. This example uses NTLM auth
1099 // to authenticate with a server.
1100 $client->get('/', [
1101 'config' => [
1102 'curl' => [
1103 CURLOPT_HTTPAUTH => CURLAUTH_NTLM,
1104 CURLOPT_USERPWD => 'username:password'
1105 ]
1106 ]
1107 ]);
1108  
1109 Event Subscribers
1110 =================
1111  
1112 Requests emit lifecycle events when they are transferred. A client object has a
1113 ``GuzzleHttp\Common\EventEmitter`` object that can be used to add event
1114 *listeners* and event *subscribers* to all requests created by the client.
1115  
1116 .. important::
1117  
1118 **Every** event listener or subscriber added to a client will be added to
1119 every request created by the client.
1120  
1121 .. code-block:: php
1122  
1123 use GuzzleHttp\Client;
1124 use GuzzleHttp\Event\BeforeEvent;
1125  
1126 $client = new Client();
1127  
1128 // Add a listener that will echo out requests before they are sent
1129 $client->getEmitter()->on('before', function (BeforeEvent $e) {
1130 echo 'About to send request: ' . $e->getRequest();
1131 });
1132  
1133 $client->get('http://httpbin.org/get');
1134 // Outputs the request as a string because of the event
1135  
1136 See :doc:`events` for more information on the event system used in Guzzle.
1137  
1138 Environment Variables
1139 =====================
1140  
1141 Guzzle exposes a few environment variables that can be used to customize the
1142 behavior of the library.
1143  
1144 ``GUZZLE_CURL_SELECT_TIMEOUT``
1145 Controls the duration in seconds that ``GuzzleHttp\Adapter\Curl\MultiAdapter``
1146 will use when selecting handles using ``curl_multi_select()``. Some systems
1147 have issues with PHP's implementation of ``curl_multi_select()`` where
1148 calling this function always results in waiting for the maximum duration of
1149 the timeout.
1150 ``HTTP_PROXY``
1151 Defines the proxy to use when sending requests using the "http" protocol.
1152 ``HTTPS_PROXY``
1153 Defines the proxy to use when sending requests using the "https" protocol.
1154  
1155 Relevant ini Settings
1156 ---------------------
1157  
1158 Guzzle can utilize PHP ini settings when configuring clients.
1159  
1160 ``openssl.cafile``
1161 Specifies the path on disk to a CA file in PEM format to use when sending
1162 requests over "https". See: https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults