includes/Rest/ResponseInterface.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
  35 /**
  36  * An interface similar to PSR-7's ResponseInterface, the primary difference
  37  * being that it is mutable.
  38  */
  39 interface ResponseInterface {
  40         // ResponseInterface
  41
  42         /**
  43          * Gets the response status code.
  44          *
  45          * The status code is a 3-digit integer result code of the server's attempt
  46          * to understand and satisfy the request.
  47          *
  48          * @return int Status code.
  49          */
  50         function getStatusCode();
  51
  52         /**
  53          * Gets the response reason phrase associated with the status code.
  54          *
  55          * Because a reason phrase is not a required element in a response
  56          * status line, the reason phrase value MAY be empty. Implementations MAY
  57          * choose to return the default RFC 7231 recommended reason phrase (or those
  58          * listed in the IANA HTTP Status Code Registry) for the response's
  59          * status code.
  60          *
  61          * @see http://tools.ietf.org/html/rfc7231#section-6
  62          * @see http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
  63          * @return string Reason phrase; must return an empty string if none present.
  64          */
  65         function getReasonPhrase();
  66
  67         // ResponseInterface mutation
  68
  69         /**
  70          * Set the status code and, optionally, reason phrase.
  71          *
  72          * If no reason phrase is specified, implementations MAY choose to default
  73          * to the RFC 7231 or IANA recommended reason phrase for the response's
  74          * status code.
  75          *
  76          * @see http://tools.ietf.org/html/rfc7231#section-6
  77          * @see http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
  78          * @param int $code The 3-digit integer result code to set.
  79          * @param string $reasonPhrase The reason phrase to use with the
  80          *     provided status code; if none is provided, implementations MAY
  81          *     use the defaults as suggested in the HTTP specification.
  82          * @throws \InvalidArgumentException For invalid status code arguments.
  83          */
  84         function setStatus( $code, $reasonPhrase = '' );
  85
  86         // MessageInterface
  87
  88         /**
  89          * Retrieves the HTTP protocol version as a string.
  90          *
  91          * The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
  92          *
  93          * @return string HTTP protocol version.
  94          */
  95         function getProtocolVersion();
  96
  97         /**
  98          * Retrieves all message header values.
  99          *
 100          * The keys represent the header name as it will be sent over the wire, and
 101          * each value is an array of strings associated with the header.
 102          *
 103          *     // Represent the headers as a string
 104          *     foreach ($message->getHeaders() as $name => $values) {
 105          *         echo $name . ': ' . implode(', ', $values);
 106          *     }
 107          *
 108          *     // Emit headers iteratively:
 109          *     foreach ($message->getHeaders() as $name => $values) {
 110          *         foreach ($values as $value) {
 111          *             header(sprintf('%s: %s', $name, $value), false);
 112          *         }
 113          *     }
 114          *
 115          * While header names are not case-sensitive, getHeaders() will preserve the
 116          * exact case in which headers were originally specified.
 117          *
 118          * @return string[][] Returns an associative array of the message's headers.
 119          *     Each key MUST be a header name, and each value MUST be an array of
 120          *     strings for that header.
 121          */
 122         function getHeaders();
 123
 124         /**
 125          * Checks if a header exists by the given case-insensitive name.
 126          *
 127          * @param string $name Case-insensitive header field name.
 128          * @return bool Returns true if any header names match the given header
 129          *     name using a case-insensitive string comparison. Returns false if
 130          *     no matching header name is found in the message.
 131          */
 132         function hasHeader( $name );
 133
 134         /**
 135          * Retrieves a message header value by the given case-insensitive name.
 136          *
 137          * This method returns an array of all the header values of the given
 138          * case-insensitive header name.
 139          *
 140          * If the header does not appear in the message, this method MUST return an
 141          * empty array.
 142          *
 143          * @param string $name Case-insensitive header field name.
 144          * @return string[] An array of string values as provided for the given
 145          *    header. If the header does not appear in the message, this method MUST
 146          *    return an empty array.
 147          */
 148         function getHeader( $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         function getHeaderLine( $name );
 170
 171         /**
 172          * Gets the body of the message.
 173          *
 174          * @return StreamInterface Returns the body as a stream.
 175          */
 176         function getBody();
 177
 178         // MessageInterface mutation
 179
 180         /**
 181          * Set the HTTP protocol version.
 182          *
 183          * The version string MUST contain only the HTTP version number (e.g.,
 184          * "1.1", "1.0").
 185          *
 186          * @param string $version HTTP protocol version
 187          */
 188         function setProtocolVersion( $version );
 189
 190         /**
 191          * Set or replace the specified header.
 192          *
 193          * While header names are case-insensitive, the casing of the header will
 194          * be preserved by this function, and returned from getHeaders().
 195          *
 196          * @param string $name Case-insensitive header field name.
 197          * @param string|string[] $value Header value(s).
 198          * @throws \InvalidArgumentException for invalid header names or values.
 199          */
 200         function setHeader( $name, $value );
 201
 202         /**
 203          * Append the given value to the specified header.
 204          *
 205          * Existing values for the specified header will be maintained. The new
 206          * value(s) will be appended to the existing list. If the header did not
 207          * exist previously, it will be added.
 208          *
 209          * @param string $name Case-insensitive header field name to add.
 210          * @param string|string[] $value Header value(s).
 211          * @throws \InvalidArgumentException for invalid header names.
 212          * @throws \InvalidArgumentException for invalid header values.
 213          */
 214         function addHeader( $name, $value );
 215
 216         /**
 217          * Remove the specified header.
 218          *
 219          * Header resolution MUST be done without case-sensitivity.
 220          *
 221          * @param string $name Case-insensitive header field name to remove.
 222          */
 223         function removeHeader( $name );
 224
 225         /**
 226          * Set the message body
 227          *
 228          * The body MUST be a StreamInterface object.
 229          *
 230          * @param StreamInterface $body Body.
 231          * @throws \InvalidArgumentException When the body is not valid.
 232          */
 233         function setBody( StreamInterface $body );
 234
 235         // MediaWiki extensions to PSR-7
 236
 237         /**
 238          * Get the full header lines including colon-separated name and value, for
 239          * passing directly to header(). Not including the status line.
 240          *
 241          * @return string[]
 242          */
 243         function getRawHeaderLines();
 244
 245         /**
 246          * Set a cookie
 247          *
 248          * The name will have the cookie prefix added to it before it is sent over
 249          * the network.
 250          *
 251          * @param string $name The name of the cookie, not including prefix.
 252          * @param string $value The value to be stored in the cookie.
 253          * @param int|null $expire Unix timestamp (in seconds) when the cookie should expire.
 254          *        0 (the default) causes it to expire $wgCookieExpiration seconds from now.
 255          *        null causes it to be a session cookie.
 256          * @param array $options Assoc of additional cookie options:
 257          *     prefix: string, name prefix ($wgCookiePrefix)
 258          *     domain: string, cookie domain ($wgCookieDomain)
 259          *     path: string, cookie path ($wgCookiePath)
 260          *     secure: bool, secure attribute ($wgCookieSecure)
 261          *     httpOnly: bool, httpOnly attribute ($wgCookieHttpOnly)
 262          */
 263         public function setCookie( $name, $value, $expire = 0, $options = [] );
 264
 265         /**
 266          * Get all previously set cookies as a list of associative arrays with
 267          * the following keys:
 268          *
 269          *  - name: The cookie name
 270          *  - value: The cookie value
 271          *  - expire: The requested expiry time
 272          *  - options: An associative array of further options
 273          *
 274          * @return array
 275          */
 276         public function getCookies();
 277 }