PHPFUI/InstaDoc
 
Copied!

PSR-7 URI implementation.

CloneableInstantiable
  • Implements
    JsonSerializable
    Psr\Http\Message\UriInterface
    Stringable
Methods
public __construct(string $uri = '')
public __toString() : string
public static composeComponents(?string $scheme, ?string $authority, string $path, ?string $query, ?string $fragment) : string
 

Composes a URI reference string from its various components.

Usually this method does not need to be called manually but instead is used indirectly via Psr\Http\Message\UriInterface::__toString.

PSR-7 UriInterface treats an empty component the same as a missing component as getQuery(), getFragment() etc. always return a string. This explains the slight difference to RFC 3986 Section 5.3.

Another adjustment is that the authority separator is added even when the authority is missing/empty for the "file" scheme. This is because PHP stream functions like file_get_contents only work with file:///myfile but not with file:/myfile although they are equivalent according to RFC 3986. But file:/// is the more common syntax for the file scheme anyway (Chrome for example redirects to that format).

  • see https://datatracker.ietf.org/doc/html/rfc3986#section-5.3
public static fromParts(array $parts) : Psr\Http\Message\UriInterface
 

Creates a URI from a hash of parse_url components.

  • see https://www.php.net/manual/en/function.parse-url.php
  • throws \MalformedUriException If the components do not form a valid URI.
public getAuthority() : string
public getFragment() : string
public getHost() : string
public getPath() : string
public getPort() : ?int
public getQuery() : string
public getScheme() : string
public getUserInfo() : string
public static isAbsolute(Psr\Http\Message\UriInterface $uri) : bool
 

Whether the URI is absolute, i.e. it has a scheme.

An instance of UriInterface can either be an absolute URI or a relative reference. This method returns true if it is the former. An absolute URI has a scheme. A relative reference is used to express a URI relative to another URI, the base URI. Relative references can be divided into several forms:

  • network-path references, e.g. '//example.com/path'
  • absolute-path references, e.g. '/path'
  • relative-path references, e.g. 'subpath'
  • see \Uri::isNetworkPathReference
  • see \Uri::isAbsolutePathReference
  • see \Uri::isRelativePathReference
  • see https://datatracker.ietf.org/doc/html/rfc3986#section-4
public static isAbsolutePathReference(Psr\Http\Message\UriInterface $uri) : bool
 

Whether the URI is a absolute-path reference.

A relative reference that begins with a single slash character is termed an absolute-path reference.

  • see https://datatracker.ietf.org/doc/html/rfc3986#section-4.2
public static isDefaultPort(Psr\Http\Message\UriInterface $uri) : bool
 

Whether the URI has the default port of the current scheme.

Psr\Http\Message\UriInterface::getPort may return null or the standard port. This method can be used independently of the implementation.

public static isNetworkPathReference(Psr\Http\Message\UriInterface $uri) : bool
 

Whether the URI is a network-path reference.

A relative reference that begins with two slash characters is termed an network-path reference.

  • see https://datatracker.ietf.org/doc/html/rfc3986#section-4.2
public static isRelativePathReference(Psr\Http\Message\UriInterface $uri) : bool
 

Whether the URI is a relative-path reference.

A relative reference that does not begin with a slash character is termed a relative-path reference.

  • see https://datatracker.ietf.org/doc/html/rfc3986#section-4.2
public static isSameDocumentReference(Psr\Http\Message\UriInterface $uri, ?Psr\Http\Message\UriInterface $base = NULL) : bool
 

Whether the URI is a same-document reference.

A same-document reference refers to a URI that is, aside from its fragment component, identical to the base URI. When no base URI is given, only an empty URI reference (apart from its fragment) is considered a same-document reference.

  • param \UriInterface $uri The URI to check
  • param \UriInterface|null $base An optional base URI to compare against
  • see https://datatracker.ietf.org/doc/html/rfc3986#section-4.4
public jsonSerialize() : string
public withFragment( $fragment) : Psr\Http\Message\UriInterface
public withHost( $host) : Psr\Http\Message\UriInterface
public static withoutQueryValue(Psr\Http\Message\UriInterface $uri, string $key) : Psr\Http\Message\UriInterface
 

Creates a new URI with a specific query string value removed.

Any existing query string values that exactly match the provided key are removed.

  • param \UriInterface $uri URI to use as a base.
  • param string $key Query string key to remove.
public withPath( $path) : Psr\Http\Message\UriInterface
public withPort( $port) : Psr\Http\Message\UriInterface
public withQuery( $query) : Psr\Http\Message\UriInterface
public static withQueryValue(Psr\Http\Message\UriInterface $uri, string $key, ?string $value) : Psr\Http\Message\UriInterface
 

Creates a new URI with a specific query string value.

Any existing query string values that exactly match the provided key are removed and replaced with the given key value pair.

A value of null will set the query string key without a value, e.g. "key" instead of "key=value".

  • param \UriInterface $uri URI to use as a base.
  • param string $key Key to set.
  • param string|null $value Value to set
public static withQueryValues(Psr\Http\Message\UriInterface $uri, array $keyValueArray) : Psr\Http\Message\UriInterface
 

Creates a new URI with multiple specific query string values.

It has the same behavior as withQueryValue() but for an associative array of key => value.

  • param \UriInterface $uri URI to use as a base.
  • param (string|null)[] $keyValueArray Associative array of key and values
public withScheme( $scheme) : Psr\Http\Message\UriInterface
public withUserInfo( $user, $password = NULL) : Psr\Http\Message\UriInterface
Constants
private GuzzleHttp\Psr7\Uri::CHAR_SUB_DELIMS = '!\$&'\(\)\*\+,;='
 

Sub-delims for use in a regex.

  • see https://datatracker.ietf.org/doc/html/rfc3986#section-2.2
private GuzzleHttp\Psr7\Uri::CHAR_UNRESERVED = 'a-zA-Z0-9_\-\.~'
 

Unreserved characters for use in a regex.

  • see https://datatracker.ietf.org/doc/html/rfc3986#section-2.3
private GuzzleHttp\Psr7\Uri::DEFAULT_PORTS = ['http' => 80, 'https' => 443, 'ftp' => 21, 'gopher' => 70, 'nntp' => 119, 'news' => 119, 'telnet' => 23, 'tn3270' => 23, 'imap' => 143, 'pop' => 110, 'ldap' => 389]
private GuzzleHttp\Psr7\Uri::HTTP_DEFAULT_HOST = 'localhost'
 

Absolute http and https URIs require a host per RFC 7230 Section 2.7 but in generic URIs the host can be empty. So for http(s) URIs we apply this default host when no host is given yet to form a valid URI.

private GuzzleHttp\Psr7\Uri::QUERY_SEPARATORS_REPLACEMENT = ['=' => '%3D', '&' => '%26']
Properties
private $composedComponents = NULL
 
  • var string|null String representation
private $fragment = ''
 
  • var string Uri fragment.
private $host = ''
 
  • var string Uri host.
private $path = ''
 
  • var string Uri path.
private $port = NULL
 
  • var int|null Uri port.
private $query = ''
 
  • var string Uri query string.
private $scheme = ''
 
  • var string Uri scheme.
private $userInfo = ''
 
  • var string Uri user info.
Methods
private applyParts(array $parts) : void
 

Apply parse_url parts to a URI.

  • param array $parts Array of parse_url parts to apply.
private filterHost( $host) : string
 
  • param mixed $host
  • throws \InvalidArgumentException If the host is invalid.
private filterPath( $path) : string
 

Filters the path of a URI

  • param mixed $path
  • throws \InvalidArgumentException If the path is invalid.
private filterPort( $port) : ?int
 
  • param mixed $port
  • throws \InvalidArgumentException If the port is invalid.
private filterQueryAndFragment( $str) : string
 

Filters the query string or fragment of a URI.

  • param mixed $str
  • throws \InvalidArgumentException If the query or fragment is invalid.
private filterScheme( $scheme) : string
 
  • param mixed $scheme
  • throws \InvalidArgumentException If the scheme is invalid.
private filterUserInfoComponent( $component) : string
 
  • param mixed $component
  • throws \InvalidArgumentException If the user info is invalid.
private static generateQueryString(string $key, ?string $value) : string
private static getFilteredQueryString(Psr\Http\Message\UriInterface $uri, array $keys) : array
 
  • param (string|int)[] $keys
  • return string[]
private static parse(string $url)
 

UTF-8 aware \parse_url() replacement.

The internal function produces broken output for non ASCII domain names (IDN) when used with locales other than "C".

On the other hand, cURL understands IDN correctly only when UTF-8 locale is configured ("C.UTF-8", "en_US.UTF-8", etc.).

  • see https://bugs.php.net/bug.php?id=52923
  • see https://www.php.net/manual/en/function.parse-url.php#114817
  • see https://curl.haxx.se/libcurl/c/CURLOPT_URL.html#ENCODING
  • return array|false
private rawurlencodeMatchZero(array $match) : string
private removeDefaultPort() : void
private validateState() : void
Methods
public static composeComponents(?string $scheme, ?string $authority, string $path, ?string $query, ?string $fragment) : string
 

Composes a URI reference string from its various components.

Usually this method does not need to be called manually but instead is used indirectly via Psr\Http\Message\UriInterface::__toString.

PSR-7 UriInterface treats an empty component the same as a missing component as getQuery(), getFragment() etc. always return a string. This explains the slight difference to RFC 3986 Section 5.3.

Another adjustment is that the authority separator is added even when the authority is missing/empty for the "file" scheme. This is because PHP stream functions like file_get_contents only work with file:///myfile but not with file:/myfile although they are equivalent according to RFC 3986. But file:/// is the more common syntax for the file scheme anyway (Chrome for example redirects to that format).

  • see https://datatracker.ietf.org/doc/html/rfc3986#section-5.3
public static fromParts(array $parts) : Psr\Http\Message\UriInterface
 

Creates a URI from a hash of parse_url components.

  • see https://www.php.net/manual/en/function.parse-url.php
  • throws \MalformedUriException If the components do not form a valid URI.
private static generateQueryString(string $key, ?string $value) : string
private static getFilteredQueryString(Psr\Http\Message\UriInterface $uri, array $keys) : array
 
  • param (string|int)[] $keys
  • return string[]
public static isAbsolute(Psr\Http\Message\UriInterface $uri) : bool
 

Whether the URI is absolute, i.e. it has a scheme.

An instance of UriInterface can either be an absolute URI or a relative reference. This method returns true if it is the former. An absolute URI has a scheme. A relative reference is used to express a URI relative to another URI, the base URI. Relative references can be divided into several forms:

  • network-path references, e.g. '//example.com/path'
  • absolute-path references, e.g. '/path'
  • relative-path references, e.g. 'subpath'
  • see \Uri::isNetworkPathReference
  • see \Uri::isAbsolutePathReference
  • see \Uri::isRelativePathReference
  • see https://datatracker.ietf.org/doc/html/rfc3986#section-4
public static isAbsolutePathReference(Psr\Http\Message\UriInterface $uri) : bool
 

Whether the URI is a absolute-path reference.

A relative reference that begins with a single slash character is termed an absolute-path reference.

  • see https://datatracker.ietf.org/doc/html/rfc3986#section-4.2
public static isDefaultPort(Psr\Http\Message\UriInterface $uri) : bool
 

Whether the URI has the default port of the current scheme.

Psr\Http\Message\UriInterface::getPort may return null or the standard port. This method can be used independently of the implementation.

public static isNetworkPathReference(Psr\Http\Message\UriInterface $uri) : bool
 

Whether the URI is a network-path reference.

A relative reference that begins with two slash characters is termed an network-path reference.

  • see https://datatracker.ietf.org/doc/html/rfc3986#section-4.2
public static isRelativePathReference(Psr\Http\Message\UriInterface $uri) : bool
 

Whether the URI is a relative-path reference.

A relative reference that does not begin with a slash character is termed a relative-path reference.

  • see https://datatracker.ietf.org/doc/html/rfc3986#section-4.2
public static isSameDocumentReference(Psr\Http\Message\UriInterface $uri, ?Psr\Http\Message\UriInterface $base = NULL) : bool
 

Whether the URI is a same-document reference.

A same-document reference refers to a URI that is, aside from its fragment component, identical to the base URI. When no base URI is given, only an empty URI reference (apart from its fragment) is considered a same-document reference.

  • param \UriInterface $uri The URI to check
  • param \UriInterface|null $base An optional base URI to compare against
  • see https://datatracker.ietf.org/doc/html/rfc3986#section-4.4
private static parse(string $url)
 

UTF-8 aware \parse_url() replacement.

The internal function produces broken output for non ASCII domain names (IDN) when used with locales other than "C".

On the other hand, cURL understands IDN correctly only when UTF-8 locale is configured ("C.UTF-8", "en_US.UTF-8", etc.).

  • see https://bugs.php.net/bug.php?id=52923
  • see https://www.php.net/manual/en/function.parse-url.php#114817
  • see https://curl.haxx.se/libcurl/c/CURLOPT_URL.html#ENCODING
  • return array|false
public static withoutQueryValue(Psr\Http\Message\UriInterface $uri, string $key) : Psr\Http\Message\UriInterface
 

Creates a new URI with a specific query string value removed.

Any existing query string values that exactly match the provided key are removed.

  • param \UriInterface $uri URI to use as a base.
  • param string $key Query string key to remove.
public static withQueryValue(Psr\Http\Message\UriInterface $uri, string $key, ?string $value) : Psr\Http\Message\UriInterface
 

Creates a new URI with a specific query string value.

Any existing query string values that exactly match the provided key are removed and replaced with the given key value pair.

A value of null will set the query string key without a value, e.g. "key" instead of "key=value".

  • param \UriInterface $uri URI to use as a base.
  • param string $key Key to set.
  • param string|null $value Value to set
public static withQueryValues(Psr\Http\Message\UriInterface $uri, array $keyValueArray) : Psr\Http\Message\UriInterface
 

Creates a new URI with multiple specific query string values.

It has the same behavior as withQueryValue() but for an associative array of key => value.

  • param \UriInterface $uri URI to use as a base.
  • param (string|null)[] $keyValueArray Associative array of key and values
© 2024 Bruce Wells
Search Namespaces \ Classes
Configuration