vendor/symfony/http-client-contracts/HttpClientInterface.php line 93

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