ResponseInterface.php 4.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109
  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\ClientExceptionInterface;
  12. use Symfony\Contracts\HttpClient\Exception\DecodingExceptionInterface;
  13. use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;
  14. use Symfony\Contracts\HttpClient\Exception\RedirectionExceptionInterface;
  15. use Symfony\Contracts\HttpClient\Exception\ServerExceptionInterface;
  16. use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
  17. /**
  18. * A (lazily retrieved) HTTP response.
  19. *
  20. * @author Nicolas Grekas <p@tchwork.com>
  21. */
  22. interface ResponseInterface
  23. {
  24. /**
  25. * Gets the HTTP status code of the response.
  26. *
  27. * @throws TransportExceptionInterface when a network error occurs
  28. */
  29. public function getStatusCode(): int;
  30. /**
  31. * Gets the HTTP headers of the response.
  32. *
  33. * @param bool $throw Whether an exception should be thrown on 3/4/5xx status codes
  34. *
  35. * @return string[][] The headers of the response keyed by header names in lowercase
  36. *
  37. * @throws TransportExceptionInterface When a network error occurs
  38. * @throws RedirectionExceptionInterface On a 3xx when $throw is true and the "max_redirects" option has been reached
  39. * @throws ClientExceptionInterface On a 4xx when $throw is true
  40. * @throws ServerExceptionInterface On a 5xx when $throw is true
  41. */
  42. public function getHeaders(bool $throw = true): array;
  43. /**
  44. * Gets the response body as a string.
  45. *
  46. * @param bool $throw Whether an exception should be thrown on 3/4/5xx status codes
  47. *
  48. * @throws TransportExceptionInterface When a network error occurs
  49. * @throws RedirectionExceptionInterface On a 3xx when $throw is true and the "max_redirects" option has been reached
  50. * @throws ClientExceptionInterface On a 4xx when $throw is true
  51. * @throws ServerExceptionInterface On a 5xx when $throw is true
  52. */
  53. public function getContent(bool $throw = true): string;
  54. /**
  55. * Gets the response body decoded as array, typically from a JSON payload.
  56. *
  57. * @param bool $throw Whether an exception should be thrown on 3/4/5xx status codes
  58. *
  59. * @throws DecodingExceptionInterface When the body cannot be decoded to an array
  60. * @throws TransportExceptionInterface When a network error occurs
  61. * @throws RedirectionExceptionInterface On a 3xx when $throw is true and the "max_redirects" option has been reached
  62. * @throws ClientExceptionInterface On a 4xx when $throw is true
  63. * @throws ServerExceptionInterface On a 5xx when $throw is true
  64. */
  65. public function toArray(bool $throw = true): array;
  66. /**
  67. * Closes the response stream and all related buffers.
  68. *
  69. * No further chunk will be yielded after this method has been called.
  70. */
  71. public function cancel(): void;
  72. /**
  73. * Returns info coming from the transport layer.
  74. *
  75. * This method SHOULD NOT throw any ExceptionInterface and SHOULD be non-blocking.
  76. * The returned info is "live": it can be empty and can change from one call to
  77. * another, as the request/response progresses.
  78. *
  79. * The following info MUST be returned:
  80. * - canceled (bool) - true if the response was canceled using ResponseInterface::cancel(), false otherwise
  81. * - error (string|null) - the error message when the transfer was aborted, null otherwise
  82. * - http_code (int) - the last response code or 0 when it is not known yet
  83. * - http_method (string) - the HTTP verb of the last request
  84. * - redirect_count (int) - the number of redirects followed while executing the request
  85. * - redirect_url (string|null) - the resolved location of redirect responses, null otherwise
  86. * - response_headers (array) - an array modelled after the special $http_response_header variable
  87. * - start_time (float) - the time when the request was sent or 0.0 when it's pending
  88. * - url (string) - the last effective URL of the request
  89. * - user_data (mixed) - the value of the "user_data" request option, null if not set
  90. *
  91. * When the "capture_peer_cert_chain" option is true, the "peer_certificate_chain"
  92. * attribute SHOULD list the peer certificates as an array of OpenSSL X.509 resources.
  93. *
  94. * Other info SHOULD be named after curl_getinfo()'s associative return value.
  95. *
  96. * @return mixed An array of all available info, or one of them when $type is
  97. * provided, or null when an unsupported type is requested
  98. */
  99. public function getInfo(string $type = null);
  100. }