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
31namespace MediaWiki\Rest;
32
33use Psr\Http\Message\StreamInterface;
34use Psr\Http\Message\UriInterface;
35
36/**
37 * A request interface similar to PSR-7's ServerRequestInterface
38 */
39interface 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}