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	use Psr\Http\Message\UriInterface;
35
36	/**
37	* A request interface similar to PSR-7's ServerRequestInterface
38	*/
39	interface RequestInterface {
40	/** @var string[] HTTP request methods that we expect never to have a payload */
41	public const NO_BODY_METHODS = [ 'GET', 'HEAD' ];
42
43	/** @var string[] HTTP request methods that we expect always to have a payload */
44	public const BODY_METHODS = [ 'POST', 'PUT' ];
45
46	// NOTE: per RFC 7231 (https://www.rfc-editor.org/rfc/rfc7231#section-4.3.5), sending a body
47	// with the DELETE method "has no defined semantics". We allow it, as it is useful for
48	// passing the csrf token required by some authentication methods.
49
50	/** @var string[] Content types handled via $_POST */
51	public const FORM_DATA_CONTENT_TYPES = [
52	'application/x-www-form-urlencoded',
53	'multipart/form-data',
54	];
55
56	/**
57	* Retrieves the HTTP method of the request.
58	*
59	* @return string Returns the request method.
60	*/
61	public function getMethod();
62
63	/**
64	* Retrieves the URI instance.
65	*
66	* This method MUST return a UriInterface instance.
67	*
68	* @link http://tools.ietf.org/html/rfc3986#section-4.3
69	* @return UriInterface Returns a UriInterface instance
70	*     representing the URI of the request.
71	*/
72	public function getUri();
73
74	// MessageInterface
75
76	/**
77	* Retrieves the HTTP protocol version as a string.
78	*
79	* The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
80	*
81	* @return string HTTP protocol version.
82	*/
83	public function getProtocolVersion();
84
85	/**
86	* Retrieves all message header values.
87	*
88	* The keys represent the header name as it will be sent over the wire, and
89	* each value is an array of strings associated with the header.
90	*
91	*     // Represent the headers as a string
92	*     foreach ($message->getHeaders() as $name => $values) {
93	*         echo $name . ": " . implode(", ", $values);
94	*     }
95	*
96	*     // Emit headers iteratively:
97	*     foreach ($message->getHeaders() as $name => $values) {
98	*         foreach ($values as $value) {
99	*             header(sprintf('%s: %s', $name, $value), false);
100	*         }
101	*     }
102	*
103	* While header names are not case-sensitive, getHeaders() will preserve the
104	* exact case in which headers were originally specified.
105	*
106	* A single header value may be a string containing a comma-separated list.
107	* Lists will not necessarily be split into arrays. See the comment on
108	* HeaderContainer::convertToListAndString().
109	*
110	* @return string[][] Returns an associative array of the message's headers. Each
111	*     key MUST be a header name, and each value MUST be an array of strings
112	*     for that header.
113	*/
114	public function getHeaders();
115
116	/**
117	* Retrieves a message header value by the given case-insensitive name.
118	*
119	* This method returns an array of all the header values of the given
120	* case-insensitive header name.
121	*
122	* If the header does not appear in the message, this method MUST return an
123	* empty array.
124	*
125	* A single header value may be a string containing a comma-separated list.
126	* Lists will not necessarily be split into arrays. See the comment on
127	* HeaderContainer::convertToListAndString().
128	*
129	* @param string $name Case-insensitive header field name.
130	* @return string[] An array of string values as provided for the given
131	*    header. If the header does not appear in the message, this method MUST
132	*    return an empty array.
133	*/
134	public function getHeader( $name );
135
136	/**
137	* Checks if a header exists by the given case-insensitive name.
138	*
139	* @param string $name Case-insensitive header field name.
140	* @return bool Returns true if any header names match the given header
141	*     name using a case-insensitive string comparison. Returns false if
142	*     no matching header name is found in the message.
143	*/
144	public function hasHeader( $name );
145
146	/**
147	* Retrieves a comma-separated string of the values for a single header.
148	*
149	* This method returns all of the header values of the given
150	* case-insensitive header name as a string concatenated together using
151	* a comma.
152	*
153	* NOTE: Not all header values may be appropriately represented using
154	* comma concatenation. For such headers, use getHeader() instead
155	* and supply your own delimiter when concatenating.
156	*
157	* If the header does not appear in the message, this method MUST return
158	* an empty string.
159	*
160	* @param string $name Case-insensitive header field name.
161	* @return string A string of values as provided for the given header
162	*    concatenated together using a comma. If the header does not appear in
163	*    the message, this method MUST return an empty string.
164	*/
165	public function getHeaderLine( $name );
166
167	/**
168	* Gets the body of the message.
169	*
170	* @return StreamInterface Returns the body as a stream.
171	*/
172	public function getBody();
173
174	// ServerRequestInterface
175
176	/**
177	* Retrieve server parameters.
178	*
179	* Retrieves data related to the incoming request environment,
180	* typically derived from PHP's $_SERVER superglobal. The data IS NOT
181	* REQUIRED to originate from $_SERVER.
182	*
183	* @return array
184	*/
185	public function getServerParams();
186
187	/**
188	* Retrieve cookies.
189	*
190	* Retrieves cookies sent by the client to the server.
191	*
192	* The data MUST be compatible with the structure of the $_COOKIE
193	* superglobal.
194	*
195	* @return array
196	*/
197	public function getCookieParams();
198
199	/**
200	* Retrieve query string arguments.
201	*
202	* Retrieves the deserialized query string arguments, if any.
203	*
204	* Note: the query params might not be in sync with the URI or server
205	* params. If you need to ensure you are only getting the original
206	* values, you may need to parse the query string from `getUri()->getQuery()`
207	* or from the `QUERY_STRING` server param.
208	*
209	* @return array
210	*/
211	public function getQueryParams();
212
213	/**
214	* Retrieve normalized file upload data.
215	*
216	* This method returns upload metadata in a normalized tree, with each leaf
217	* an instance of Psr\Http\Message\UploadedFileInterface.
218	*
219	* @return array An array tree of UploadedFileInterface instances; an empty
220	*     array MUST be returned if no data is present.
221	*/
222	public function getUploadedFiles();
223
224	// MediaWiki extensions to PSR-7
225
226	/**
227	* Get the parameters derived from the path template match
228	*
229	* @return string[]
230	*/
231	public function getPathParams();
232
233	/**
234	* Retrieve a single path parameter.
235	*
236	* Retrieves a single path parameter as described in getPathParams(). If
237	* the attribute has not been previously set, returns null.
238	*
239	* @see getPathParams()
240	* @param string $name The parameter name.
241	* @return string|null
242	*/
243	public function getPathParam( $name );
244
245	/**
246	* Erase all path parameters from the object and set the parameter array
247	* to the one specified.
248	*
249	* @param string[] $params
250	*/
251	public function setPathParams( $params );
252
253	/**
254	* Get the current cookie prefix
255	*
256	* @return string
257	*/
258	public function getCookiePrefix();
259
260	/**
261	* Add the cookie prefix to a specified cookie name and get the value of
262	* the resulting prefixed cookie. If the cookie does not exist, $default
263	* is returned.
264	*
265	* @param string $name
266	* @param mixed|null $default
267	* @return mixed The cookie value as a string, or $default
268	*/
269	public function getCookie( $name, $default = null );
270
271	/**
272	* Retrieve POST form parameters.
273	*
274	* This will return an array of parameters in the format of $_POST.
275	*
276	* @return array The deserialized POST parameters
277	*/
278	public function getPostParams();
279
280	/**
281	* Returns the parsed body as an associative array.
282	*
283	* If setParsedBody() was called on a given RequestInterface object,
284	* this method must return the data passed to that call.
285	*
286	* If setParsedBody() was not called, implementations may return body data
287	* they get from the runtime environment, or null.
288	*
289	* @since 1.42
290	*
291	* @return array|null
292	*/
293	public function getParsedBody(): ?array;
294
295	/**
296	* Specify the data that subsequent calls to getParsedBody() should return.
297	*
298	* This is intended for use by the framework to make a parsed representation
299	* of the body data known to request handlers.
300	*
301	* @since 1.42
302	*
303	* @param array|null $data The body data.
304	*/
305	public function setParsedBody( ?array $data );
306
307	/**
308	* Returns the MIME type of the request body, according to the
309	* content-type header. The value returned by this method must be
310	* a lower-case string with no whitespace and no additional information
311	* beyond the mime type. In particular, any "parameters" must be stripped
312	* from the value of the content-type header. See RFC 9110 section 8.3.1.
313	*
314	* @since 1.42
315	*
316	* @return string|null The request body's mime type, or null if there is
317	*         no request body or there the type was not specified.
318	*/
319	public function getBodyType(): ?string;
320
321	/**
322	* Determines whether the request has body data associated with it.
323	* Note that this method may return true even if the body is empty.
324	*
325	* @since 1.42
326	*
327	* @return bool
328	*/
329	public function hasBody(): bool;
330	}