[Summary view] [Print] [Text view]

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