See Release Notes
Long Term Support Release
1 <?php 2 3 namespace Psr\Http\Message; 4 5 /** 6 * Representation of an incoming, server-side HTTP request. 7 * 8 * Per the HTTP specification, this interface includes properties for 9 * each of the following: 10 * 11 * - Protocol version 12 * - HTTP method 13 * - URI 14 * - Headers 15 * - Message body 16 * 17 * Additionally, it encapsulates all data as it has arrived to the 18 * application from the CGI and/or PHP environment, including: 19 * 20 * - The values represented in $_SERVER. 21 * - Any cookies provided (generally via $_COOKIE) 22 * - Query string arguments (generally via $_GET, or as parsed via parse_str()) 23 * - Upload files, if any (as represented by $_FILES) 24 * - Deserialized body parameters (generally from $_POST) 25 * 26 * $_SERVER values MUST be treated as immutable, as they represent application 27 * state at the time of request; as such, no methods are provided to allow 28 * modification of those values. The other values provide such methods, as they 29 * can be restored from $_SERVER or the request body, and may need treatment 30 * during the application (e.g., body parameters may be deserialized based on 31 * content type). 32 * 33 * Additionally, this interface recognizes the utility of introspecting a 34 * request to derive and match additional parameters (e.g., via URI path 35 * matching, decrypting cookie values, deserializing non-form-encoded body 36 * content, matching authorization headers to users, etc). These parameters 37 * are stored in an "attributes" property. 38 * 39 * Requests are considered immutable; all methods that might change state MUST 40 * be implemented such that they retain the internal state of the current 41 * message and return an instance that contains the changed state. 42 */ 43 interface ServerRequestInterface extends RequestInterface 44 { 45 /** 46 * Retrieve server parameters. 47 * 48 * Retrieves data related to the incoming request environment, 49 * typically derived from PHP's $_SERVER superglobal. The data IS NOT 50 * REQUIRED to originate from $_SERVER. 51 * 52 * @return array 53 */ 54 public function getServerParams(); 55 56 /** 57 * Retrieve cookies. 58 * 59 * Retrieves cookies sent by the client to the server. 60 * 61 * The data MUST be compatible with the structure of the $_COOKIE 62 * superglobal. 63 * 64 * @return array 65 */ 66 public function getCookieParams(); 67 68 /** 69 * Return an instance with the specified cookies. 70 * 71 * The data IS NOT REQUIRED to come from the $_COOKIE superglobal, but MUST 72 * be compatible with the structure of $_COOKIE. Typically, this data will 73 * be injected at instantiation. 74 * 75 * This method MUST NOT update the related Cookie header of the request 76 * instance, nor related values in the server params. 77 * 78 * This method MUST be implemented in such a way as to retain the 79 * immutability of the message, and MUST return an instance that has the 80 * updated cookie values. 81 * 82 * @param array $cookies Array of key/value pairs representing cookies. 83 * @return static 84 */ 85 public function withCookieParams(array $cookies); 86 87 /** 88 * Retrieve query string arguments. 89 * 90 * Retrieves the deserialized query string arguments, if any. 91 * 92 * Note: the query params might not be in sync with the URI or server 93 * params. If you need to ensure you are only getting the original 94 * values, you may need to parse the query string from `getUri()->getQuery()` 95 * or from the `QUERY_STRING` server param. 96 * 97 * @return array 98 */ 99 public function getQueryParams(); 100 101 /** 102 * Return an instance with the specified query string arguments. 103 * 104 * These values SHOULD remain immutable over the course of the incoming 105 * request. They MAY be injected during instantiation, such as from PHP's 106 * $_GET superglobal, or MAY be derived from some other value such as the 107 * URI. In cases where the arguments are parsed from the URI, the data 108 * MUST be compatible with what PHP's parse_str() would return for 109 * purposes of how duplicate query parameters are handled, and how nested 110 * sets are handled. 111 * 112 * Setting query string arguments MUST NOT change the URI stored by the 113 * request, nor the values in the server params. 114 * 115 * This method MUST be implemented in such a way as to retain the 116 * immutability of the message, and MUST return an instance that has the 117 * updated query string arguments. 118 * 119 * @param array $query Array of query string arguments, typically from 120 * $_GET. 121 * @return static 122 */ 123 public function withQueryParams(array $query); 124 125 /** 126 * Retrieve normalized file upload data. 127 * 128 * This method returns upload metadata in a normalized tree, with each leaf 129 * an instance of Psr\Http\Message\UploadedFileInterface. 130 * 131 * These values MAY be prepared from $_FILES or the message body during 132 * instantiation, or MAY be injected via withUploadedFiles(). 133 * 134 * @return array An array tree of UploadedFileInterface instances; an empty 135 * array MUST be returned if no data is present. 136 */ 137 public function getUploadedFiles(); 138 139 /** 140 * Create a new instance with the specified uploaded files. 141 * 142 * This method MUST be implemented in such a way as to retain the 143 * immutability of the message, and MUST return an instance that has the 144 * updated body parameters. 145 * 146 * @param array $uploadedFiles An array tree of UploadedFileInterface instances. 147 * @return static 148 * @throws \InvalidArgumentException if an invalid structure is provided. 149 */ 150 public function withUploadedFiles(array $uploadedFiles); 151 152 /** 153 * Retrieve any parameters provided in the request body. 154 * 155 * If the request Content-Type is either application/x-www-form-urlencoded 156 * or multipart/form-data, and the request method is POST, this method MUST 157 * return the contents of $_POST. 158 * 159 * Otherwise, this method may return any results of deserializing 160 * the request body content; as parsing returns structured content, the 161 * potential types MUST be arrays or objects only. A null value indicates 162 * the absence of body content. 163 * 164 * @return null|array|object The deserialized body parameters, if any. 165 * These will typically be an array or object. 166 */ 167 public function getParsedBody(); 168 169 /** 170 * Return an instance with the specified body parameters. 171 * 172 * These MAY be injected during instantiation. 173 * 174 * If the request Content-Type is either application/x-www-form-urlencoded 175 * or multipart/form-data, and the request method is POST, use this method 176 * ONLY to inject the contents of $_POST. 177 * 178 * The data IS NOT REQUIRED to come from $_POST, but MUST be the results of 179 * deserializing the request body content. Deserialization/parsing returns 180 * structured data, and, as such, this method ONLY accepts arrays or objects, 181 * or a null value if nothing was available to parse. 182 * 183 * As an example, if content negotiation determines that the request data 184 * is a JSON payload, this method could be used to create a request 185 * instance with the deserialized parameters. 186 * 187 * This method MUST be implemented in such a way as to retain the 188 * immutability of the message, and MUST return an instance that has the 189 * updated body parameters. 190 * 191 * @param null|array|object $data The deserialized body data. This will 192 * typically be in an array or object. 193 * @return static 194 * @throws \InvalidArgumentException if an unsupported argument type is 195 * provided. 196 */ 197 public function withParsedBody($data); 198 199 /** 200 * Retrieve attributes derived from the request. 201 * 202 * The request "attributes" may be used to allow injection of any 203 * parameters derived from the request: e.g., the results of path 204 * match operations; the results of decrypting cookies; the results of 205 * deserializing non-form-encoded message bodies; etc. Attributes 206 * will be application and request specific, and CAN be mutable. 207 * 208 * @return array Attributes derived from the request. 209 */ 210 public function getAttributes(); 211 212 /** 213 * Retrieve a single derived request attribute. 214 * 215 * Retrieves a single derived request attribute as described in 216 * getAttributes(). If the attribute has not been previously set, returns 217 * the default value as provided. 218 * 219 * This method obviates the need for a hasAttribute() method, as it allows 220 * specifying a default value to return if the attribute is not found. 221 * 222 * @see getAttributes() 223 * @param string $name The attribute name. 224 * @param mixed $default Default value to return if the attribute does not exist. 225 * @return mixed 226 */ 227 public function getAttribute($name, $default = null); 228 229 /** 230 * Return an instance with the specified derived request attribute. 231 * 232 * This method allows setting a single derived request attribute as 233 * described in getAttributes(). 234 * 235 * This method MUST be implemented in such a way as to retain the 236 * immutability of the message, and MUST return an instance that has the 237 * updated attribute. 238 * 239 * @see getAttributes() 240 * @param string $name The attribute name. 241 * @param mixed $value The value of the attribute. 242 * @return static 243 */ 244 public function withAttribute($name, $value); 245 246 /** 247 * Return an instance that removes the specified derived request attribute. 248 * 249 * This method allows removing a single derived request attribute as 250 * described in getAttributes(). 251 * 252 * This method MUST be implemented in such a way as to retain the 253 * immutability of the message, and MUST return an instance that removes 254 * the attribute. 255 * 256 * @see getAttributes() 257 * @param string $name The attribute name. 258 * @return static 259 */ 260 public function withoutAttribute($name); 261 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body