IClient.php 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * @copyright Copyright (c) 2016, ownCloud, Inc.
  5. *
  6. * @author Lukas Reschke <lukas@statuscode.ch>
  7. * @author Morris Jobke <hey@morrisjobke.de>
  8. * @author Roeland Jago Douma <roeland@famdouma.nl>
  9. *
  10. * @license AGPL-3.0
  11. *
  12. * This code is free software: you can redistribute it and/or modify
  13. * it under the terms of the GNU Affero General Public License, version 3,
  14. * as published by the Free Software Foundation.
  15. *
  16. * This program is distributed in the hope that it will be useful,
  17. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  19. * GNU Affero General Public License for more details.
  20. *
  21. * You should have received a copy of the GNU Affero General Public License, version 3,
  22. * along with this program. If not, see <http://www.gnu.org/licenses/>
  23. *
  24. */
  25. namespace OCP\Http\Client;
  26. /**
  27. * Interface IClient
  28. *
  29. * @since 8.1.0
  30. */
  31. interface IClient {
  32. /**
  33. * Sends a GET request
  34. * @param string $uri
  35. * @param array $options Array such as
  36. * 'query' => [
  37. * 'field' => 'abc',
  38. * 'other_field' => '123',
  39. * 'file_name' => fopen('/path/to/file', 'r'),
  40. * ],
  41. * 'headers' => [
  42. * 'foo' => 'bar',
  43. * ],
  44. * 'cookies' => [
  45. * 'foo' => 'bar',
  46. * ],
  47. * 'allow_redirects' => [
  48. * 'max' => 10, // allow at most 10 redirects.
  49. * 'strict' => true, // use "strict" RFC compliant redirects.
  50. * 'referer' => true, // add a Referer header
  51. * 'protocols' => ['https'] // only allow https URLs
  52. * ],
  53. * 'sink' => '/path/to/file', // save to a file or a stream
  54. * 'verify' => true, // bool or string to CA file
  55. * 'debug' => true,
  56. * @return IResponse
  57. * @throws \Exception If the request could not get completed
  58. * @since 8.1.0
  59. */
  60. public function get(string $uri, array $options = []): IResponse;
  61. /**
  62. * Sends a HEAD request
  63. * @param string $uri
  64. * @param array $options Array such as
  65. * 'headers' => [
  66. * 'foo' => 'bar',
  67. * ],
  68. * 'cookies' => [
  69. * 'foo' => 'bar',
  70. * ],
  71. * 'allow_redirects' => [
  72. * 'max' => 10, // allow at most 10 redirects.
  73. * 'strict' => true, // use "strict" RFC compliant redirects.
  74. * 'referer' => true, // add a Referer header
  75. * 'protocols' => ['https'] // only allow https URLs
  76. * ],
  77. * 'sink' => '/path/to/file', // save to a file or a stream
  78. * 'verify' => true, // bool or string to CA file
  79. * 'debug' => true,
  80. * @return IResponse
  81. * @throws \Exception If the request could not get completed
  82. * @since 8.1.0
  83. */
  84. public function head(string $uri, array $options = []): IResponse;
  85. /**
  86. * Sends a POST request
  87. * @param string $uri
  88. * @param array $options Array such as
  89. * 'body' => [
  90. * 'field' => 'abc',
  91. * 'other_field' => '123',
  92. * 'file_name' => fopen('/path/to/file', 'r'),
  93. * ],
  94. * 'headers' => [
  95. * 'foo' => 'bar',
  96. * ],
  97. * 'cookies' => [
  98. * 'foo' => 'bar',
  99. * ],
  100. * 'allow_redirects' => [
  101. * 'max' => 10, // allow at most 10 redirects.
  102. * 'strict' => true, // use "strict" RFC compliant redirects.
  103. * 'referer' => true, // add a Referer header
  104. * 'protocols' => ['https'] // only allow https URLs
  105. * ],
  106. * 'sink' => '/path/to/file', // save to a file or a stream
  107. * 'verify' => true, // bool or string to CA file
  108. * 'debug' => true,
  109. * @return IResponse
  110. * @throws \Exception If the request could not get completed
  111. * @since 8.1.0
  112. */
  113. public function post(string $uri, array $options = []): IResponse;
  114. /**
  115. * Sends a PUT request
  116. * @param string $uri
  117. * @param array $options Array such as
  118. * 'body' => [
  119. * 'field' => 'abc',
  120. * 'other_field' => '123',
  121. * 'file_name' => fopen('/path/to/file', 'r'),
  122. * ],
  123. * 'headers' => [
  124. * 'foo' => 'bar',
  125. * ],
  126. * 'cookies' => [
  127. * 'foo' => 'bar',
  128. * ],
  129. * 'allow_redirects' => [
  130. * 'max' => 10, // allow at most 10 redirects.
  131. * 'strict' => true, // use "strict" RFC compliant redirects.
  132. * 'referer' => true, // add a Referer header
  133. * 'protocols' => ['https'] // only allow https URLs
  134. * ],
  135. * 'sink' => '/path/to/file', // save to a file or a stream
  136. * 'verify' => true, // bool or string to CA file
  137. * 'debug' => true,
  138. * @return IResponse
  139. * @throws \Exception If the request could not get completed
  140. * @since 8.1.0
  141. */
  142. public function put(string $uri, array $options = []): IResponse;
  143. /**
  144. * Sends a DELETE request
  145. * @param string $uri
  146. * @param array $options Array such as
  147. * 'body' => [
  148. * 'field' => 'abc',
  149. * 'other_field' => '123',
  150. * 'file_name' => fopen('/path/to/file', 'r'),
  151. * ],
  152. * 'headers' => [
  153. * 'foo' => 'bar',
  154. * ],
  155. * 'cookies' => [
  156. * 'foo' => 'bar',
  157. * ],
  158. * 'allow_redirects' => [
  159. * 'max' => 10, // allow at most 10 redirects.
  160. * 'strict' => true, // use "strict" RFC compliant redirects.
  161. * 'referer' => true, // add a Referer header
  162. * 'protocols' => ['https'] // only allow https URLs
  163. * ],
  164. * 'sink' => '/path/to/file', // save to a file or a stream
  165. * 'verify' => true, // bool or string to CA file
  166. * 'debug' => true,
  167. * @return IResponse
  168. * @throws \Exception If the request could not get completed
  169. * @since 8.1.0
  170. */
  171. public function delete(string $uri, array $options = []): IResponse;
  172. /**
  173. * Sends an OPTIONS request
  174. * @param string $uri
  175. * @param array $options Array such as
  176. * 'body' => [
  177. * 'field' => 'abc',
  178. * 'other_field' => '123',
  179. * 'file_name' => fopen('/path/to/file', 'r'),
  180. * ],
  181. * 'headers' => [
  182. * 'foo' => 'bar',
  183. * ],
  184. * 'cookies' => [
  185. * 'foo' => 'bar',
  186. * ],
  187. * 'allow_redirects' => [
  188. * 'max' => 10, // allow at most 10 redirects.
  189. * 'strict' => true, // use "strict" RFC compliant redirects.
  190. * 'referer' => true, // add a Referer header
  191. * 'protocols' => ['https'] // only allow https URLs
  192. * ],
  193. * 'sink' => '/path/to/file', // save to a file or a stream
  194. * 'verify' => true, // bool or string to CA file
  195. * 'debug' => true,
  196. * @return IResponse
  197. * @throws \Exception If the request could not get completed
  198. * @since 8.1.0
  199. */
  200. public function options(string $uri, array $options = []): IResponse;
  201. /**
  202. * Sends an asynchronous GET request
  203. * @param string $uri
  204. * @param array $options Array such as
  205. * 'query' => [
  206. * 'field' => 'abc',
  207. * 'other_field' => '123',
  208. * 'file_name' => fopen('/path/to/file', 'r'),
  209. * ],
  210. * 'headers' => [
  211. * 'foo' => 'bar',
  212. * ],
  213. * 'cookies' => [
  214. * 'foo' => 'bar',
  215. * ],
  216. * 'allow_redirects' => [
  217. * 'max' => 10, // allow at most 10 redirects.
  218. * 'strict' => true, // use "strict" RFC compliant redirects.
  219. * 'referer' => true, // add a Referer header
  220. * 'protocols' => ['https'] // only allow https URLs
  221. * ],
  222. * 'sink' => '/path/to/file', // save to a file or a stream
  223. * 'verify' => true, // bool or string to CA file
  224. * 'debug' => true,
  225. * @return IPromise
  226. * @since 28.0.0
  227. */
  228. public function getAsync(string $uri, array $options = []): IPromise;
  229. /**
  230. * Sends an asynchronous HEAD request
  231. * @param string $uri
  232. * @param array $options Array such as
  233. * 'headers' => [
  234. * 'foo' => 'bar',
  235. * ],
  236. * 'cookies' => [
  237. * 'foo' => 'bar',
  238. * ],
  239. * 'allow_redirects' => [
  240. * 'max' => 10, // allow at most 10 redirects.
  241. * 'strict' => true, // use "strict" RFC compliant redirects.
  242. * 'referer' => true, // add a Referer header
  243. * 'protocols' => ['https'] // only allow https URLs
  244. * ],
  245. * 'sink' => '/path/to/file', // save to a file or a stream
  246. * 'verify' => true, // bool or string to CA file
  247. * 'debug' => true,
  248. * @return IPromise
  249. * @since 28.0.0
  250. */
  251. public function headAsync(string $uri, array $options = []): IPromise;
  252. /**
  253. * Sends an asynchronous POST request
  254. * @param string $uri
  255. * @param array $options Array such as
  256. * 'body' => [
  257. * 'field' => 'abc',
  258. * 'other_field' => '123',
  259. * 'file_name' => fopen('/path/to/file', 'r'),
  260. * ],
  261. * 'headers' => [
  262. * 'foo' => 'bar',
  263. * ],
  264. * 'cookies' => [
  265. * 'foo' => 'bar',
  266. * ],
  267. * 'allow_redirects' => [
  268. * 'max' => 10, // allow at most 10 redirects.
  269. * 'strict' => true, // use "strict" RFC compliant redirects.
  270. * 'referer' => true, // add a Referer header
  271. * 'protocols' => ['https'] // only allow https URLs
  272. * ],
  273. * 'sink' => '/path/to/file', // save to a file or a stream
  274. * 'verify' => true, // bool or string to CA file
  275. * 'debug' => true,
  276. * @return IPromise
  277. * @since 28.0.0
  278. */
  279. public function postAsync(string $uri, array $options = []): IPromise;
  280. /**
  281. * Sends an asynchronous PUT request
  282. * @param string $uri
  283. * @param array $options Array such as
  284. * 'body' => [
  285. * 'field' => 'abc',
  286. * 'other_field' => '123',
  287. * 'file_name' => fopen('/path/to/file', 'r'),
  288. * ],
  289. * 'headers' => [
  290. * 'foo' => 'bar',
  291. * ],
  292. * 'cookies' => [
  293. * 'foo' => 'bar',
  294. * ],
  295. * 'allow_redirects' => [
  296. * 'max' => 10, // allow at most 10 redirects.
  297. * 'strict' => true, // use "strict" RFC compliant redirects.
  298. * 'referer' => true, // add a Referer header
  299. * 'protocols' => ['https'] // only allow https URLs
  300. * ],
  301. * 'sink' => '/path/to/file', // save to a file or a stream
  302. * 'verify' => true, // bool or string to CA file
  303. * 'debug' => true,
  304. * @return IPromise
  305. * @since 28.0.0
  306. */
  307. public function putAsync(string $uri, array $options = []): IPromise;
  308. /**
  309. * Sends an asynchronous DELETE request
  310. * @param string $uri
  311. * @param array $options Array such as
  312. * 'body' => [
  313. * 'field' => 'abc',
  314. * 'other_field' => '123',
  315. * 'file_name' => fopen('/path/to/file', 'r'),
  316. * ],
  317. * 'headers' => [
  318. * 'foo' => 'bar',
  319. * ],
  320. * 'cookies' => [
  321. * 'foo' => 'bar',
  322. * ],
  323. * 'allow_redirects' => [
  324. * 'max' => 10, // allow at most 10 redirects.
  325. * 'strict' => true, // use "strict" RFC compliant redirects.
  326. * 'referer' => true, // add a Referer header
  327. * 'protocols' => ['https'] // only allow https URLs
  328. * ],
  329. * 'sink' => '/path/to/file', // save to a file or a stream
  330. * 'verify' => true, // bool or string to CA file
  331. * 'debug' => true,
  332. * @return IPromise
  333. * @since 28.0.0
  334. */
  335. public function deleteAsync(string $uri, array $options = []): IPromise;
  336. /**
  337. * Sends an asynchronous OPTIONS request
  338. * @param string $uri
  339. * @param array $options Array such as
  340. * 'body' => [
  341. * 'field' => 'abc',
  342. * 'other_field' => '123',
  343. * 'file_name' => fopen('/path/to/file', 'r'),
  344. * ],
  345. * 'headers' => [
  346. * 'foo' => 'bar',
  347. * ],
  348. * 'cookies' => [
  349. * 'foo' => 'bar',
  350. * ],
  351. * 'allow_redirects' => [
  352. * 'max' => 10, // allow at most 10 redirects.
  353. * 'strict' => true, // use "strict" RFC compliant redirects.
  354. * 'referer' => true, // add a Referer header
  355. * 'protocols' => ['https'] // only allow https URLs
  356. * ],
  357. * 'sink' => '/path/to/file', // save to a file or a stream
  358. * 'verify' => true, // bool or string to CA file
  359. * 'debug' => true,
  360. * @return IPromise
  361. * @since 28.0.0
  362. */
  363. public function optionsAsync(string $uri, array $options = []): IPromise;
  364. }