[Summary view] [Print] [Text view]

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