scratch – Blame information for rev 87
?pathlinks?
Rev | Author | Line No. | Line |
---|---|---|---|
87 | office | 1 | === |
2 | FAQ |
||
3 | === |
||
4 | |||
5 | Why should I use Guzzle? |
||
6 | ======================== |
||
7 | |||
8 | Guzzle makes it easy to send HTTP requests and super simple to integrate with |
||
9 | web services. Guzzle manages things like persistent connections, represents |
||
10 | query strings as collections, makes it simple to send streaming POST requests |
||
11 | with fields and files, and abstracts away the underlying HTTP transport layer |
||
12 | (cURL, ``fopen()``, etc.). By providing an object oriented interface for HTTP |
||
13 | clients, requests, responses, headers, and message bodies, Guzzle makes it so |
||
14 | that you no longer need to fool around with cURL options or stream contexts. |
||
15 | |||
16 | To get a feel for how easy it is to use Guzzle, take a look at the |
||
17 | :doc:`quick start guide <quickstart>`. |
||
18 | |||
19 | Swappable HTTP Adapters |
||
20 | ----------------------- |
||
21 | |||
22 | Guzzle will use the most appropriate HTTP adapter to send requests based on the |
||
23 | capabilities of your environment and the options applied to a request. When |
||
24 | cURL is available on your system, Guzzle will automatically use cURL. When a |
||
25 | request is sent with the ``stream=true`` request option, Guzzle will |
||
26 | automatically use the PHP stream wrapper HTTP adapter so that bytes are only |
||
27 | read from the HTTP stream as needed. |
||
28 | |||
29 | .. note:: |
||
30 | |||
31 | Guzzle has historically only utilized cURL to send HTTP requests. cURL is |
||
32 | an amazing HTTP client (arguably the best), and Guzzle will continue to use |
||
33 | it by default when it is available. It is rare, but some developers don't |
||
34 | have cURL installed on their systems or run into version specific issues. |
||
35 | By allowing swappable HTTP adapters, Guzzle is now much more customizable |
||
36 | and able to adapt to fit the needs of more developers. |
||
37 | |||
38 | HTTP Streams |
||
39 | ------------ |
||
40 | |||
41 | Request and response message bodies use :doc:`Guzzle Streams <streams>`, |
||
42 | allowing you to stream data without needing to load it all into memory. |
||
43 | Guzzle's stream layer provides a large suite of functionality: |
||
44 | |||
45 | - You can modify streams at runtime using custom or a number of |
||
46 | pre-made decorators. |
||
47 | - You can emit progress events as data is read from a stream. |
||
48 | - You can validate the integrity of a stream using a rolling hash as data is |
||
49 | read from a stream. |
||
50 | |||
51 | Event System |
||
52 | ------------ |
||
53 | |||
54 | Guzzle's flexible event system allows you to completely modify the behavior |
||
55 | of a client or request at runtime to cater them for any API. You can send a |
||
56 | request with a client, and the client can do things like automatically retry |
||
57 | your request if it fails, automatically redirect, log HTTP messages that are |
||
58 | sent over the wire, emit progress events as data is uploaded and downloaded, |
||
59 | sign requests using OAuth 1.0, verify the integrity of messages before and |
||
60 | after they are sent over the wire, and anything else you might need. |
||
61 | |||
62 | Easy to Test |
||
63 | ------------ |
||
64 | |||
65 | Another important aspect of Guzzle is that it's really |
||
66 | :doc:`easy to test clients <testing>`. You can mock HTTP responses and when |
||
67 | testing an adapter implementation, Guzzle provides a mock web server that |
||
68 | makes it easy. |
||
69 | |||
70 | Large Ecosystem |
||
71 | --------------- |
||
72 | |||
73 | Guzzle has a large `ecosystem of plugins <http://guzzle.readthedocs.org/en/latest/index.html#http-components>`_, |
||
74 | including `service descriptions <https://github.com/guzzle/guzzle-services>`_ |
||
75 | which allows you to abstract web services using service descriptions. These |
||
76 | service descriptions define how to serialize an HTTP request and how to parse |
||
77 | an HTTP response into a more meaningful model object. |
||
78 | |||
79 | - `Guzzle Command <https://github.com/guzzle/command>`_: Provides the building |
||
80 | blocks for service description abstraction. |
||
81 | - `Guzzle Services <https://github.com/guzzle/guzzle-services>`_: Provides an |
||
82 | implementation of "Guzzle Command" that utlizes Guzzle's service description |
||
83 | format. |
||
84 | |||
85 | Is it possible to use Guzzle 3 and 4 in the same project? |
||
86 | ========================================================= |
||
87 | |||
88 | Yes, because Guzzle 3 and 4 use different Packagist packages and different |
||
89 | namespaces. You simply need to add ``guzzle/guzzle`` (Guzzle 3) and |
||
90 | ``guzzlehttp/guzzle`` (Guzzle 4+) to your project's composer.json file. |
||
91 | |||
92 | .. code-block:: javascript |
||
93 | |||
94 | { |
||
95 | "require": { |
||
96 | "guzzle/guzzle": 3.*, |
||
97 | "guzzlehttp/guzzle": 4.* |
||
98 | } |
||
99 | } |
||
100 | |||
101 | You might need to use Guzzle 3 and Guzzle 4 in the same project due to a |
||
102 | requirement of a legacy application or a dependency that has not yet migrated |
||
103 | to Guzzle 4.0. |
||
104 | |||
105 | How do I migrate from Guzzle 3 to 4? |
||
106 | ==================================== |
||
107 | |||
108 | See https://github.com/guzzle/guzzle/blob/master/UPGRADING.md#3x-to-40. |
||
109 | |||
110 | What is this Maximum function nesting error? |
||
111 | ============================================ |
||
112 | |||
113 | Maximum function nesting level of '100' reached, aborting |
||
114 | |||
115 | You could run into this error if you have the XDebug extension installed and |
||
116 | you execute a lot of requests in callbacks. This error message comes |
||
117 | specifically from the XDebug extension. PHP itself does not have a function |
||
118 | nesting limit. Change this setting in your php.ini to increase the limit:: |
||
119 | |||
120 | xdebug.max_nesting_level = 1000 |
||
121 | |||
122 | [`source <http://stackoverflow.com/a/4293870/151504>`_] |
||
123 | |||
124 | Why am I getting a 417 error response? |
||
125 | ====================================== |
||
126 | |||
127 | This can occur for a number of reasons, but if you are sending PUT, POST, or |
||
128 | PATCH requests with an ``Expect: 100-Continue`` header, a server that does not |
||
129 | support this header will return a 417 response. You can work around this by |
||
130 | setting the ``expect`` request option to ``false``: |
||
131 | |||
132 | .. code-block:: php |
||
133 | |||
134 | $client = new GuzzleHttp\Client(); |
||
135 | |||
136 | // Disable the expect header on a single request |
||
137 | $response = $client->put('/', [], 'the body', [ |
||
138 | 'expect' => false |
||
139 | ]); |
||
140 | |||
141 | // Disable the expect header on all client requests |
||
142 | $client->setDefaultOption('expect', false) |
||
143 | |||
144 | How can I add custom cURL options? |
||
145 | ================================== |
||
146 | |||
147 | cURL offer a huge number of `customizable options <http://us1.php.net/curl_setopt>`_. |
||
148 | While Guzzle normalizes many of these options across different adapters, there |
||
149 | are times when you need to set custom cURL options. This can be accomplished |
||
150 | by passing an associative array of cURL settings in the **curl** key of the |
||
151 | **config** request option. |
||
152 | |||
153 | For example, let's say you need to customize the outgoing network interface |
||
154 | used with a client. |
||
155 | |||
156 | .. code-block:: php |
||
157 | |||
158 | $client->get('/', [ |
||
159 | 'config' => [ |
||
160 | 'curl' => [ |
||
161 | CURLOPT_INTERFACE => 'xxx.xxx.xxx.xxx' |
||
162 | ] |
||
163 | ] |
||
164 | ]); |
||
165 | |||
166 | How can I add custom stream context options? |
||
167 | ============================================ |
||
168 | |||
169 | You can pass custom `stream context options <http://www.php.net/manual/en/context.php>`_ |
||
170 | using the **stream_context** key of the **config** request option. The |
||
171 | **stream_context** array is an associative array where each key is a PHP |
||
172 | transport, and each value is an associative array of transport options. |
||
173 | |||
174 | For example, let's say you need to customize the outgoing network interface |
||
175 | used with a client and allow self-signed certificates. |
||
176 | |||
177 | .. code-block:: php |
||
178 | |||
179 | $client->get('/', [ |
||
180 | 'stream' => true, |
||
181 | 'config' => [ |
||
182 | 'stream_context' => [ |
||
183 | 'ssl' => [ |
||
184 | 'allow_self_signed' => true |
||
185 | ], |
||
186 | 'socket' => [ |
||
187 | 'bindto' => 'xxx.xxx.xxx.xxx' |
||
188 | ] |
||
189 | ] |
||
190 | ] |
||
191 | ]); |