HttpClientInterface.php 5.6 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495
  1. <?php
  2. /*
  3. * This file is part of the Symfony package.
  4. *
  5. * (c) Fabien Potencier <fabien@symfony.com>
  6. *
  7. * For the full copyright and license information, please view the LICENSE
  8. * file that was distributed with this source code.
  9. */
  10. namespace Symfony\Contracts\HttpClient;
  11. use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
  12. use Symfony\Contracts\HttpClient\Test\HttpClientTestCase;
  13. /**
  14. * Provides flexible methods for requesting HTTP resources synchronously or asynchronously.
  15. *
  16. * @see HttpClientTestCase for a reference test suite
  17. *
  18. * @author Nicolas Grekas <p@tchwork.com>
  19. *
  20. * @experimental in 1.1
  21. */
  22. interface HttpClientInterface
  23. {
  24. public const OPTIONS_DEFAULTS = [
  25. 'auth_basic' => null, // array|string - an array containing the username as first value, and optionally the
  26. // password as the second one; or string like username:password - enabling HTTP Basic
  27. // authentication (RFC 7617)
  28. 'auth_bearer' => null, // string - a token enabling HTTP Bearer authorization (RFC 6750)
  29. 'query' => [], // string[] - associative array of query string values to merge with the request's URL
  30. 'headers' => [], // iterable|string[]|string[][] - headers names provided as keys or as part of values
  31. 'body' => '', // array|string|resource|\Traversable|\Closure - the callback SHOULD yield a string
  32. // smaller than the amount requested as argument; the empty string signals EOF; if
  33. // an array is passed, it is meant as a form payload of field names and values
  34. 'json' => null, // mixed - if set, implementations MUST set the "body" option to the JSON-encoded
  35. // value and set the "content-type" header to a JSON-compatible value if it is not
  36. // explicitly defined in the headers option - typically "application/json"
  37. 'user_data' => null, // mixed - any extra data to attach to the request (scalar, callable, object...) that
  38. // MUST be available via $response->getInfo('user_data') - not used internally
  39. 'max_redirects' => 20, // int - the maximum number of redirects to follow; a value lower than or equal to 0
  40. // means redirects should not be followed; "Authorization" and "Cookie" headers MUST
  41. // NOT follow except for the initial host name
  42. 'http_version' => null, // string - defaults to the best supported version, typically 1.1 or 2.0
  43. 'base_uri' => null, // string - the URI to resolve relative URLs, following rules in RFC 3986, section 2
  44. 'buffer' => true, // bool|resource|\Closure - whether the content of the response should be buffered or not,
  45. // or a stream resource where the response body should be written,
  46. // or a closure telling if/where the response should be buffered based on its headers
  47. 'on_progress' => null, // callable(int $dlNow, int $dlSize, array $info) - throwing any exceptions MUST abort
  48. // the request; it MUST be called on DNS resolution, on arrival of headers and on
  49. // completion; it SHOULD be called on upload/download of data and at least 1/s
  50. 'resolve' => [], // string[] - a map of host to IP address that SHOULD replace DNS resolution
  51. 'proxy' => null, // string - by default, the proxy-related env vars handled by curl SHOULD be honored
  52. 'no_proxy' => null, // string - a comma separated list of hosts that do not require a proxy to be reached
  53. 'timeout' => null, // float - the idle timeout - defaults to ini_get('default_socket_timeout')
  54. 'max_duration' => 0, // float - the maximum execution time for the request+response as a whole;
  55. // a value lower than or equal to 0 means it is unlimited
  56. 'bindto' => '0', // string - the interface or the local socket to bind to
  57. 'verify_peer' => true, // see https://php.net/context.ssl for the following options
  58. 'verify_host' => true,
  59. 'cafile' => null,
  60. 'capath' => null,
  61. 'local_cert' => null,
  62. 'local_pk' => null,
  63. 'passphrase' => null,
  64. 'ciphers' => null,
  65. 'peer_fingerprint' => null,
  66. 'capture_peer_cert_chain' => false,
  67. 'extra' => [], // array - additional options that can be ignored if unsupported, unlike regular options
  68. ];
  69. /**
  70. * Requests an HTTP resource.
  71. *
  72. * Responses MUST be lazy, but their status code MUST be
  73. * checked even if none of their public methods are called.
  74. *
  75. * Implementations are not required to support all options described above; they can also
  76. * support more custom options; but in any case, they MUST throw a TransportExceptionInterface
  77. * when an unsupported option is passed.
  78. *
  79. * @throws TransportExceptionInterface When an unsupported option is passed
  80. */
  81. public function request(string $method, string $url, array $options = []): ResponseInterface;
  82. /**
  83. * Yields responses chunk by chunk as they complete.
  84. *
  85. * @param ResponseInterface|ResponseInterface[]|iterable $responses One or more responses created by the current HTTP client
  86. * @param float|null $timeout The idle timeout before yielding timeout chunks
  87. */
  88. public function stream($responses, float $timeout = null): ResponseStreamInterface;
  89. }