[Summary view] [Print] [Text view]

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