[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  namespace WordPress\AiClientDependencies\Psr\Http\Message;
   4  
   5  /**
   6   * HTTP messages consist of requests from a client to a server and responses
   7   * from a server to a client. This interface defines the methods common to
   8   * each.
   9   *
  10   * Messages are considered immutable; all methods that might change state MUST
  11   * be implemented such that they retain the internal state of the current
  12   * message and return an instance that contains the changed state.
  13   *
  14   * @link http://www.ietf.org/rfc/rfc7230.txt
  15   * @link http://www.ietf.org/rfc/rfc7231.txt
  16   */
  17  interface MessageInterface
  18  {
  19      /**
  20       * Retrieves the HTTP protocol version as a string.
  21       *
  22       * The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
  23       *
  24       * @return string HTTP protocol version.
  25       */
  26      public function getProtocolVersion(): string;
  27      /**
  28       * Return an instance with the specified HTTP protocol version.
  29       *
  30       * The version string MUST contain only the HTTP version number (e.g.,
  31       * "1.1", "1.0").
  32       *
  33       * This method MUST be implemented in such a way as to retain the
  34       * immutability of the message, and MUST return an instance that has the
  35       * new protocol version.
  36       *
  37       * @param string $version HTTP protocol version
  38       * @return static
  39       */
  40      public function withProtocolVersion(string $version): MessageInterface;
  41      /**
  42       * Retrieves all message header values.
  43       *
  44       * The keys represent the header name as it will be sent over the wire, and
  45       * each value is an array of strings associated with the header.
  46       *
  47       *     // Represent the headers as a string
  48       *     foreach ($message->getHeaders() as $name => $values) {
  49       *         echo $name . ": " . implode(", ", $values);
  50       *     }
  51       *
  52       *     // Emit headers iteratively:
  53       *     foreach ($message->getHeaders() as $name => $values) {
  54       *         foreach ($values as $value) {
  55       *             header(sprintf('%s: %s', $name, $value), false);
  56       *         }
  57       *     }
  58       *
  59       * While header names are not case-sensitive, getHeaders() will preserve the
  60       * exact case in which headers were originally specified.
  61       *
  62       * @return string[][] Returns an associative array of the message's headers. Each
  63       *     key MUST be a header name, and each value MUST be an array of strings
  64       *     for that header.
  65       */
  66      public function getHeaders(): array;
  67      /**
  68       * Checks if a header exists by the given case-insensitive name.
  69       *
  70       * @param string $name Case-insensitive header field name.
  71       * @return bool Returns true if any header names match the given header
  72       *     name using a case-insensitive string comparison. Returns false if
  73       *     no matching header name is found in the message.
  74       */
  75      public function hasHeader(string $name): bool;
  76      /**
  77       * Retrieves a message header value by the given case-insensitive name.
  78       *
  79       * This method returns an array of all the header values of the given
  80       * case-insensitive header name.
  81       *
  82       * If the header does not appear in the message, this method MUST return an
  83       * empty array.
  84       *
  85       * @param string $name Case-insensitive header field name.
  86       * @return string[] An array of string values as provided for the given
  87       *    header. If the header does not appear in the message, this method MUST
  88       *    return an empty array.
  89       */
  90      public function getHeader(string $name): array;
  91      /**
  92       * Retrieves a comma-separated string of the values for a single header.
  93       *
  94       * This method returns all of the header values of the given
  95       * case-insensitive header name as a string concatenated together using
  96       * a comma.
  97       *
  98       * NOTE: Not all header values may be appropriately represented using
  99       * comma concatenation. For such headers, use getHeader() instead
 100       * and supply your own delimiter when concatenating.
 101       *
 102       * If the header does not appear in the message, this method MUST return
 103       * an empty string.
 104       *
 105       * @param string $name Case-insensitive header field name.
 106       * @return string A string of values as provided for the given header
 107       *    concatenated together using a comma. If the header does not appear in
 108       *    the message, this method MUST return an empty string.
 109       */
 110      public function getHeaderLine(string $name): string;
 111      /**
 112       * Return an instance with the provided value replacing the specified header.
 113       *
 114       * While header names are case-insensitive, the casing of the header will
 115       * be preserved by this function, and returned from getHeaders().
 116       *
 117       * This method MUST be implemented in such a way as to retain the
 118       * immutability of the message, and MUST return an instance that has the
 119       * new and/or updated header and value.
 120       *
 121       * @param string $name Case-insensitive header field name.
 122       * @param string|string[] $value Header value(s).
 123       * @return static
 124       * @throws \InvalidArgumentException for invalid header names or values.
 125       */
 126      public function withHeader(string $name, $value): MessageInterface;
 127      /**
 128       * Return an instance with the specified header appended with the given value.
 129       *
 130       * Existing values for the specified header will be maintained. The new
 131       * value(s) will be appended to the existing list. If the header did not
 132       * exist previously, it will be added.
 133       *
 134       * This method MUST be implemented in such a way as to retain the
 135       * immutability of the message, and MUST return an instance that has the
 136       * new header and/or value.
 137       *
 138       * @param string $name Case-insensitive header field name to add.
 139       * @param string|string[] $value Header value(s).
 140       * @return static
 141       * @throws \InvalidArgumentException for invalid header names or values.
 142       */
 143      public function withAddedHeader(string $name, $value): MessageInterface;
 144      /**
 145       * Return an instance without the specified header.
 146       *
 147       * Header resolution MUST be done without case-sensitivity.
 148       *
 149       * This method MUST be implemented in such a way as to retain the
 150       * immutability of the message, and MUST return an instance that removes
 151       * the named header.
 152       *
 153       * @param string $name Case-insensitive header field name to remove.
 154       * @return static
 155       */
 156      public function withoutHeader(string $name): MessageInterface;
 157      /**
 158       * Gets the body of the message.
 159       *
 160       * @return StreamInterface Returns the body as a stream.
 161       */
 162      public function getBody(): StreamInterface;
 163      /**
 164       * Return an instance with the specified message body.
 165       *
 166       * The body MUST be a StreamInterface object.
 167       *
 168       * This method MUST be implemented in such a way as to retain the
 169       * immutability of the message, and MUST return a new instance that has the
 170       * new body stream.
 171       *
 172       * @param StreamInterface $body Body.
 173       * @return static
 174       * @throws \InvalidArgumentException When the body is not valid.
 175       */
 176      public function withBody(StreamInterface $body): MessageInterface;
 177  }