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