krz/vox-populi

  1<?php
  2
  3namespace 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 */
 17interface 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}