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 | /** @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 | } |