[Summary view]

   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  }