[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  // SPDX-FileCopyrightText: 2004-2023 Ryan Parman, Sam Sneddon, Ryan McCue
   4  // SPDX-FileCopyrightText: 2014 PHP Framework Interoperability Group
   5  // SPDX-License-Identifier: MIT
   6  
   7  declare(strict_types=1);
   8  
   9  namespace SimplePie\HTTP;
  10  
  11  /**
  12   * HTTP Response interface
  13   *
  14   * This interface must be interoperable with Psr\Http\Message\ResponseInterface
  15   * @see https://www.php-fig.org/psr/psr-7/#33-psrhttpmessageresponseinterface
  16   *
  17   * @internal
  18   */
  19  interface Response
  20  {
  21      /**
  22       * Return the string representation of the permanent URI of the requested resource
  23       * (the first location after a prefix of (only) permanent redirects).
  24       *
  25       * Depending on which components of the URI are present, the resulting
  26       * string is either a full URI or relative reference according to RFC 3986,
  27       * Section 4.1. The method concatenates the various components of the URI,
  28       * using the appropriate delimiters:
  29       *
  30       * - If a scheme is present, it MUST be suffixed by ":".
  31       * - If an authority is present, it MUST be prefixed by "//".
  32       * - The path can be concatenated without delimiters. But there are two
  33       *   cases where the path has to be adjusted to make the URI reference
  34       *   valid as PHP does not allow to throw an exception in __toString():
  35       *     - If the path is rootless and an authority is present, the path MUST
  36       *       be prefixed by "/".
  37       *     - If the path is starting with more than one "/" and no authority is
  38       *       present, the starting slashes MUST be reduced to one.
  39       * - If a query is present, it MUST be prefixed by "?".
  40       * - If a fragment is present, it MUST be prefixed by "#".
  41       *
  42       * @see http://tools.ietf.org/html/rfc3986#section-4.1
  43       */
  44      public function get_permanent_uri(): string;
  45  
  46      /**
  47       * Return the string representation of the final requested URL after following all redirects.
  48       *
  49       * Depending on which components of the URI are present, the resulting
  50       * string is either a full URI or relative reference according to RFC 3986,
  51       * Section 4.1. The method concatenates the various components of the URI,
  52       * using the appropriate delimiters:
  53       *
  54       * - If a scheme is present, it MUST be suffixed by ":".
  55       * - If an authority is present, it MUST be prefixed by "//".
  56       * - The path can be concatenated without delimiters. But there are two
  57       *   cases where the path has to be adjusted to make the URI reference
  58       *   valid as PHP does not allow to throw an exception in __toString():
  59       *     - If the path is rootless and an authority is present, the path MUST
  60       *       be prefixed by "/".
  61       *     - If the path is starting with more than one "/" and no authority is
  62       *       present, the starting slashes MUST be reduced to one.
  63       * - If a query is present, it MUST be prefixed by "?".
  64       * - If a fragment is present, it MUST be prefixed by "#".
  65       *
  66       * @see http://tools.ietf.org/html/rfc3986#section-4.1
  67       */
  68      public function get_final_requested_uri(): string;
  69  
  70      /**
  71       * Gets the response status code.
  72       *
  73       * The status code is a 3-digit integer result code of the server's attempt
  74       * to understand and satisfy the request.
  75       *
  76       * @return int Status code.
  77       */
  78      public function get_status_code(): int;
  79  
  80      /**
  81       * Retrieves all message header values.
  82       *
  83       * The keys represent the header name as it will be sent over the wire, and
  84       * each value is an array of strings associated with the header.
  85       *
  86       *     // Represent the headers as a string
  87       *     foreach ($message->get_headers() as $name => $values) {
  88       *         echo $name . ': ' . implode(', ', $values);
  89       *     }
  90       *
  91       *     // Emit headers iteratively:
  92       *     foreach ($message->get_headers() as $name => $values) {
  93       *         foreach ($values as $value) {
  94       *             header(sprintf('%s: %s', $name, $value), false);
  95       *         }
  96       *     }
  97       *
  98       * @return array<non-empty-array<string>> Returns an associative array of the message's headers.
  99       *     Each key MUST be a header name, and each value MUST be an array of
 100       *     strings for that header.
 101       */
 102      public function get_headers(): array;
 103  
 104      /**
 105       * Checks if a header exists by the given case-insensitive name.
 106       *
 107       * @param string $name Case-insensitive header field name.
 108       * @return bool Returns true if any header names match the given header
 109       *     name using a case-insensitive string comparison. Returns false if
 110       *     no matching header name is found in the message.
 111       */
 112      public function has_header(string $name): bool;
 113  
 114      /**
 115       * Retrieves a message header value by the given case-insensitive name.
 116       *
 117       * This method returns an array of all the header values of the given
 118       * case-insensitive header name.
 119       *
 120       * If the header does not appear in the message, this method MUST return an
 121       * empty array.
 122       *
 123       * @param string $name Case-insensitive header field name.
 124       * @return string[] An array of string values as provided for the given
 125       *    header. If the header does not appear in the message, this method MUST
 126       *    return an empty array.
 127       */
 128      public function get_header(string $name): array;
 129  
 130      /**
 131       * Return an instance with the provided value replacing the specified header.
 132       *
 133       * This method MUST be implemented in such a way as to retain the
 134       * immutability of the message, and MUST return an instance that has the
 135       * new and/or updated header and value.
 136       *
 137       * @param string $name Case-insensitive header field name.
 138       * @param string|non-empty-array<string> $value Header value(s).
 139       * @return static
 140       * @throws \InvalidArgumentException for invalid header names or values.
 141       */
 142      public function with_header(string $name, $value);
 143  
 144      /**
 145       * Retrieves a comma-separated string of the values for a single header.
 146       *
 147       * This method returns all of the header values of the given
 148       * case-insensitive header name as a string concatenated together using
 149       * a comma.
 150       *
 151       * NOTE: Not all header values may be appropriately represented using
 152       * comma concatenation. For such headers, use getHeader() instead
 153       * and supply your own delimiter when concatenating.
 154       *
 155       * If the header does not appear in the message, this method MUST return
 156       * an empty string.
 157       *
 158       * @param string $name Case-insensitive header field name.
 159       * @return string A string of values as provided for the given header
 160       *    concatenated together using a comma. If the header does not appear in
 161       *    the message, this method MUST return an empty string.
 162       */
 163      public function get_header_line(string $name): string;
 164  
 165      /**
 166       * get the body as string
 167       *
 168       * @return string
 169       */
 170      public function get_body_content(): string;
 171  }