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}
188