3
declare(strict_types=1);
6
* This file is part of CodeIgniter 4 framework.
8
* (c) CodeIgniter Foundation <admin@codeigniter.com>
10
* For the full copyright and license information, please view
11
* the LICENSE file that was distributed with this source code.
14
namespace CodeIgniter\HTTP;
16
use CodeIgniter\Cookie\Cookie;
17
use CodeIgniter\Cookie\CookieStore;
18
use CodeIgniter\HTTP\Exceptions\HTTPException;
19
use CodeIgniter\Pager\PagerInterface;
21
use InvalidArgumentException;
24
* Representation of an outgoing, server-side response.
25
* Most of these methods are supplied by ResponseTrait.
27
* Per the HTTP specification, this interface includes properties for
28
* each of the following:
31
* - Status code and reason phrase
35
interface ResponseInterface extends MessageInterface
38
* Constants for status codes.
39
* From https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
42
public const HTTP_CONTINUE = 100;
43
public const HTTP_SWITCHING_PROTOCOLS = 101;
44
public const HTTP_PROCESSING = 102;
45
public const HTTP_EARLY_HINTS = 103;
46
public const HTTP_OK = 200;
47
public const HTTP_CREATED = 201;
48
public const HTTP_ACCEPTED = 202;
49
public const HTTP_NONAUTHORITATIVE_INFORMATION = 203;
50
public const HTTP_NO_CONTENT = 204;
51
public const HTTP_RESET_CONTENT = 205;
52
public const HTTP_PARTIAL_CONTENT = 206;
53
public const HTTP_MULTI_STATUS = 207;
54
public const HTTP_ALREADY_REPORTED = 208;
55
public const HTTP_IM_USED = 226;
56
public const HTTP_MULTIPLE_CHOICES = 300;
57
public const HTTP_MOVED_PERMANENTLY = 301;
58
public const HTTP_FOUND = 302;
59
public const HTTP_SEE_OTHER = 303;
60
public const HTTP_NOT_MODIFIED = 304;
61
public const HTTP_USE_PROXY = 305;
62
public const HTTP_SWITCH_PROXY = 306;
63
public const HTTP_TEMPORARY_REDIRECT = 307;
64
public const HTTP_PERMANENT_REDIRECT = 308;
65
public const HTTP_BAD_REQUEST = 400;
66
public const HTTP_UNAUTHORIZED = 401;
67
public const HTTP_PAYMENT_REQUIRED = 402;
68
public const HTTP_FORBIDDEN = 403;
69
public const HTTP_NOT_FOUND = 404;
70
public const HTTP_METHOD_NOT_ALLOWED = 405;
71
public const HTTP_NOT_ACCEPTABLE = 406;
72
public const HTTP_PROXY_AUTHENTICATION_REQUIRED = 407;
73
public const HTTP_REQUEST_TIMEOUT = 408;
74
public const HTTP_CONFLICT = 409;
75
public const HTTP_GONE = 410;
76
public const HTTP_LENGTH_REQUIRED = 411;
77
public const HTTP_PRECONDITION_FAILED = 412;
78
public const HTTP_PAYLOAD_TOO_LARGE = 413;
79
public const HTTP_URI_TOO_LONG = 414;
80
public const HTTP_UNSUPPORTED_MEDIA_TYPE = 415;
81
public const HTTP_RANGE_NOT_SATISFIABLE = 416;
82
public const HTTP_EXPECTATION_FAILED = 417;
83
public const HTTP_IM_A_TEAPOT = 418;
84
public const HTTP_MISDIRECTED_REQUEST = 421;
85
public const HTTP_UNPROCESSABLE_ENTITY = 422;
86
public const HTTP_LOCKED = 423;
87
public const HTTP_FAILED_DEPENDENCY = 424;
88
public const HTTP_TOO_EARLY = 425;
89
public const HTTP_UPGRADE_REQUIRED = 426;
90
public const HTTP_PRECONDITION_REQUIRED = 428;
91
public const HTTP_TOO_MANY_REQUESTS = 429;
92
public const HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE = 431;
93
public const HTTP_UNAVAILABLE_FOR_LEGAL_REASONS = 451;
94
public const HTTP_CLIENT_CLOSED_REQUEST = 499;
95
public const HTTP_INTERNAL_SERVER_ERROR = 500;
96
public const HTTP_NOT_IMPLEMENTED = 501;
97
public const HTTP_BAD_GATEWAY = 502;
98
public const HTTP_SERVICE_UNAVAILABLE = 503;
99
public const HTTP_GATEWAY_TIMEOUT = 504;
100
public const HTTP_HTTP_VERSION_NOT_SUPPORTED = 505;
101
public const HTTP_VARIANT_ALSO_NEGOTIATES = 506;
102
public const HTTP_INSUFFICIENT_STORAGE = 507;
103
public const HTTP_LOOP_DETECTED = 508;
104
public const HTTP_NOT_EXTENDED = 510;
105
public const HTTP_NETWORK_AUTHENTICATION_REQUIRED = 511;
106
public const HTTP_NETWORK_CONNECT_TIMEOUT_ERROR = 599;
109
* Gets the response status code.
111
* The status code is a 3-digit integer result code of the server's attempt
112
* to understand and satisfy the request.
114
* @return int Status code.
116
public function getStatusCode(): int;
119
* Return an instance with the specified status code and, optionally, reason phrase.
121
* If no reason phrase is specified, will default recommended reason phrase for
122
* the response's status code.
124
* @see http://tools.ietf.org/html/rfc7231#section-6
125
* @see http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
127
* @param int $code The 3-digit integer result code to set.
128
* @param string $reason The reason phrase to use with the
129
* provided status code; if none is provided, will
130
* default to the IANA name.
134
* @throws HTTPException For invalid status code arguments.
136
public function setStatusCode(int $code, string $reason = '');
139
* Gets the response phrase associated with the status code.
141
* @see http://tools.ietf.org/html/rfc7231#section-6
142
* @see http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
144
* @deprecated Use getReasonPhrase()
146
public function getReason(): string;
149
* Gets the response reason phrase associated with the status code.
151
* Because a reason phrase is not a required element in a response
152
* status line, the reason phrase value MAY be null. Implementations MAY
153
* choose to return the default RFC 7231 recommended reason phrase (or those
154
* listed in the IANA HTTP Status Code Registry) for the response's
157
* @see http://tools.ietf.org/html/rfc7231#section-6
158
* @see http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
160
* @return string Reason phrase; must return an empty string if none present.
162
public function getReasonPhrase();
164
// --------------------------------------------------------------------
165
// Convenience Methods
166
// --------------------------------------------------------------------
169
* Sets the date header
173
public function setDate(DateTime $date);
176
* Sets the Last-Modified date header.
178
* $date can be either a string representation of the date or,
179
* preferably, an instance of DateTime.
181
* @param DateTime|string $date
185
public function setLastModified($date);
188
* Set the Link Header
190
* @see http://tools.ietf.org/html/rfc5988
194
* @todo Recommend moving to Pager
196
public function setLink(PagerInterface $pager);
199
* Sets the Content Type header for this response with the mime type
200
* and, optionally, the charset.
204
public function setContentType(string $mime, string $charset = 'UTF-8');
206
// --------------------------------------------------------------------
208
// --------------------------------------------------------------------
211
* Converts the $body into JSON and sets the Content Type header.
213
* @param array|string $body
217
public function setJSON($body, bool $unencoded = false);
220
* Returns the current body, converted to JSON is it isn't already.
222
* @return bool|string|null
224
* @throws InvalidArgumentException If the body property is not array.
226
public function getJSON();
229
* Converts $body into XML, and sets the correct Content-Type.
231
* @param array|string $body
235
public function setXML($body);
238
* Retrieves the current body into XML and returns it.
240
* @return bool|string|null
242
* @throws InvalidArgumentException If the body property is not array.
244
public function getXML();
246
// --------------------------------------------------------------------
247
// Cache Control Methods
249
// http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9
250
// --------------------------------------------------------------------
253
* Sets the appropriate headers to ensure this response
254
* is not cached by the browsers.
258
public function noCache();
261
* A shortcut method that allows the developer to set all of the
262
* cache-control headers in one method call.
264
* The options array is used to provide the cache-control directives
265
* for the header. It might look something like:
273
* Typical options are:
286
public function setCache(array $options = []);
288
// --------------------------------------------------------------------
290
// --------------------------------------------------------------------
293
* Sends the output to the browser.
297
public function send();
300
* Sends the headers of this HTTP request to the browser.
304
public function sendHeaders();
307
* Sends the Body of the message to the browser.
311
public function sendBody();
313
// --------------------------------------------------------------------
315
// --------------------------------------------------------------------
320
* Accepts an arbitrary number of binds (up to 7) or an associative
321
* array in the first parameter containing all the values.
323
* @param array|Cookie|string $name Cookie name / array containing binds / Cookie object
324
* @param string $value Cookie value
325
* @param int $expire Cookie expiration time in seconds
326
* @param string $domain Cookie domain (e.g.: '.yourdomain.com')
327
* @param string $path Cookie path (default: '/')
328
* @param string $prefix Cookie name prefix
329
* @param bool $secure Whether to only transfer cookies via SSL
330
* @param bool $httponly Whether only make the cookie accessible via HTTP (no javascript)
331
* @param string|null $samesite
335
public function setCookie(
348
* Checks to see if the Response has a specified cookie or not.
350
public function hasCookie(string $name, ?string $value = null, string $prefix = ''): bool;
355
* @return array<string, Cookie>|Cookie|null
357
public function getCookie(?string $name = null, string $prefix = '');
360
* Sets a cookie to be deleted when the response is sent.
364
public function deleteCookie(string $name = '', string $domain = '', string $path = '/', string $prefix = '');
367
* Returns all cookies currently set.
369
* @return array<string, Cookie>
371
public function getCookies();
374
* Returns the `CookieStore` instance.
376
* @return CookieStore
378
public function getCookieStore();
380
// --------------------------------------------------------------------
382
// --------------------------------------------------------------------
385
* Perform a redirect to a new URL, in two flavors: header or location.
387
* @param string $uri The URI to redirect to
388
* @param int $code The type of redirection, defaults to 302
392
* @throws HTTPException For invalid status code.
394
public function redirect(string $uri, string $method = 'auto', ?int $code = null);
399
* Generates the headers that force a download to happen. And
400
* sends the file to the browser.
402
* @param string $filename The path to the file to send
403
* @param string|null $data The data to be downloaded
404
* @param bool $setMime Whether to try and send the actual MIME type
406
* @return DownloadResponse|null
408
public function download(string $filename = '', $data = '', bool $setMime = false);
410
// --------------------------------------------------------------------
412
// --------------------------------------------------------------------
415
* Get Content Security Policy handler.
417
public function getCSP(): ContentSecurityPolicy;