265 lines
8 KiB
PHP
265 lines
8 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 {
|
|
// RequestInterface
|
|
|
|
/**
|
|
* 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();
|
|
}
|