[Summary view]

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