1: <?php
2:
3: namespace Guzzle\Http\Message;
4:
5: use Guzzle\Common\Collection;
6: use Guzzle\Common\HasDispatcherInterface;
7: use Guzzle\Http\Exception\RequestException;
8: use Guzzle\Http\ClientInterface;
9: use Guzzle\Http\EntityBodyInterface;
10: use Guzzle\Http\Url;
11: use Guzzle\Http\QueryString;
12:
13: /**
14: * Generic HTTP request interface
15: */
16: interface RequestInterface extends MessageInterface, HasDispatcherInterface
17: {
18: const STATE_NEW = 'new';
19: const STATE_COMPLETE = 'complete';
20: const STATE_TRANSFER = 'transfer';
21: const STATE_ERROR = 'error';
22:
23: const GET = 'GET';
24: const PUT = 'PUT';
25: const POST = 'POST';
26: const DELETE = 'DELETE';
27: const HEAD = 'HEAD';
28: const CONNECT = 'CONNECT';
29: const OPTIONS = 'OPTIONS';
30: const TRACE = 'TRACE';
31: const PATCH = 'PATCH';
32:
33: /**
34: * Get the HTTP request as a string
35: *
36: * @return string
37: */
38: public function __toString();
39:
40: /**
41: * Set the client used to transport the request
42: *
43: * @param ClientInterface $client
44: *
45: * @return RequestInterface
46: */
47: public function setClient(ClientInterface $client);
48:
49: /**
50: * Get the client used to transport the request
51: *
52: * @return ClientInterface $client
53: */
54: public function getClient();
55:
56: /**
57: * Set the URL of the request
58: *
59: * Warning: Calling this method will modify headers, rewrite the query string object, and set other data
60: * associated with the request.
61: *
62: * @param string $url|Url Full URL to set including query string
63: *
64: * @return RequestInterface
65: */
66: public function setUrl($url);
67:
68: /**
69: * Send the request
70: *
71: * @return Response
72: * @throws RequestException on a request error
73: */
74: public function send();
75:
76: /**
77: * Get the previously received {@see Response} or NULL if the request has
78: * not been sent
79: *
80: * @return Response|null
81: */
82: public function getResponse();
83:
84: /**
85: * Get the collection of key value pairs that will be used as the query
86: * string in the request
87: *
88: * @return QueryString
89: */
90: public function getQuery();
91:
92: /**
93: * Get the HTTP method of the request
94: *
95: * @return string
96: */
97: public function getMethod();
98:
99: /**
100: * Get the URI scheme of the request (http, https, ftp, etc)
101: *
102: * @return string
103: */
104: public function getScheme();
105:
106: /**
107: * Set the URI scheme of the request (http, https, ftp, etc)
108: *
109: * @param string $scheme Scheme to set
110: *
111: * @return RequestInterface
112: */
113: public function setScheme($scheme);
114:
115: /**
116: * Get the host of the request
117: *
118: * @return string
119: */
120: public function getHost();
121:
122: /**
123: * Set the host of the request. Including a port in the host will modify
124: * the port of the request.
125: *
126: * @param string $host Host to set (e.g. www.yahoo.com, www.yahoo.com:80)
127: *
128: * @return RequestInterface
129: */
130: public function setHost($host);
131:
132: /**
133: * Get the HTTP protocol version of the request
134: *
135: * @return string
136: */
137: public function getProtocolVersion();
138:
139: /**
140: * Set the HTTP protocol version of the request (e.g. 1.1 or 1.0)
141: *
142: * @param string $protocol HTTP protocol version to use with the request
143: *
144: * @return RequestInterface
145: */
146: public function setProtocolVersion($protocol);
147:
148: /**
149: * Get the path of the request (e.g. '/', '/index.html')
150: *
151: * @return string
152: */
153: public function getPath();
154:
155: /**
156: * Set the path of the request (e.g. '/', '/index.html')
157: *
158: * @param string|array $path Path to set or array of segments to implode
159: *
160: * @return RequestInterface
161: */
162: public function setPath($path);
163:
164: /**
165: * Get the port that the request will be sent on if it has been set
166: *
167: * @return int|null
168: */
169: public function getPort();
170:
171: /**
172: * Set the port that the request will be sent on
173: *
174: * @param int $port Port number to set
175: *
176: * @return RequestInterface
177: */
178: public function setPort($port);
179:
180: /**
181: * Get the username to pass in the URL if set
182: *
183: * @return string|null
184: */
185: public function getUsername();
186:
187: /**
188: * Set HTTP authorization parameters
189: *
190: * @param string|bool $user User name or false disable authentication
191: * @param string $password Password
192: * @param string $scheme Authentication scheme to use (CURLAUTH_BASIC, CURLAUTH_DIGEST, etc)
193: *
194: * @return Request
195: *
196: * @link http://www.ietf.org/rfc/rfc2617.txt
197: * @link http://php.net/manual/en/function.curl-setopt.php See the available options for CURLOPT_HTTPAUTH
198: * @throws RequestException
199: */
200: public function setAuth($user, $password = '', $scheme = 'Basic');
201:
202: /**
203: * Get the password to pass in the URL if set
204: *
205: * @return string|null
206: */
207: public function getPassword();
208:
209: /**
210: * Get the resource part of the the request, including the path, query
211: * string, and fragment
212: *
213: * @return string
214: */
215: public function getResource();
216:
217: /**
218: * Get the full URL of the request (e.g. 'http://www.guzzle-project.com/')
219: * scheme://username:password@domain:port/path?query_string#fragment
220: *
221: * @param bool $asObject Set to TRUE to retrieve the URL as a clone of the URL object owned by the request.
222: *
223: * @return string|Url
224: */
225: public function getUrl($asObject = false);
226:
227: /**
228: * Get the state of the request. One of 'complete', 'sending', 'new'
229: *
230: * @return string
231: */
232: public function getState();
233:
234: /**
235: * Set the state of the request
236: *
237: * @param string $state State of the request (complete, sending, or new)
238: * @param array $context Contextual information about the state change
239: *
240: * @return RequestInterface
241: */
242: public function setState($state, array $context = array());
243:
244: /**
245: * Get the cURL options that will be applied when the cURL handle is created
246: *
247: * @return Collection
248: */
249: public function getCurlOptions();
250:
251: /**
252: * Method to receive HTTP response headers as they are retrieved
253: *
254: * @param string $data Header data.
255: *
256: * @return integer Returns the size of the data.
257: */
258: public function receiveResponseHeader($data);
259:
260: /**
261: * Set the EntityBody that will hold a successful response message's entity body.
262: *
263: * This method should be invoked when you need to send the response's entity body somewhere other than the normal
264: * php://temp buffer. For example, you can send the entity body to a socket, file, or some other custom stream.
265: *
266: * @param EntityBodyInterface|string|resource $body Response body object. Pass a string to attempt to store the
267: * response body in a local file.
268: * @return Request
269: */
270: public function setResponseBody($body);
271:
272: /**
273: * Get the EntityBody that will hold the resulting response message's entity body. This response body will only
274: * be used for successful responses. Intermediate responses (e.g. redirects) will not use the targeted response
275: * body.
276: *
277: * @return EntityBodyInterface
278: */
279: public function getResponseBody();
280:
281: /**
282: * Determine if the response body is repeatable (readable + seekable)
283: *
284: * @return bool
285: */
286: public function isResponseBodyRepeatable();
287:
288: /**
289: * Manually set a response for the request.
290: *
291: * This method is useful for specifying a mock response for the request or setting the response using a cache.
292: * Manually setting a response will bypass the actual sending of a request.
293: *
294: * @param Response $response Response object to set
295: * @param bool $queued Set to TRUE to keep the request in a state of not having been sent, but queue the
296: * response for send()
297: *
298: * @return RequestInterface Returns a reference to the object.
299: */
300: public function setResponse(Response $response, $queued = false);
301:
302: /**
303: * Get an array of Cookies
304: *
305: * @return array
306: */
307: public function getCookies();
308:
309: /**
310: * Get a cookie value by name
311: *
312: * @param string $name Cookie to retrieve
313: *
314: * @return null|string
315: */
316: public function getCookie($name);
317:
318: /**
319: * Add a Cookie value by name to the Cookie header
320: *
321: * @param string $name Name of the cookie to add
322: * @param string $value Value to set
323: *
324: * @return RequestInterface
325: */
326: public function addCookie($name, $value);
327:
328: /**
329: * Remove a specific cookie value by name
330: *
331: * @param string $name Cookie to remove by name
332: *
333: * @return RequestInterface
334: */
335: public function removeCookie($name);
336:
337: /**
338: * Returns whether or not the request can be cached
339: *
340: * @return bool
341: */
342: public function canCache();
343:
344: /**
345: * Set whether or not the request is a request that resulted from a redirect
346: *
347: * @param bool $isRedirect
348: *
349: * @return self
350: */
351: public function setIsRedirect($isRedirect);
352:
353: /**
354: * Check whether or not the request is a request that resulted from a redirect
355: *
356: * @return bool
357: */
358: public function isRedirect();
359: }
360: