class Uri implements UriInterface (View source)

Immutable value object that represents a RFC3986 compliant URI.

Traits

Provides convenience methods for accessing the standard URI interface.

Methods

string
getScheme()

Returns the scheme component of the URI.

int|null
getStandardPort()

Returns the standard port for the current scheme.

string
getUserInfo()

Returns the user information component of the URI.

string
getUsername()

Returns the decoded username from the URI.

string
getPassword()

Returns the decoded password from the URI.

string
getHost()

Returns the host component of the URI.

string|null
getIpAddress()

Returns the IP address from the host component.

string
getTopLevelDomain()

Returns the top level domain from the host component.

string
getPath()

Returns the path component of the URI.

string[]
getPathSegments()

Returns the decoded path segments from the path component.

string
getPathExtension()

Returns the file extension for the last segment in the path.

string
getQuery()

Returns the query string of the URI.

array
getQueryParameters()

Returns the decoded parameters parsed from the query component.

Uri
withPath(string $path)

Returns a URI instance with the specified path.

withPathSegments(array $segments)

Returns a URI instance with path constructed from given path segments.

Uri
withQuery(string $query)

Returns a URI instance with the specified query string.

withQueryParameters(array $parameters)

Returns a URI instance with the query constructed from the given parameters.

__construct(string $uri = '', int $mode = UriParser::MODE_RFC3986)

Creates a new instance of Uri.

string
getAuthority()

Returns the authority component of the URI.

int|null
getPort()

Returns the port component of the URI.

string
getFragment()

Returns the fragment component of the URI.

Uri
withScheme(string $scheme)

Returns a URI instance with the specified scheme.

Uri
withUserInfo(string $user, string|null $password = null)

Returns a URI instance with the specified user information.

Uri
withHost(string $host)

Returns a URI instance with the specified host.

Uri
withPort(int|null $port)

Returns a URI instance with the specified port.

Uri
withFragment(string $fragment)

Returns a URI instance with the specified URI fragment.

string
__toString()

Returns the string representation of the URI.

Details

string getScheme()

Returns the scheme component of the URI.

Note that the returned value will always be normalized to lowercase, as per RFC 3986 Section 3.1. If no scheme has been provided, an empty string will be returned instead.

Return Value

string The URI scheme or an empty string if no scheme has been provided

See also

https://tools.ietf.org/html/rfc3986#section-3.1

int|null getStandardPort()

Returns the standard port for the current scheme.

The known ports are:

  • ftp : 21
  • http : 80
  • https : 443

Return Value

int|null The standard port for the current scheme or null if not known

string getUserInfo()

Returns the user information component of the URI.

The user information component contains the username and password in the URI separated by a colon. If no username has been provided, an empty string will be returned instead. If no password has been provided, the returned value will only contain the username without the delimiting colon.

Return Value

string The URI user information or an empty string if no username has been provided

See also

http://tools.ietf.org/html/rfc3986#section-3.2.1

string getUsername()

Returns the decoded username from the URI.

Return Value

string The decoded username

string getPassword()

Returns the decoded password from the URI.

Return Value

string The decoded password

string getHost()

Returns the host component of the URI.

Note that the returned value will always be normalized to lowercase, as per RFC 3986 Section 3.2.2. If no host has been provided, an empty string will be returned instead.

Return Value

string The URI host or an empty string if no host has been provided

See also

http://tools.ietf.org/html/rfc3986#section-3.2.2

string|null getIpAddress()

Returns the IP address from the host component.

Return Value

string|null IP address from the host or null if the host is not an IP address

string getTopLevelDomain()

Returns the top level domain from the host component.

Note that if the host component represents an IP address, an empty string will be returned instead. Additionally, if the host component ends in a period, the section prior that period will be returned instead. If no period is present in the host component, the entire host component will be returned.

Return Value

string The top level domain or an empty string, if no TLD is present

string getPath()

Returns the path component of the URI.

Return Value

string The URI path or an empty string if no path has been provided

See also

https://tools.ietf.org/html/rfc3986#section-3.3

string[] getPathSegments()

Returns the decoded path segments from the path component.

Return Value

string[] The decoded non empty path segments

string getPathExtension()

Returns the file extension for the last segment in the path.

Return Value

string The file extension from the last non empty segment

string getQuery()

Returns the query string of the URI.

Return Value

string The URI query string or an empty string if no query has been provided

See also

https://tools.ietf.org/html/rfc3986#section-3.4

array getQueryParameters()

Returns the decoded parameters parsed from the query component.

Return Value

array The decoded parameters parsed from the query

Uri withPath(string $path)

Returns a URI instance with the specified path.

The provided path may or may not begin with a forward slash. The path will be automatically normalized with the appropriate number of slashes once the string is generated from the Uri instance. An empty string can be used to remove the path. The path may also contain percent encoded characters as these characters will not be double encoded.

Parameters

string $path The path to use with the new instance

Return Value

Uri A new instance with the specified path

ExtendedUriTrait withPathSegments(array $segments)

Returns a URI instance with path constructed from given path segments.

Note that all the segments are assumed to be decoded. Thus any percent encoded characters in the segments will be double encoded. Due to aggressive encoding, this method will encode even the forward slashes in the provided segments.

Parameters

array $segments Path segments for the new path

Return Value

ExtendedUriTrait A new instance with the specified path

Uri withQuery(string $query)

Returns a URI instance with the specified query string.

An empty string can be used to remove the query string. The provided value may contain both encoded and unencoded characters. Encoded characters will not be double encoded.

Parameters

string $query The query string to use with the new instance

Return Value

Uri A new instance with the specified query string

ExtendedUriTrait withQueryParameters(array $parameters)

Returns a URI instance with the query constructed from the given parameters.

The provided associative array will be used to construct the query string. Even characters such as the ampersand and equal sign will be encoded in resulting string. Note the any percent encoded characters will be double encoded, since this method assumes that all the values are unencoded.

Parameters

array $parameters Parameters for the query

Return Value

ExtendedUriTrait A new instance with the specified query string

__construct(string $uri = '', int $mode = UriParser::MODE_RFC3986)

Creates a new instance of Uri.

Parameters

string $uri The URI provided as a string or empty string for none
int $mode The parser mode used to parse the provided URI

Exceptions

InvalidArgumentException If the provided URI is invalid

string getAuthority()

Returns the authority component of the URI.

If no authority information has been provided, an empty string will be returned instead. Note that the host component in the authority component will always be normalized to lowercase as per RFC 3986 Section 3.2.2.

Also note that even if a port has been provided, but it is the standard port for the current scheme, the port will not be included in the returned value.

The format of the returned value is [user-info@]host[:port]

Return Value

string The URI authority or an empty string if no authority information has been provided

See also

https://tools.ietf.org/html/rfc3986#section-3.2

int|null getPort()

Returns the port component of the URI.

If no port has been provided, this method will return a null instead. Note that this method will also return a null, if the provided port is the standard port for the current scheme.

Return Value

int|null The URI port or null if no port has been provided

See also

http://tools.ietf.org/html/rfc3986#section-3.2.3

string getFragment()

Returns the fragment component of the URI.

Return Value

string The URI fragment or an empty string if no fragment has been provided

See also

https://tools.ietf.org/html/rfc3986#section-3.5

Uri withScheme(string $scheme)

Returns a URI instance with the specified scheme.

This method allows all different kinds of schemes. Note, however, that the different components are only validated based on the generic URI syntax. No additional validation is performed based on the scheme. An empty string can be used to remove the scheme. Note that the provided scheme will be normalized to lowercase.

Parameters

string $scheme The scheme to use with the new instance

Return Value

Uri A new instance with the specified scheme

Exceptions

InvalidArgumentException If the scheme is invalid

Uri withUserInfo(string $user, string|null $password = null)

Returns a URI instance with the specified user information.

Note that the password is optional, but unless an username is provided, the password will be ignored. Note that this method assumes that neither the username nor the password contains encoded characters. Thus, all encoded characters will be double encoded, if present. An empty username can be used to remove the user information.

Parameters

string $user The username to use for the authority component
string|null $password The password associated with the user

Return Value

Uri A new instance with the specified user information

Uri withHost(string $host)

Returns a URI instance with the specified host.

An empty host can be used to remove the host. Note that since host names are treated in a case insensitive manner, the host will be normalized to lowercase. This method does not support international domain names and hosts with non ascii characters are considered invalid.

Parameters

string $host The hostname to use with the new instance

Return Value

Uri A new instance with the specified host

Exceptions

InvalidArgumentException If the hostname is invalid

Uri withPort(int|null $port)

Returns a URI instance with the specified port.

A null value can be used to remove the port number. Note that if an invalid port number is provided (a number less than 0 or more than 65535), an exception will be thrown.

Parameters

int|null $port The port to use with the new instance

Return Value

Uri A new instance with the specified port

Exceptions

InvalidArgumentException If the port is invalid

Uri withFragment(string $fragment)

Returns a URI instance with the specified URI fragment.

An empty string can be used to remove the fragment. The provided value may contain both encoded and unencoded characters. Encoded characters will not be double encoded.

Parameters

string $fragment The fragment to use with the new instance

Return Value

Uri A new instance with the specified fragment

string __toString()

Returns the string representation of the URI.

The resulting URI will be composed of the provided components. All components that have not been provided will be omitted from the generated URI. The provided path will be normalized based on whether the authority is included in the URI or not.

Return Value

string The string representation of the URI