includes/Rest/RequestInterface.php

   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         // RequestInterface
  41
  42         /**
  43          * Retrieves the HTTP method of the request.
  44          *
  45          * @return string Returns the request method.
  46          */
  47         function getMethod();
  48
  49         /**
  50          * Retrieves the URI instance.
  51          *
  52          * This method MUST return a UriInterface instance.
  53          *
  54          * @link http://tools.ietf.org/html/rfc3986#section-4.3
  55          * @return UriInterface Returns a UriInterface instance
  56          *     representing the URI of the request.
  57          */
  58         function getUri();
  59
  60         // MessageInterface
  61
  62         /**
  63          * Retrieves the HTTP protocol version as a string.
  64          *
  65          * The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
  66          *
  67          * @return string HTTP protocol version.
  68          */
  69         function getProtocolVersion();
  70
  71         /**
  72          * Retrieves all message header values.
  73          *
  74          * The keys represent the header name as it will be sent over the wire, and
  75          * each value is an array of strings associated with the header.
  76          *
  77          *     // Represent the headers as a string
  78          *     foreach ($message->getHeaders() as $name => $values) {
  79          *         echo $name . ": " . implode(", ", $values);
  80          *     }
  81          *
  82          *     // Emit headers iteratively:
  83          *     foreach ($message->getHeaders() as $name => $values) {
  84          *         foreach ($values as $value) {
  85          *             header(sprintf('%s: %s', $name, $value), false);
  86          *         }
  87          *     }
  88          *
  89          * While header names are not case-sensitive, getHeaders() will preserve the
  90          * exact case in which headers were originally specified.
  91          *
  92          * A single header value may be a string containing a comma-separated list.
  93          * Lists will not necessarily be split into arrays. See the comment on
  94          * HeaderContainer::convertToListAndString().
  95          *
  96          * @return string[][] Returns an associative array of the message's headers. Each
  97          *     key MUST be a header name, and each value MUST be an array of strings
  98          *     for that header.
  99          */
 100         function getHeaders();
 101
 102         /**
 103          * Retrieves a message header value by the given case-insensitive name.
 104          *
 105          * This method returns an array of all the header values of the given
 106          * case-insensitive header name.
 107          *
 108          * If the header does not appear in the message, this method MUST return an
 109          * empty array.
 110          *
 111          * A single header value may be a string containing a comma-separated list.
 112          * Lists will not necessarily be split into arrays. See the comment on
 113          * HeaderContainer::convertToListAndString().
 114          *
 115          * @param string $name Case-insensitive header field name.
 116          * @return string[] An array of string values as provided for the given
 117          *    header. If the header does not appear in the message, this method MUST
 118          *    return an empty array.
 119          */
 120         function getHeader( $name );
 121
 122         /**
 123          * Checks if a header exists by the given case-insensitive name.
 124          *
 125          * @param string $name Case-insensitive header field name.
 126          * @return bool Returns true if any header names match the given header
 127          *     name using a case-insensitive string comparison. Returns false if
 128          *     no matching header name is found in the message.
 129          */
 130         function hasHeader( $name );
 131
 132         /**
 133          * Retrieves a comma-separated string of the values for a single header.
 134          *
 135          * This method returns all of the header values of the given
 136          * case-insensitive header name as a string concatenated together using
 137          * a comma.
 138          *
 139          * NOTE: Not all header values may be appropriately represented using
 140          * comma concatenation. For such headers, use getHeader() instead
 141          * and supply your own delimiter when concatenating.
 142          *
 143          * If the header does not appear in the message, this method MUST return
 144          * an empty string.
 145          *
 146          * @param string $name Case-insensitive header field name.
 147          * @return string A string of values as provided for the given header
 148          *    concatenated together using a comma. If the header does not appear in
 149          *    the message, this method MUST return an empty string.
 150          */
 151         function getHeaderLine( $name );
 152
 153         /**
 154          * Gets the body of the message.
 155          *
 156          * @return StreamInterface Returns the body as a stream.
 157          */
 158         function getBody();
 159
 160         // ServerRequestInterface
 161
 162         /**
 163          * Retrieve server parameters.
 164          *
 165          * Retrieves data related to the incoming request environment,
 166          * typically derived from PHP's $_SERVER superglobal. The data IS NOT
 167          * REQUIRED to originate from $_SERVER.
 168          *
 169          * @return array
 170          */
 171         function getServerParams();
 172
 173         /**
 174          * Retrieve cookies.
 175          *
 176          * Retrieves cookies sent by the client to the server.
 177          *
 178          * The data MUST be compatible with the structure of the $_COOKIE
 179          * superglobal.
 180          *
 181          * @return array
 182          */
 183         function getCookieParams();
 184
 185         /**
 186          * Retrieve query string arguments.
 187          *
 188          * Retrieves the deserialized query string arguments, if any.
 189          *
 190          * Note: the query params might not be in sync with the URI or server
 191          * params. If you need to ensure you are only getting the original
 192          * values, you may need to parse the query string from `getUri()->getQuery()`
 193          * or from the `QUERY_STRING` server param.
 194          *
 195          * @return array
 196          */
 197         function getQueryParams();
 198
 199         /**
 200          * Retrieve normalized file upload data.
 201          *
 202          * This method returns upload metadata in a normalized tree, with each leaf
 203          * an instance of Psr\Http\Message\UploadedFileInterface.
 204          *
 205          * @return array An array tree of UploadedFileInterface instances; an empty
 206          *     array MUST be returned if no data is present.
 207          */
 208         function getUploadedFiles();
 209
 210         // MediaWiki extensions to PSR-7
 211
 212         /**
 213          * Get the parameters derived from the path template match
 214          *
 215          * @return string[]
 216          */
 217         function getPathParams();
 218
 219         /**
 220          * Retrieve a single path parameter.
 221          *
 222          * Retrieves a single path parameter as described in getPathParams(). If
 223          * the attribute has not been previously set, returns null.
 224          *
 225          * @see getPathParams()
 226          * @param string $name The parameter name.
 227          * @return string|null
 228          */
 229         function getPathParam( $name );
 230
 231         /**
 232          * Erase all path parameters from the object and set the parameter array
 233          * to the one specified.
 234          *
 235          * @param string[] $params
 236          */
 237         function setPathParams( $params );
 238
 239         /**
 240          * Get the current cookie prefix
 241          *
 242          * @return string
 243          */
 244         function getCookiePrefix();
 245
 246         /**
 247          * Add the cookie prefix to a specified cookie name and get the value of
 248          * the resulting prefixed cookie. If the cookie does not exist, $default
 249          * is returned.
 250          *
 251          * @param string $name
 252          * @param mixed|null $default
 253          * @return mixed The cookie value as a string, or $default
 254          */
 255         function getCookie( $name, $default = null );
 256
 257         /**
 258          * Retrieve POST form parameters.
 259          *
 260          * This will return an array of parameters in the format of $_POST.
 261          *
 262          * @return array The deserialized POST parameters
 263          */
 264         function getPostParams();
 265 }