1: <?php
2:
3: namespace Guzzle\Http;
4:
5: use Guzzle\Common\HasDispatcherInterface;
6: use Guzzle\Common\Collection;
7: use Guzzle\Common\Exception\InvalidArgumentException;
8: use Guzzle\Http\Message\EntityEnclosingRequestInterface;
9: use Guzzle\Http\Message\RequestInterface;
10: use Guzzle\Http\Message\RequestFactoryInterface;
11: use Guzzle\Parser\UriTemplate\UriTemplateInterface;
12: use Guzzle\Http\Curl\CurlMultiInterface;
13:
14: /**
15: * Client interface for send HTTP requests
16: */
17: interface ClientInterface extends HasDispatcherInterface
18: {
19: const CREATE_REQUEST = 'client.create_request';
20:
21: /**
22: * @var string RFC 1123 HTTP-Date
23: */
24: const HTTP_DATE = 'D, d M Y H:i:s \G\M\T';
25:
26: /**
27: * Set the configuration object to use with the client
28: *
29: * @param array|Collection|string $config Parameters that define how the client behaves and connects to a
30: * webservice. Pass an array or a Collection object.
31: * @return ClientInterface
32: */
33: public function setConfig($config);
34:
35: /**
36: * Get a configuration setting or all of the configuration settings
37: *
38: * @param bool|string $key Configuration value to retrieve. Set to FALSE to retrieve all values of the client.
39: * The object return can be modified, and modifications will affect the client's config.
40: * @return mixed|Collection
41: */
42: public function getConfig($key = false);
43:
44: /**
45: * Set SSL verification options.
46: *
47: * Setting $certificateAuthority to TRUE will result in the bundled
48: * cacert.pem being used to verify against the remote host.
49: *
50: * Alternate certificates to verify against can be specified with the
51: * $certificateAuthority option set to a certificate file location to be
52: * used with CURLOPT_CAINFO, or a certificate directory path to be used
53: * with the CURLOPT_CAPATH option.
54: *
55: * Setting $certificateAuthority to FALSE will turn off peer verification,
56: * unset the bundled cacert.pem, and disable host verification. Please
57: * don't do this unless you really know what you're doing, and why
58: * you're doing it.
59: *
60: * @param string|bool $certificateAuthority bool, file path, or directory path
61: * @param bool $verifyPeer FALSE to stop cURL from verifying the peer's certificate.
62: * @param int $verifyHost Set the cURL handle's CURLOPT_SSL_VERIFYHOST option
63: *
64: * @return ClientInterface
65: */
66: public function setSslVerification($certificateAuthority = true, $verifyPeer = true, $verifyHost = 2);
67:
68: /**
69: * Get the default HTTP headers to add to each request created by the client
70: *
71: * @return Collection
72: */
73: public function getDefaultHeaders();
74:
75: /**
76: * Set the default HTTP headers to add to each request created by the client
77: *
78: * @param array|Collection $headers Default HTTP headers
79: *
80: * @return ClientInterface
81: */
82: public function setDefaultHeaders($headers);
83:
84: /**
85: * Set the URI template expander to use with the client
86: *
87: * @param UriTemplateInterface $uriTemplate URI template expander
88: *
89: * @return ClientInterface
90: */
91: public function setUriTemplate(UriTemplateInterface $uriTemplate);
92:
93: /**
94: * Get the URI template expander used by the client
95: *
96: * @return UriTemplateInterface
97: */
98: public function getUriTemplate();
99:
100: /**
101: * Expand a URI template using client configuration data
102: *
103: * @param string $template URI template to expand
104: * @param array $variables Additional variables to use in the expansion
105: *
106: * @return string
107: */
108: public function expandTemplate($template, array $variables = null);
109:
110: /**
111: * Create and return a new {@see RequestInterface} configured for the client.
112: *
113: * Use an absolute path to override the base path of the client, or a relative path to append to the base path of
114: * the client. The URI can contain the query string as well. Use an array to provide a URI template and additional
115: * variables to use in the URI template expansion.
116: *
117: * @param string $method HTTP method. Defaults to GET
118: * @param string|array $uri Resource URI.
119: * @param array|Collection $headers HTTP headers
120: * @param string|resource|array|EntityBodyInterface $body Entity body of request (POST/PUT) or response (GET)
121: *
122: * @return RequestInterface
123: * @throws InvalidArgumentException if a URI array is passed that does not contain exactly two elements: the URI
124: * followed by template variables
125: */
126: public function createRequest($method = RequestInterface::GET, $uri = null, $headers = null, $body = null);
127:
128: /**
129: * Get the client's base URL as either an expanded or raw URI template
130: *
131: * @param bool $expand Set to FALSE to get the raw base URL without URI template expansion
132: *
133: * @return string|null
134: */
135: public function getBaseUrl($expand = true);
136:
137: /**
138: * Set the base URL of the client
139: *
140: * @param string $url The base service endpoint URL of the webservice
141: *
142: * @return ClientInterface
143: */
144: public function setBaseUrl($url);
145:
146: /**
147: * Set the User-Agent header to be used on all requests from the client
148: *
149: * @param string $userAgent User agent string
150: * @param bool $includeDefault Set to true to prepend the value to Guzzle's default user agent string
151: *
152: * @return self
153: */
154: public function setUserAgent($userAgent, $includeDefault = false);
155:
156: /**
157: * Create a GET request for the client
158: *
159: * @param string|array $uri Resource URI
160: * @param array|Collection $headers HTTP headers
161: * @param string|resource|array|EntityBodyInterface $body Where to store the response entity body
162: *
163: * @return RequestInterface
164: * @see Guzzle\Http\ClientInterface::createRequest()
165: */
166: public function get($uri = null, $headers = null, $body = null);
167:
168: /**
169: * Create a HEAD request for the client
170: *
171: * @param string|array $uri Resource URI
172: * @param array|Collection $headers HTTP headers
173: *
174: * @return RequestInterface
175: * @see Guzzle\Http\ClientInterface::createRequest()
176: */
177: public function head($uri = null, $headers = null);
178:
179: /**
180: * Create a DELETE request for the client
181: *
182: * @param string|array $uri Resource URI
183: * @param array|Collection $headers HTTP headers
184: * @param string|resource|EntityBodyInterface $body Body to send in the request
185: *
186: * @return EntityEnclosingRequestInterface
187: * @see Guzzle\Http\ClientInterface::createRequest()
188: */
189: public function delete($uri = null, $headers = null, $body = null);
190:
191: /**
192: * Create a PUT request for the client
193: *
194: * @param string|array $uri Resource URI
195: * @param array|Collection $headers HTTP headers
196: * @param string|resource|EntityBodyInterface $body Body to send in the request
197: *
198: * @return EntityEnclosingRequestInterface
199: * @see Guzzle\Http\ClientInterface::createRequest()
200: */
201: public function put($uri = null, $headers = null, $body = null);
202:
203: /**
204: * Create a PATCH request for the client
205: *
206: * @param string|array $uri Resource URI
207: * @param array|Collection $headers HTTP headers
208: * @param string|resource|EntityBodyInterface $body Body to send in the request
209: *
210: * @return EntityEnclosingRequestInterface
211: * @see Guzzle\Http\ClientInterface::createRequest()
212: */
213: public function patch($uri = null, $headers = null, $body = null);
214:
215: /**
216: * Create a POST request for the client
217: *
218: * @param string|array $uri Resource URI
219: * @param array|Collection $headers HTTP headers
220: * @param array|Collection|string|EntityBodyInterface $postBody POST body. Can be a string, EntityBody, or
221: * associative array of POST fields to send in the body of the
222: * request. Prefix a value in the array with the @ symbol to
223: * reference a file.
224: * @return EntityEnclosingRequestInterface
225: * @see Guzzle\Http\ClientInterface::createRequest()
226: */
227: public function post($uri = null, $headers = null, $postBody = null);
228:
229: /**
230: * Create an OPTIONS request for the client
231: *
232: * @param string|array $uri Resource URI
233: *
234: * @return RequestInterface
235: * @see Guzzle\Http\ClientInterface::createRequest()
236: */
237: public function options($uri = null);
238:
239: /**
240: * Sends a single request or an array of requests in parallel
241: *
242: * @param array $requests Request(s) to send
243: *
244: * @return array Returns the response(s)
245: */
246: public function send($requests);
247:
248: /**
249: * Set a curl multi object to be used internally by the client for transferring requests.
250: *
251: * @param CurlMultiInterface $curlMulti Multi object
252: *
253: * @return ClientInterface
254: */
255: public function setCurlMulti(CurlMultiInterface $curlMulti);
256:
257: /**
258: * Get the curl multi object to be used internally by the client for transferring requests.
259: *
260: * @return CurlMultiInterface
261: */
262: public function getCurlMulti();
263:
264: /**
265: * Set the request factory to use with the client when creating requests
266: *
267: * @param RequestFactoryInterface $factory Request factory
268: *
269: * @return ClientInterface
270: */
271: public function setRequestFactory(RequestFactoryInterface $factory);
272: }
273: