scratch – Blame information for rev 87

Subversion Repositories:
Rev:
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 ]);