scratch – Blame information for rev 87

Subversion Repositories:
Rev:
Rev Author Line No. Line
87 office 1 ==========
2 Quickstart
3 ==========
4  
5 This page provides a quick introduction to Guzzle and introductory examples.
6 If you have not already installed, Guzzle, head over to the :ref:`installation`
7 page.
8  
9 Make a Request
10 ==============
11  
12 You can send requests with Guzzle in one of two ways: through the procedural
13 API or using a ``GuzzleHttp\ClientInterface`` object. Using the procedural API
14 is an easy way to send a quick HTTP request. Using a Client object provides
15 much more flexibility in how requests are transferred and allows you to more
16 easily test the client.
17  
18 Procedural API
19 --------------
20  
21 Here's an example of sending a ``POST`` request using the procedural API.
22  
23 .. code-block:: php
24  
25 $response = GuzzleHttp\post('http://httpbin.org/post', [
26 'headers' => ['X-Foo' => 'Bar'],
27 'body' => ['field_name' => 'value']
28 ]);
29  
30 You can send all kinds of HTTP requests with the procedural API. Just call
31 the function that maps to the HTTP method name.
32  
33 .. code-block:: php
34  
35 $response = GuzzleHttp\head('http://httpbin.org/get');
36 $response = GuzzleHttp\post('http://httpbin.org/post');
37 $response = GuzzleHttp\put('http://httpbin.org/put');
38 $response = GuzzleHttp\delete('http://httpbin.org/delete');
39 $response = GuzzleHttp\options('http://httpbin.org/get');
40  
41 Creating a Client
42 -----------------
43  
44 The procedural API is simple but not very testable; it's best left for quick
45 prototyping. If you want to use Guzzle in a more flexible and testable way,
46 then you'll need to use a ``GuzzleHttp\ClientInterface`` object.
47  
48 .. code-block:: php
49  
50 use GuzzleHttp\Client;
51  
52 $client = new Client();
53 $response = $client->get('http://httpbin.org/get');
54  
55 // You can use the same methods you saw in the procedural API
56 $response = $client->delete('http://httpbin.org/delete');
57 $response = $client->head('http://httpbin.org/get');
58 $response = $client->options('http://httpbin.org/get');
59 $response = $client->patch('http://httpbin.org/patch');
60 $response = $client->post('http://httpbin.org/post');
61 $response = $client->put('http://httpbin.org/put');
62  
63 You can create a request with a client and then send the request with the
64 client when you're ready.
65  
66 .. code-block:: php
67  
68 $request = $client->createRequest('GET', 'http://www.foo.com');
69 $response = $client->send($request);
70  
71 Client objects provide a great deal of flexibility in how request are
72 transferred including default request options, subscribers that are attached
73 to each request, and a base URL that allows you to send requests with relative
74 URLs. You can find out all about clients in the :doc:`clients` page of the
75 documentation.
76  
77 Using Responses
78 ===============
79  
80 In the previous examples, we retrieved a ``$response`` variable. This value is
81 actually a ``GuzzleHttp\Message\ResponseInterface`` object and contains lots
82 of helpful information.
83  
84 You can get the status code and reason phrase of the response.
85  
86 .. code-block:: php
87  
88 $code = $response->getStatusCode();
89 // 200
90  
91 $reason = $response->getReasonPhrase();
92 // OK
93  
94 Response Body
95 -------------
96  
97 The body of a response can be retrieved and cast to a string.
98  
99 .. code-block:: php
100  
101 $body = $response->getBody();
102 echo $body;
103 // { "some_json_data" ...}
104  
105 You can also read read bytes from body of a response like a stream.
106  
107 .. code-block:: php
108  
109 $body = $response->getBody();
110  
111 while (!$body->eof()) {
112 echo $body->read(1024);
113 }
114  
115 JSON Responses
116 ~~~~~~~~~~~~~~
117  
118 You can more easily work with JSON responses using the ``json()`` method of a
119 response.
120  
121 .. code-block:: php
122  
123 $response = $client->get('http://httpbin.org/get');
124 $json = $response->json();
125 var_dump($json[0]['origin']);
126  
127 Guzzle internally uses PHP's ``json_decode()`` function to parse responses. If
128 Guzzle is unable to parse the JSON response body, then a
129 ``GuzzleHttp\Exception\ParseException`` is thrown.
130  
131 XML Responses
132 ~~~~~~~~~~~~~
133  
134 You can use a response's ``xml()`` method to more easily work with responses
135 that contain XML data.
136  
137 .. code-block:: php
138  
139 $response = $client->get('https://github.com/mtdowling.atom');
140 $xml = $response->xml();
141 echo $xml->id;
142 // tag:github.com,2008:/mtdowling
143  
144 Guzzle internally uses a ``SimpleXMLElement`` object to parse responses. If
145 Guzzle is unable to parse the XML response body, then a
146 ``GuzzleHttp\Exception\ParseException`` is thrown.
147  
148 Query String Parameters
149 =======================
150  
151 Sending query string parameters with a request is easy. You can set query
152 string parameters in the request's URL.
153  
154 .. code-block:: php
155  
156 $response = $client->get('http://httpbin.org?foo=bar');
157  
158 You can also specify the query string parameters using the ``query`` request
159 option.
160  
161 .. code-block:: php
162  
163 $client->get('http://httpbin.org', [
164 'query' => ['foo' => 'bar']
165 ]);
166  
167 And finally, you can build up the query string of a request as needed by
168 calling the ``getQuery()`` method of a request and modifying the request's
169 ``GuzzleHttp\Query`` object as needed.
170  
171 .. code-block:: php
172  
173 $request = $client->createRequest('GET', 'http://httpbin.org');
174 $query = $request->getQuery();
175 $query->set('foo', 'bar');
176  
177 // You can use the query string object like an array
178 $query['baz'] = 'bam';
179  
180 // The query object can be cast to a string
181 echo $query;
182 // foo=bar&baz=bam
183  
184 // Setting a value to false or null will cause the "=" sign to be omitted
185 $query['empty'] = null;
186 echo $query;
187 // foo=bar&baz=bam&empty
188  
189 // Use an empty string to include the "=" sign with an empty value
190 $query['empty'] = '';
191 echo $query;
192 // foo=bar&baz=bam&empty=
193  
194 .. _headers:
195  
196 Request and Response Headers
197 ----------------------------
198  
199 You can specify request headers when sending or creating requests with a
200 client. In the following example, we send the ``X-Foo-Header`` with a value of
201 ``value`` by setting the ``headers`` request option.
202  
203 .. code-block:: php
204  
205 $response = $client->get('http://httpbin.org/get', [
206 'headers' => ['X-Foo-Header' => 'value']
207 ]);
208  
209 You can view the headers of a response using header specific methods of a
210 response class. Headers work exactly the same way for request and response
211 object.
212  
213 You can retrieve a header from a request or response using the ``getHeader()``
214 method of the object. This method is case-insensitive and by default will
215 return a string containing the header field value.
216  
217 .. code-block:: php
218  
219 $response = $client->get('http://www.yahoo.com');
220 $length = $response->getHeader('Content-Length');
221  
222 Header fields that contain multiple values can be retrieved as a string or as
223 an array. Retrieving the field values as a string will naively concatenate all
224 of the header values together with a comma. Because not all header fields
225 should be represented this way (e.g., ``Set-Cookie``), you can pass an optional
226 flag to the ``getHeader()`` method to retrieve the header values as an array.
227  
228 .. code-block:: php
229  
230 $values = $response->getHeader('Set-Cookie', true);
231 foreach ($values as $value) {
232 echo $value;
233 }
234  
235 You can test if a request or response has a specific header using the
236 ``hasHeader()`` method. This method accepts a case-insensitive string and
237 returns true if the header is present or false if it is not.
238  
239 You can retrieve all of the headers of a message using the ``getHeaders()``
240 method of a request or response. The return value is an associative array where
241 the keys represent the header name as it will be sent over the wire, and each
242 value is an array of strings associated with the header.
243  
244 .. code-block:: php
245  
246 $headers = $response->getHeaders();
247 foreach ($message->getHeaders() as $name => $values) {
248 echo $name . ": " . implode(", ", $values);
249 }
250  
251 Modifying headers
252 -----------------
253  
254 The headers of a message can be modified using the ``setHeader()``,
255 ``addHeader()``, ``setHeaders()``, and ``removeHeader()`` methods of a request
256 or response object.
257  
258 .. code-block:: php
259  
260 $request = $client->createRequest('GET', 'http://httpbin.org/get');
261  
262 // Set a single value for a header
263 $request->setHeader('User-Agent', 'Testing!');
264  
265 // Set multiple values for a header in one call
266 $request->setHeader('X-Foo', ['Baz', 'Bar']);
267  
268 // Add a header to the message
269 $request->addHeader('X-Foo', 'Bam');
270  
271 echo $request->getHeader('X-Foo');
272 // Baz, Bar, Bam
273  
274 // Remove a specific header using a case-insensitive name
275 $request->removeHeader('x-foo');
276 echo $request->getHeader('X-Foo');
277 // Echoes an empty string: ''
278  
279 Uploading Data
280 ==============
281  
282 Guzzle provides several methods of uploading data.
283  
284 You can send requests that contain a stream of data by passing a string,
285 resource returned from ``fopen``, or a ``GuzzleHttp\Stream\StreamInterface``
286 object to the ``body`` request option.
287  
288 .. code-block:: php
289  
290 $r = $client->post('http://httpbin.org/post', ['body' => 'raw data']);
291  
292 You can easily upload JSON data using the ``json`` request option.
293  
294 .. code-block:: php
295  
296 $r = $client->put('http://httpbin.org/put', ['json' => ['foo' => 'bar']]);
297  
298 POST Requests
299 -------------
300  
301 In addition to specifying the raw data of a request using the ``body`` request
302 option, Guzzle provides helpful abstractions over sending POST data.
303  
304 Sending POST Fields
305 ~~~~~~~~~~~~~~~~~~~
306  
307 Sending ``application/x-www-form-urlencoded`` POST requests requires that you
308 specify the body of a POST request as an array.
309  
310 .. code-block:: php
311  
312 $response = $client->post('http://httpbin.org/post', [
313 'body' => [
314 'field_name' => 'abc',
315 'other_field' => '123'
316 ]
317 ]);
318  
319 You can also build up POST requests before sending them.
320  
321 .. code-block:: php
322  
323 $request = $client->createRequest('POST', 'http://httpbin.org/post');
324 $postBody = $request->getBody();
325  
326 // $postBody is an instance of GuzzleHttp\Post\PostBodyInterface
327 $postBody->setField('foo', 'bar');
328 echo $postBody->getField('foo');
329 // 'bar'
330  
331 echo json_encode($postBody->getFields());
332 // {"foo": "bar"}
333  
334 // Send the POST request
335 $response = $client->send($request);
336  
337 Sending POST Files
338 ~~~~~~~~~~~~~~~~~~
339  
340 Sending ``multipart/form-data`` POST requests (POST requests that contain
341 files) is the same as sending ``application/x-www-form-urlencoded``, except
342 some of the array values of the POST fields map to PHP ``fopen`` resources, or
343 ``GuzzleHttp\Stream\StreamInterface``, or
344 ``GuzzleHttp\Post\PostFileInterface`` objects.
345  
346 .. code-block:: php
347  
348 use GuzzleHttp\Post\PostFile;
349  
350 $response = $client->post('http://httpbin.org/post', [
351 'body' => [
352 'field_name' => 'abc',
353 'file_filed' => fopen('/path/to/file', 'r'),
354 'other_file' => new PostFile('other_file', 'this is the content')
355 ]
356 ]);
357  
358 Just like when sending POST fields, you can also build up POST requests with
359 files before sending them.
360  
361 .. code-block:: php
362  
363 use GuzzleHttp\Post\PostFile;
364  
365 $request = $client->createRequest('POST', 'http://httpbin.org/post');
366 $postBody = $request->getBody();
367 $postBody->setField('foo', 'bar');
368 $postBody->addFile(new PostFile('test', fopen('/path/to/file', 'r')));
369 $response = $client->send($request);
370  
371 Cookies
372 =======
373  
374 Guzzle can maintain a cookie session for you if instructed using the
375 ``cookies`` request option.
376  
377 - Set to ``true`` to use a shared cookie session associated with the client.
378 - Pass an associative array containing cookies to send in the request and start
379 a new cookie session.
380 - Set to a ``GuzzleHttp\Subscriber\CookieJar\CookieJarInterface`` object to use
381 an existing cookie jar.
382  
383 Redirects
384 =========
385  
386 Guzzle will automatically follow redirects unless you tell it not to. You can
387 customize the redirect behavior using the ``allow_redirects`` request option.
388  
389 - Set to true to enable normal redirects with a maximum number of 5 redirects.
390 This is the default setting.
391 - Set to false to disable redirects.
392 - Pass an associative array containing the 'max' key to specify the maximum
393 number of redirects and optionally provide a 'strict' key value to specify
394 whether or not to use strict RFC compliant redirects (meaning redirect POST
395 requests with POST requests vs. doing what most browsers do which is
396 redirect POST requests with GET requests).
397  
398 .. code-block:: php
399  
400 $response = $client->get('http://github.com');
401 echo $response->getStatusCode();
402 // 200
403 echo $response->getEffectiveUrl();
404 // 'https://github.com/'
405  
406 The following example shows that redirects can be disabled.
407  
408 .. code-block:: php
409  
410 $response = $client->get('http://github.com', ['allow_redirects' => false]);
411 echo $response->getStatusCode();
412 // 301
413 echo $response->getEffectiveUrl();
414 // 'http://github.com/'
415  
416 Exceptions
417 ==========
418  
419 Guzzle throws exceptions for errors that occur during a transfer.
420  
421 - In the event of a networking error (connection timeout, DNS errors, etc.),
422 a ``GuzzleHttp\Exception\RequestException`` is thrown. This exception
423 extends from ``GuzzleHttp\Exception\TransferException``. Catching this
424 exception will catch any exception that can be thrown while transferring
425 (non-parallel) requests.
426  
427 .. code-block:: php
428  
429 use GuzzleHttp\Exception\RequestException;
430  
431 try {
432 $client->get('https://github.com/_abc_123_404');
433 } catch (RequestException $e) {
434 echo $e->getRequest();
435 if ($e->hasResponse()) {
436 echo $e->getResponse();
437 }
438 }
439  
440 - A ``GuzzleHttp\Exception\ClientException`` is thrown for 400
441 level errors if the ``exceptions`` request option is set to true. This
442 exception extends from ``GuzzleHttp\Exception\BadResponseException`` and
443 ``GuzzleHttp\Exception\BadResponseException`` extends from
444 ``GuzzleHttp\Exception\RequestException``.
445  
446 .. code-block:: php
447  
448 use GuzzleHttp\Exception\ClientException;
449  
450 try {
451 $client->get('https://github.com/_abc_123_404');
452 } catch (ClientException $e) {
453 echo $e->getRequest();
454 echo $e->getResponse();
455 }
456  
457 - A ``GuzzleHttp\Exception\ServerException`` is thrown for 500 level
458 errors if the ``exceptions`` request option is set to true. This
459 exception extends from ``GuzzleHttp\Exception\BadResponseException``.
460 - A ``GuzzleHttp\Exception\TooManyRedirectsException`` is thrown when too
461 many redirects are followed. This exception extends from ``GuzzleHttp\Exception\RequestException``.
462 - A ``GuzzleHttp\Exception\AdapterException`` is thrown when an error occurs
463 in an HTTP adapter during a parallel request. This exception is only thrown
464 when using the ``sendAll()`` method of a client.
465  
466 All of the above exceptions extend from
467 ``GuzzleHttp\Exception\TransferException``.