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