See Release Notes
Long Term Support Release
1 <?php 2 namespace Psr\Http\Message; 3 4 /** 5 * Value object representing a URI. 6 * 7 * This interface is meant to represent URIs according to RFC 3986 and to 8 * provide methods for most common operations. Additional functionality for 9 * working with URIs can be provided on top of the interface or externally. 10 * Its primary use is for HTTP requests, but may also be used in other 11 * contexts. 12 * 13 * Instances of this interface are considered immutable; all methods that 14 * might change state MUST be implemented such that they retain the internal 15 * state of the current instance and return an instance that contains the 16 * changed state. 17 * 18 * Typically the Host header will be also be present in the request message. 19 * For server-side requests, the scheme will typically be discoverable in the 20 * server parameters. 21 * 22 * @link http://tools.ietf.org/html/rfc3986 (the URI specification) 23 */ 24 interface UriInterface 25 { 26 /** 27 * Retrieve the scheme component of the URI. 28 * 29 * If no scheme is present, this method MUST return an empty string. 30 * 31 * The value returned MUST be normalized to lowercase, per RFC 3986 32 * Section 3.1. 33 * 34 * The trailing ":" character is not part of the scheme and MUST NOT be 35 * added. 36 * 37 * @see https://tools.ietf.org/html/rfc3986#section-3.1 38 * @return string The URI scheme. 39 */ 40 public function getScheme(); 41 42 /** 43 * Retrieve the authority component of the URI. 44 * 45 * If no authority information is present, this method MUST return an empty 46 * string. 47 * 48 * The authority syntax of the URI is: 49 * 50 * <pre> 51 * [user-info@]host[:port] 52 * </pre> 53 * 54 * If the port component is not set or is the standard port for the current 55 * scheme, it SHOULD NOT be included. 56 * 57 * @see https://tools.ietf.org/html/rfc3986#section-3.2 58 * @return string The URI authority, in "[user-info@]host[:port]" format. 59 */ 60 public function getAuthority(); 61 62 /** 63 * Retrieve the user information component of the URI. 64 * 65 * If no user information is present, this method MUST return an empty 66 * string. 67 * 68 * If a user is present in the URI, this will return that value; 69 * additionally, if the password is also present, it will be appended to the 70 * user value, with a colon (":") separating the values. 71 * 72 * The trailing "@" character is not part of the user information and MUST 73 * NOT be added. 74 * 75 * @return string The URI user information, in "username[:password]" format. 76 */ 77 public function getUserInfo(); 78 79 /** 80 * Retrieve the host component of the URI. 81 * 82 * If no host is present, this method MUST return an empty string. 83 * 84 * The value returned MUST be normalized to lowercase, per RFC 3986 85 * Section 3.2.2. 86 * 87 * @see http://tools.ietf.org/html/rfc3986#section-3.2.2 88 * @return string The URI host. 89 */ 90 public function getHost(); 91 92 /** 93 * Retrieve the port component of the URI. 94 * 95 * If a port is present, and it is non-standard for the current scheme, 96 * this method MUST return it as an integer. If the port is the standard port 97 * used with the current scheme, this method SHOULD return null. 98 * 99 * If no port is present, and no scheme is present, this method MUST return 100 * a null value. 101 * 102 * If no port is present, but a scheme is present, this method MAY return 103 * the standard port for that scheme, but SHOULD return null. 104 * 105 * @return null|int The URI port. 106 */ 107 public function getPort(); 108 109 /** 110 * Retrieve the path component of the URI. 111 * 112 * The path can either be empty or absolute (starting with a slash) or 113 * rootless (not starting with a slash). Implementations MUST support all 114 * three syntaxes. 115 * 116 * Normally, the empty path "" and absolute path "/" are considered equal as 117 * defined in RFC 7230 Section 2.7.3. But this method MUST NOT automatically 118 * do this normalization because in contexts with a trimmed base path, e.g. 119 * the front controller, this difference becomes significant. It's the task 120 * of the user to handle both "" and "/". 121 * 122 * The value returned MUST be percent-encoded, but MUST NOT double-encode 123 * any characters. To determine what characters to encode, please refer to 124 * RFC 3986, Sections 2 and 3.3. 125 * 126 * As an example, if the value should include a slash ("/") not intended as 127 * delimiter between path segments, that value MUST be passed in encoded 128 * form (e.g., "%2F") to the instance. 129 * 130 * @see https://tools.ietf.org/html/rfc3986#section-2 131 * @see https://tools.ietf.org/html/rfc3986#section-3.3 132 * @return string The URI path. 133 */ 134 public function getPath(); 135 136 /** 137 * Retrieve the query string of the URI. 138 * 139 * If no query string is present, this method MUST return an empty string. 140 * 141 * The leading "?" character is not part of the query and MUST NOT be 142 * added. 143 * 144 * The value returned MUST be percent-encoded, but MUST NOT double-encode 145 * any characters. To determine what characters to encode, please refer to 146 * RFC 3986, Sections 2 and 3.4. 147 * 148 * As an example, if a value in a key/value pair of the query string should 149 * include an ampersand ("&") not intended as a delimiter between values, 150 * that value MUST be passed in encoded form (e.g., "%26") to the instance. 151 * 152 * @see https://tools.ietf.org/html/rfc3986#section-2 153 * @see https://tools.ietf.org/html/rfc3986#section-3.4 154 * @return string The URI query string. 155 */ 156 public function getQuery(); 157 158 /** 159 * Retrieve the fragment component of the URI. 160 * 161 * If no fragment is present, this method MUST return an empty string. 162 * 163 * The leading "#" character is not part of the fragment and MUST NOT be 164 * added. 165 * 166 * The value returned MUST be percent-encoded, but MUST NOT double-encode 167 * any characters. To determine what characters to encode, please refer to 168 * RFC 3986, Sections 2 and 3.5. 169 * 170 * @see https://tools.ietf.org/html/rfc3986#section-2 171 * @see https://tools.ietf.org/html/rfc3986#section-3.5 172 * @return string The URI fragment. 173 */ 174 public function getFragment(); 175 176 /** 177 * Return an instance with the specified scheme. 178 * 179 * This method MUST retain the state of the current instance, and return 180 * an instance that contains the specified scheme. 181 * 182 * Implementations MUST support the schemes "http" and "https" case 183 * insensitively, and MAY accommodate other schemes if required. 184 * 185 * An empty scheme is equivalent to removing the scheme. 186 * 187 * @param string $scheme The scheme to use with the new instance. 188 * @return static A new instance with the specified scheme. 189 * @throws \InvalidArgumentException for invalid or unsupported schemes. 190 */ 191 public function withScheme($scheme); 192 193 /** 194 * Return an instance with the specified user information. 195 * 196 * This method MUST retain the state of the current instance, and return 197 * an instance that contains the specified user information. 198 * 199 * Password is optional, but the user information MUST include the 200 * user; an empty string for the user is equivalent to removing user 201 * information. 202 * 203 * @param string $user The user name to use for authority. 204 * @param null|string $password The password associated with $user. 205 * @return static A new instance with the specified user information. 206 */ 207 public function withUserInfo($user, $password = null); 208 209 /** 210 * Return an instance with the specified host. 211 * 212 * This method MUST retain the state of the current instance, and return 213 * an instance that contains the specified host. 214 * 215 * An empty host value is equivalent to removing the host. 216 * 217 * @param string $host The hostname to use with the new instance. 218 * @return static A new instance with the specified host. 219 * @throws \InvalidArgumentException for invalid hostnames. 220 */ 221 public function withHost($host); 222 223 /** 224 * Return an instance with the specified port. 225 * 226 * This method MUST retain the state of the current instance, and return 227 * an instance that contains the specified port. 228 * 229 * Implementations MUST raise an exception for ports outside the 230 * established TCP and UDP port ranges. 231 * 232 * A null value provided for the port is equivalent to removing the port 233 * information. 234 * 235 * @param null|int $port The port to use with the new instance; a null value 236 * removes the port information. 237 * @return static A new instance with the specified port. 238 * @throws \InvalidArgumentException for invalid ports. 239 */ 240 public function withPort($port); 241 242 /** 243 * Return an instance with the specified path. 244 * 245 * This method MUST retain the state of the current instance, and return 246 * an instance that contains the specified path. 247 * 248 * The path can either be empty or absolute (starting with a slash) or 249 * rootless (not starting with a slash). Implementations MUST support all 250 * three syntaxes. 251 * 252 * If the path is intended to be domain-relative rather than path relative then 253 * it must begin with a slash ("/"). Paths not starting with a slash ("/") 254 * are assumed to be relative to some base path known to the application or 255 * consumer. 256 * 257 * Users can provide both encoded and decoded path characters. 258 * Implementations ensure the correct encoding as outlined in getPath(). 259 * 260 * @param string $path The path to use with the new instance. 261 * @return static A new instance with the specified path. 262 * @throws \InvalidArgumentException for invalid paths. 263 */ 264 public function withPath($path); 265 266 /** 267 * Return an instance with the specified query string. 268 * 269 * This method MUST retain the state of the current instance, and return 270 * an instance that contains the specified query string. 271 * 272 * Users can provide both encoded and decoded query characters. 273 * Implementations ensure the correct encoding as outlined in getQuery(). 274 * 275 * An empty query string value is equivalent to removing the query string. 276 * 277 * @param string $query The query string to use with the new instance. 278 * @return static A new instance with the specified query string. 279 * @throws \InvalidArgumentException for invalid query strings. 280 */ 281 public function withQuery($query); 282 283 /** 284 * Return an instance with the specified URI fragment. 285 * 286 * This method MUST retain the state of the current instance, and return 287 * an instance that contains the specified URI fragment. 288 * 289 * Users can provide both encoded and decoded fragment characters. 290 * Implementations ensure the correct encoding as outlined in getFragment(). 291 * 292 * An empty fragment value is equivalent to removing the fragment. 293 * 294 * @param string $fragment The fragment to use with the new instance. 295 * @return static A new instance with the specified fragment. 296 */ 297 public function withFragment($fragment); 298 299 /** 300 * Return the string representation as a URI reference. 301 * 302 * Depending on which components of the URI are present, the resulting 303 * string is either a full URI or relative reference according to RFC 3986, 304 * Section 4.1. The method concatenates the various components of the URI, 305 * using the appropriate delimiters: 306 * 307 * - If a scheme is present, it MUST be suffixed by ":". 308 * - If an authority is present, it MUST be prefixed by "//". 309 * - The path can be concatenated without delimiters. But there are two 310 * cases where the path has to be adjusted to make the URI reference 311 * valid as PHP does not allow to throw an exception in __toString(): 312 * - If the path is rootless and an authority is present, the path MUST 313 * be prefixed by "/". 314 * - If the path is starting with more than one "/" and no authority is 315 * present, the starting slashes MUST be reduced to one. 316 * - If a query is present, it MUST be prefixed by "?". 317 * - If a fragment is present, it MUST be prefixed by "#". 318 * 319 * @see http://tools.ietf.org/html/rfc3986#section-4.1 320 * @return string 321 */ 322 public function __toString(); 323 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body