1	<?php
2
3	/**
4	* Copyright (c) 2019 Wikimedia Foundation.
5	*
6	* This file is partly derived from PSR-7, which requires the following copyright notice:
7	*
8	* Copyright (c) 2014 PHP Framework Interoperability Group
9	*
10	* Permission is hereby granted, free of charge, to any person obtaining a copy
11	* of this software and associated documentation files (the "Software"), to deal
12	* in the Software without restriction, including without limitation the rights
13	* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14	* copies of the Software, and to permit persons to whom the Software is
15	* furnished to do so, subject to the following conditions:
16	*
17	* The above copyright notice and this permission notice shall be included in
18	* all copies or substantial portions of the Software.
19	*
20	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21	* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22	* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23	* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24	* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25	* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
26	* THE SOFTWARE.
27	*
28	* @file
29	*/
30
31	namespace MediaWiki\Rest;
32
33	use Psr\Http\Message\StreamInterface;
34
35	/**
36	* An interface similar to PSR-7's ResponseInterface, the primary difference
37	* being that it is mutable.
38	*
39	* @stable to implement
40	*/
41	interface ResponseInterface {
42	// ResponseInterface
43
44	/**
45	* Gets the response status code.
46	*
47	* The status code is a 3-digit integer result code of the server's attempt
48	* to understand and satisfy the request.
49	*
50	* @return int Status code.
51	*/
52	public function getStatusCode(): int;
53
54	/**
55	* Gets the response reason phrase associated with the status code.
56	*
57	* Because a reason phrase is not a required element in a response
58	* status line, the reason phrase value MAY be empty. Implementations MAY
59	* choose to return the default RFC 7231 recommended reason phrase (or those
60	* listed in the IANA HTTP Status Code Registry) for the response's
61	* status code.
62	*
63	* @see http://tools.ietf.org/html/rfc7231#section-6
64	* @see http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
65	* @return string Reason phrase; must return an empty string if none present.
66	*/
67	public function getReasonPhrase(): string;
68
69	// ResponseInterface mutation
70
71	/**
72	* Set the status code and, optionally, reason phrase.
73	*
74	* If no reason phrase is specified, implementations MAY choose to default
75	* to the RFC 7231 or IANA recommended reason phrase for the response's
76	* status code.
77	*
78	* @see http://tools.ietf.org/html/rfc7231#section-6
79	* @see http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
80	* @param int $code The 3-digit integer result code to set.
81	* @param string $reasonPhrase The reason phrase to use with the
82	*     provided status code; if none is provided, implementations MAY
83	*     use the defaults as suggested in the HTTP specification.
84	* @throws \InvalidArgumentException For invalid status code arguments.
85	*/
86	public function setStatus( $code, $reasonPhrase = '' );
87
88	// MessageInterface
89
90	/**
91	* Retrieves the HTTP protocol version as a string.
92	*
93	* The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
94	*
95	* @return string HTTP protocol version.
96	*/
97	public function getProtocolVersion(): string;
98
99	/**
100	* Retrieves all message header values.
101	*
102	* The keys represent the header name as it will be sent over the wire, and
103	* each value is an array of strings associated with the header.
104	*
105	*     // Represent the headers as a string
106	*     foreach ($message->getHeaders() as $name => $values) {
107	*         echo $name . ': ' . implode(', ', $values);
108	*     }
109	*
110	*     // Emit headers iteratively:
111	*     foreach ($message->getHeaders() as $name => $values) {
112	*         foreach ($values as $value) {
113	*             header(sprintf('%s: %s', $name, $value), false);
114	*         }
115	*     }
116	*
117	* While header names are not case-sensitive, getHeaders() will preserve the
118	* exact case in which headers were originally specified.
119	*
120	* @return string[][] Returns an associative array of the message's headers.
121	*     Each key MUST be a header name, and each value MUST be an array of
122	*     strings for that header.
123	*/
124	public function getHeaders(): array;
125
126	/**
127	* Checks if a header exists by the given case-insensitive name.
128	*
129	* @param string $name Case-insensitive header field name.
130	* @return bool Returns true if any header names match the given header
131	*     name using a case-insensitive string comparison. Returns false if
132	*     no matching header name is found in the message.
133	*/
134	public function hasHeader( string $name ): bool;
135
136	/**
137	* Retrieves a message header value by the given case-insensitive name.
138	*
139	* This method returns an array of all the header values of the given
140	* case-insensitive header name.
141	*
142	* If the header does not appear in the message, this method MUST return an
143	* empty array.
144	*
145	* @param string $name Case-insensitive header field name.
146	* @return string[] An array of string values as provided for the given
147	*    header. If the header does not appear in the message, this method MUST
148	*    return an empty array.
149	*/
150	public function getHeader( string $name ): array;
151
152	/**
153	* Retrieves a comma-separated string of the values for a single header.
154	*
155	* This method returns all of the header values of the given
156	* case-insensitive header name as a string concatenated together using
157	* a comma.
158	*
159	* NOTE: Not all header values may be appropriately represented using
160	* comma concatenation. For such headers, use getHeader() instead
161	* and supply your own delimiter when concatenating.
162	*
163	* If the header does not appear in the message, this method MUST return
164	* an empty string.
165	*
166	* @param string $name Case-insensitive header field name.
167	* @return string A string of values as provided for the given header
168	*    concatenated together using a comma. If the header does not appear in
169	*    the message, this method MUST return an empty string.
170	*/
171	public function getHeaderLine( string $name ): string;
172
173	/**
174	* Gets the body of the message.
175	*
176	* @return StreamInterface Returns the body as a stream.
177	*/
178	public function getBody();
179
180	// MessageInterface mutation
181
182	/**
183	* Set the HTTP protocol version.
184	*
185	* The version string MUST contain only the HTTP version number (e.g.,
186	* "1.1", "1.0").
187	*
188	* @param string $version HTTP protocol version
189	*/
190	public function setProtocolVersion( $version );
191
192	/**
193	* Set or replace the specified header.
194	*
195	* While header names are case-insensitive, the casing of the header will
196	* be preserved by this function, and returned from getHeaders().
197	*
198	* @param string $name Case-insensitive header field name.
199	* @param string|string[] $value Header value(s).
200	* @throws \InvalidArgumentException for invalid header names or values.
201	*/
202	public function setHeader( $name, $value );
203
204	/**
205	* Append the given value to the specified header.
206	*
207	* Existing values for the specified header will be maintained. The new
208	* value(s) will be appended to the existing list. If the header did not
209	* exist previously, it will be added.
210	*
211	* @param string $name Case-insensitive header field name to add.
212	* @param string|string[] $value Header value(s).
213	* @throws \InvalidArgumentException for invalid header names.
214	* @throws \InvalidArgumentException for invalid header values.
215	*/
216	public function addHeader( $name, $value );
217
218	/**
219	* Remove the specified header.
220	*
221	* Header resolution MUST be done without case-sensitivity.
222	*
223	* @param string $name Case-insensitive header field name to remove.
224	*/
225	public function removeHeader( $name );
226
227	/**
228	* Set the message body
229	*
230	* The body MUST be a StreamInterface object.
231	*
232	* @param StreamInterface $body
233	* @throws \InvalidArgumentException When the body is not valid.
234	*/
235	public function setBody( StreamInterface $body );
236
237	// MediaWiki extensions to PSR-7
238
239	/**
240	* Get the full header lines including colon-separated name and value, for
241	* passing directly to header(). Not including the status line.
242	*
243	* @return string[]
244	*/
245	public function getRawHeaderLines();
246
247	/**
248	* Set a cookie
249	*
250	* The name will have the cookie prefix added to it before it is sent over
251	* the network.
252	*
253	* @param string $name The name of the cookie, not including prefix.
254	* @param string $value The value to be stored in the cookie.
255	* @param int|null $expire Unix timestamp (in seconds) when the cookie should expire.
256	*        0 (the default) causes it to expire $wgCookieExpiration seconds from now.
257	*        null causes it to be a session cookie.
258	* @param array $options Assoc of additional cookie options:
259	*     prefix: string, name prefix ($wgCookiePrefix)
260	*     domain: string, cookie domain ($wgCookieDomain)
261	*     path: string, cookie path ($wgCookiePath)
262	*     secure: bool, secure attribute ($wgCookieSecure)
263	*     httpOnly: bool, httpOnly attribute ($wgCookieHttpOnly)
264	*/
265	public function setCookie( $name, $value, $expire = 0, $options = [] );
266
267	/**
268	* Get all previously set cookies as a list of associative arrays with
269	* the following keys:
270	*
271	*  - name: The cookie name
272	*  - value: The cookie value
273	*  - expire: The requested expiry time
274	*  - options: An associative array of further options
275	*
276	* @return array
277	* @phan-return array{name:string,value:mixed,expire:int,options:array}
278	*/
279	public function getCookies();
280	}