41daf4d0d5
Note that "post" parameters remain accessible through getValidatedParams(), while "body" parameters have to be accessed though getValidatedBody(). This adds a number of tests that ensure that this remains to be the case, while deprecation warnings are triggered when appropriate. Code search to check that this is unused in prod: https://codesearch.wmcloud.org/things/?q=SOURCE+*%3D%3E+*%27post%27&files=&excludeFiles=&repos= Previous reverted incarnation of this: Ia0eedb383e69b Bug: T362850 Bug: T358560 Depends-On: Id94335b3ec8f0549ff7350d31cb7cfee8feaa012 Change-Id: I88accc52c5faab70b453709b02ed88a8af4bc181
334 lines
10 KiB
PHP
334 lines
10 KiB
PHP
<?php
|
|
|
|
/**
|
|
* Copyright (c) 2019 Wikimedia Foundation.
|
|
*
|
|
* This file is partly derived from PSR-7, which requires the following copyright notice:
|
|
*
|
|
* Copyright (c) 2014 PHP Framework Interoperability Group
|
|
*
|
|
* Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
* of this software and associated documentation files (the "Software"), to deal
|
|
* in the Software without restriction, including without limitation the rights
|
|
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
* copies of the Software, and to permit persons to whom the Software is
|
|
* furnished to do so, subject to the following conditions:
|
|
*
|
|
* The above copyright notice and this permission notice shall be included in
|
|
* all copies or substantial portions of the Software.
|
|
*
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
* THE SOFTWARE.
|
|
*
|
|
* @file
|
|
*/
|
|
|
|
namespace MediaWiki\Rest;
|
|
|
|
use Psr\Http\Message\StreamInterface;
|
|
use Psr\Http\Message\UriInterface;
|
|
|
|
/**
|
|
* A request interface similar to PSR-7's ServerRequestInterface
|
|
*/
|
|
interface RequestInterface {
|
|
/** @var string[] HTTP request methods that we expect never to have a payload */
|
|
public const NO_BODY_METHODS = [ 'GET', 'HEAD' ];
|
|
|
|
/** @var string[] HTTP request methods that we expect always to have a payload */
|
|
public const BODY_METHODS = [ 'POST', 'PUT' ];
|
|
|
|
// NOTE: per RFC 7231 (https://www.rfc-editor.org/rfc/rfc7231#section-4.3.5), sending a body
|
|
// with the DELETE method "has no defined semantics". We allow it, as it is useful for
|
|
// passing the csrf token required by some authentication methods.
|
|
|
|
public const JSON_CONTENT_TYPE = 'application/json';
|
|
public const MULTIPART_FORM_DATA_CONTENT_TYPE = 'multipart/form-data';
|
|
public const FORM_URLENCODED_CONTENT_TYPE = 'application/x-www-form-urlencoded';
|
|
|
|
/** @var string[] Content types handled via $_POST */
|
|
public const FORM_DATA_CONTENT_TYPES = [
|
|
self::FORM_URLENCODED_CONTENT_TYPE,
|
|
self::MULTIPART_FORM_DATA_CONTENT_TYPE,
|
|
];
|
|
|
|
/**
|
|
* Retrieves the HTTP method of the request.
|
|
*
|
|
* @return string Returns the request method.
|
|
*/
|
|
public function getMethod();
|
|
|
|
/**
|
|
* Retrieves the URI instance.
|
|
*
|
|
* This method MUST return a UriInterface instance.
|
|
*
|
|
* @link http://tools.ietf.org/html/rfc3986#section-4.3
|
|
* @return UriInterface Returns a UriInterface instance
|
|
* representing the URI of the request.
|
|
*/
|
|
public function getUri();
|
|
|
|
// MessageInterface
|
|
|
|
/**
|
|
* Retrieves the HTTP protocol version as a string.
|
|
*
|
|
* The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
|
|
*
|
|
* @return string HTTP protocol version.
|
|
*/
|
|
public function getProtocolVersion();
|
|
|
|
/**
|
|
* Retrieves all message header values.
|
|
*
|
|
* The keys represent the header name as it will be sent over the wire, and
|
|
* each value is an array of strings associated with the header.
|
|
*
|
|
* // Represent the headers as a string
|
|
* foreach ($message->getHeaders() as $name => $values) {
|
|
* echo $name . ": " . implode(", ", $values);
|
|
* }
|
|
*
|
|
* // Emit headers iteratively:
|
|
* foreach ($message->getHeaders() as $name => $values) {
|
|
* foreach ($values as $value) {
|
|
* header(sprintf('%s: %s', $name, $value), false);
|
|
* }
|
|
* }
|
|
*
|
|
* While header names are not case-sensitive, getHeaders() will preserve the
|
|
* exact case in which headers were originally specified.
|
|
*
|
|
* A single header value may be a string containing a comma-separated list.
|
|
* Lists will not necessarily be split into arrays. See the comment on
|
|
* HeaderContainer::convertToListAndString().
|
|
*
|
|
* @return string[][] Returns an associative array of the message's headers. Each
|
|
* key MUST be a header name, and each value MUST be an array of strings
|
|
* for that header.
|
|
*/
|
|
public function getHeaders();
|
|
|
|
/**
|
|
* Retrieves a message header value by the given case-insensitive name.
|
|
*
|
|
* This method returns an array of all the header values of the given
|
|
* case-insensitive header name.
|
|
*
|
|
* If the header does not appear in the message, this method MUST return an
|
|
* empty array.
|
|
*
|
|
* A single header value may be a string containing a comma-separated list.
|
|
* Lists will not necessarily be split into arrays. See the comment on
|
|
* HeaderContainer::convertToListAndString().
|
|
*
|
|
* @param string $name Case-insensitive header field name.
|
|
* @return string[] An array of string values as provided for the given
|
|
* header. If the header does not appear in the message, this method MUST
|
|
* return an empty array.
|
|
*/
|
|
public function getHeader( $name );
|
|
|
|
/**
|
|
* Checks if a header exists by the given case-insensitive name.
|
|
*
|
|
* @param string $name Case-insensitive header field name.
|
|
* @return bool Returns true if any header names match the given header
|
|
* name using a case-insensitive string comparison. Returns false if
|
|
* no matching header name is found in the message.
|
|
*/
|
|
public function hasHeader( $name );
|
|
|
|
/**
|
|
* Retrieves a comma-separated string of the values for a single header.
|
|
*
|
|
* This method returns all of the header values of the given
|
|
* case-insensitive header name as a string concatenated together using
|
|
* a comma.
|
|
*
|
|
* NOTE: Not all header values may be appropriately represented using
|
|
* comma concatenation. For such headers, use getHeader() instead
|
|
* and supply your own delimiter when concatenating.
|
|
*
|
|
* If the header does not appear in the message, this method MUST return
|
|
* an empty string.
|
|
*
|
|
* @param string $name Case-insensitive header field name.
|
|
* @return string A string of values as provided for the given header
|
|
* concatenated together using a comma. If the header does not appear in
|
|
* the message, this method MUST return an empty string.
|
|
*/
|
|
public function getHeaderLine( $name );
|
|
|
|
/**
|
|
* Gets the body of the message.
|
|
*
|
|
* @return StreamInterface Returns the body as a stream.
|
|
*/
|
|
public function getBody();
|
|
|
|
// ServerRequestInterface
|
|
|
|
/**
|
|
* Retrieve server parameters.
|
|
*
|
|
* Retrieves data related to the incoming request environment,
|
|
* typically derived from PHP's $_SERVER superglobal. The data IS NOT
|
|
* REQUIRED to originate from $_SERVER.
|
|
*
|
|
* @return array
|
|
*/
|
|
public function getServerParams();
|
|
|
|
/**
|
|
* Retrieve cookies.
|
|
*
|
|
* Retrieves cookies sent by the client to the server.
|
|
*
|
|
* The data MUST be compatible with the structure of the $_COOKIE
|
|
* superglobal.
|
|
*
|
|
* @return array
|
|
*/
|
|
public function getCookieParams();
|
|
|
|
/**
|
|
* Retrieve query string arguments.
|
|
*
|
|
* Retrieves the deserialized query string arguments, if any.
|
|
*
|
|
* Note: the query params might not be in sync with the URI or server
|
|
* params. If you need to ensure you are only getting the original
|
|
* values, you may need to parse the query string from `getUri()->getQuery()`
|
|
* or from the `QUERY_STRING` server param.
|
|
*
|
|
* @return array
|
|
*/
|
|
public function getQueryParams();
|
|
|
|
/**
|
|
* Retrieve normalized file upload data.
|
|
*
|
|
* This method returns upload metadata in a normalized tree, with each leaf
|
|
* an instance of Psr\Http\Message\UploadedFileInterface.
|
|
*
|
|
* @return array An array tree of UploadedFileInterface instances; an empty
|
|
* array MUST be returned if no data is present.
|
|
*/
|
|
public function getUploadedFiles();
|
|
|
|
// MediaWiki extensions to PSR-7
|
|
|
|
/**
|
|
* Get the parameters derived from the path template match
|
|
*
|
|
* @return string[]
|
|
*/
|
|
public function getPathParams();
|
|
|
|
/**
|
|
* Retrieve a single path parameter.
|
|
*
|
|
* Retrieves a single path parameter as described in getPathParams(). If
|
|
* the attribute has not been previously set, returns null.
|
|
*
|
|
* @see getPathParams()
|
|
* @param string $name The parameter name.
|
|
* @return string|null
|
|
*/
|
|
public function getPathParam( $name );
|
|
|
|
/**
|
|
* Erase all path parameters from the object and set the parameter array
|
|
* to the one specified.
|
|
*
|
|
* @param string[] $params
|
|
*/
|
|
public function setPathParams( $params );
|
|
|
|
/**
|
|
* Get the current cookie prefix
|
|
*
|
|
* @return string
|
|
*/
|
|
public function getCookiePrefix();
|
|
|
|
/**
|
|
* Add the cookie prefix to a specified cookie name and get the value of
|
|
* the resulting prefixed cookie. If the cookie does not exist, $default
|
|
* is returned.
|
|
*
|
|
* @param string $name
|
|
* @param mixed|null $default
|
|
* @return mixed The cookie value as a string, or $default
|
|
*/
|
|
public function getCookie( $name, $default = null );
|
|
|
|
/**
|
|
* Retrieve POST form parameters.
|
|
*
|
|
* This will return an array of parameters in the format of $_POST.
|
|
*
|
|
* @return array The deserialized POST parameters
|
|
*/
|
|
public function getPostParams();
|
|
|
|
/**
|
|
* Returns the parsed body as an associative array.
|
|
*
|
|
* If setParsedBody() was called on a given RequestInterface object,
|
|
* this method must return the data passed to that call.
|
|
*
|
|
* If setParsedBody() was not called, implementations may return body data
|
|
* they get from the runtime environment, or null.
|
|
*
|
|
* @since 1.42
|
|
*
|
|
* @return array|null
|
|
*/
|
|
public function getParsedBody(): ?array;
|
|
|
|
/**
|
|
* Specify the data that subsequent calls to getParsedBody() should return.
|
|
*
|
|
* This is intended for use by the framework to make a parsed representation
|
|
* of the body data known to request handlers.
|
|
*
|
|
* @since 1.42
|
|
*
|
|
* @param array|null $data The body data.
|
|
*/
|
|
public function setParsedBody( ?array $data );
|
|
|
|
/**
|
|
* Returns the MIME type of the request body, according to the
|
|
* content-type header. The value returned by this method must be
|
|
* a lower-case string with no whitespace and no additional information
|
|
* beyond the mime type. In particular, any "parameters" must be stripped
|
|
* from the value of the content-type header. See RFC 9110 section 8.3.1.
|
|
*
|
|
* @since 1.42
|
|
*
|
|
* @return string|null The request body's mime type, or null if there is
|
|
* no request body or there the type was not specified.
|
|
*/
|
|
public function getBodyType(): ?string;
|
|
|
|
/**
|
|
* Determines whether the request has body data associated with it.
|
|
* Note that this method may return true even if the body is empty.
|
|
*
|
|
* @since 1.42
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function hasBody(): bool;
|
|
}
|