vendor/psr/http-message/src/MessageInterface.php

   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 }