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