# Class HttpSoft\Message\Uri

Class, that implements Psr\Http\Message\UriInterface.

Validates and normalizes components of the URI in accordance with the RFC 3986 specification.

The HttpSoft\Message\Uri object are immutable. You can use setters (with the with prefix) that return a new instance of the HttpSoft\Message\Uri class with the changed data.

Source code on GitHub.

use HttpSoft\Message\Uri;

$uri = new Uri('https://example.com/path/to/action?key1=value1&key2=val<>ue2#fragment');

$uri->getScheme(); // 'https'
$uri->getHost(); // 'example.com'

$uri->getPath(); // '/path/to/action'
$uriWithNewPath = $uri->withPath('new/path');
$uriWithNewPath->getPath(); // 'new/path'
$uri->getPath(); // '/path/to/action'

$uri->getQuery(); // 'key1=value1&key2=val%3C%3Eue2'
$uri->getFragment(); // 'fragment'

$uri->__toString(); // 'https://example.com/path/to/action?key1=value1&key2=val%3C%3Eue2#fragment'
// equivalently to:
(string) $uri; // echo $uri;

# Public methods

See the original detailed description of the methods in the Psr\Http\Message\UriInterface.

public function __construct(string $uri = '');

# __toString

Returns a string representation of the URI.

public function __toString(): string;

The first time the method is called, a string representation of the URI is generated and cached, and on repeated calls, the line is returned from the cache without generation.

$uri = new Uri('https://example.com/path');

$uri->__toString(); // 'https://example.com/path'
(string) $uri; // 'https://example.com/path'
echo $uri; // 'https://example.com/path'

If the port is standard (80 for http connection or 443 for https connection), it will be omitted.

# getScheme

Returns the normalized scheme component of the URI according to RFC 3986 Scheme.

public function getScheme(): string;

Example of returned values: 'http', 'https', ''.

# getAuthority

Returns the normalized authority component of the URI according to RFC 3986 Authority.

public function getAuthority(): string;

Example of returned values: 'us%3C%3Eer:pass@example.com:8080', 'example.com', ''.

# getUserInfo

Returns the normalized user information component of the URI according to RFC 3986 User Information.

public function getUserInfo(): string;

Example of returned values: 'user:password', 'us%3C%3Eer', ''.

# getHost

Returns the normalized host component of the URI according to RFC 3986 Host.

public function getHost(): string;

Example of returned values: '127.0.0.1', 'example.com', ''.

# getPort

Returns the normalized port component of the URI according to RFC 3986 Port.

public function getPort(): string;

Example of returned values: 1, 65535, null.

If the port is standard (80 for http connection or 443 for https connection), will be null returned.

# getPath

Returns the normalized path component of the URI according to RFC 3986 Path.

public function getPath(): string;

Example of returned values: '/path/to/act%3C%3Eion', '/', ''.

# getQuery

Returns the normalized query string component of the URI according to RFC 3986 Query.

public function getQuery(): string;

Example of returned values: 'key1=value1&key2=val%3C%3Eue2', 'qu%3C%3Eery', ''.

# getFragment

Returns the normalized fragment (hash)component of the URI according to RFC 3986 Fragment.

public function getFragment(): string;

Example of returned values: 'any-string', 'frag%3C%3Ement', ''.

# withScheme

Returns a new HttpSoft\Message\Uri instance with the specified scheme component of the URI according to RFC 3986 Scheme.

public function withScheme($scheme): self;

If $scheme invalid or unsupported, the \InvalidArgumentException exception will be thrown. Supported schemes: 'http' and 'https'.

$newUri = $uri->withScheme('http');
$newUri->getScheme(); // 'http'

$newUri = $uri->withScheme('https');
$newUri->getScheme(); // 'https'

$newUri = $uri->withScheme('https:');
$newUri->getScheme(); // 'https'

$newUri = $uri->withScheme('https://');
$newUri->getScheme(); // 'https'

$uri->withScheme('https:/'); // throws InvalidArgumentException
$uri->withScheme('invalid'); // throws InvalidArgumentException
$uri->withScheme('mailto'); // throws InvalidArgumentException
$uri->withScheme('file'); // throws InvalidArgumentException
$uri->withScheme('ftp'); // throws InvalidArgumentException
$uri->withScheme('ssh'); // throws InvalidArgumentException

# withUserInfo

Returns a new HttpSoft\Message\Uri instance with the specified user information component of the URI according to RFC 3986 User Information.

public function withUserInfo($user, $password = null): self;

If $user is empty, userInfo will be equal to an empty string. If $user and $pass are not empty, userInfo will be equal to a string 'user:pass'. If $user is not empty, but $pass is empty, will be equal to a string 'user'.

$newUri = $uri->withUserInfo('', 'password'); // ''
$newUri->getUserInfo(); // ''

$uri->withUserInfo('us<>er');
$newUri->getUserInfo(); // 'us%3C%3Eer'

$uri->withUserInfo('us%3C%3Eer');
$newUri->getUserInfo(); // 'us%3C%3Eer'

$uri->withUserInfo('user', 'password');
$newUri->getUserInfo(); // 'user:password'

# withHost

Returns a new HttpSoft\Message\Uri instance with the specified host component of the URI according to RFC 3986 Host.

public function withHost($host): self;

All uppercase Latin letters will be reduced to lowercase.

$newUri = $uri->withHost('127.0.0.1');
$newUri->getHost(); // '127.0.0.1'

$newUri = $uri->withHost('example.com');
$newUri->getHost(); // 'example.com'

$newUri = $uri->withHost('Example.org');
$newUri->getHost(); // 'example.org'

# withPort

Returns a new HttpSoft\Message\Uri instance with the specified port component of the URI according to RFC 3986 Port.

public function withPort($port): self;

If $port is not an integer (8080) or not a string representation number ('8080') or less than 1 or more than 65535 or not equal to null, the \InvalidArgumentException exception will be thrown.

$newUri = $uri->withPort(8080);
$newUri->getPort(); // 8080

$newUri = $uri->withPort('8080');
$newUri->getPort(); // 8080

$newUri = $uri->withPort('80.80');
$newUri->getPort(); // 80

$newUri = $uri->withPort(null);
$newUri->getPort(); // null

$uri->withPort(80.80); // throws InvalidArgumentException
$uri->withPort('string'); // throws InvalidArgumentException
$uri->withPort(0); // throws InvalidArgumentException
$uri->withPort('0'); // throws InvalidArgumentException
$uri->withPort(65536); // throws InvalidArgumentException
$uri->withPort('65536'); // throws InvalidArgumentException

# withPath

Returns a new HttpSoft\Message\Uri instance with the specified path component of the URI according to RFC 3986 Path.

public function withPath($path): self;

$path can either be empty or absolute (starting with a slash) or rootless (not starting with a slash).

$newUri = $uri->withPath('');
$newUri->getPath(); // ''

$newUri = $uri->withPath('/');
$newUri->getPath(); // '/'

$newUri = $uri->withPath('path/to/act<>ion');
$newUri->getPath(); // 'path/to/act%3C%3Eion'

$newUri = $uri->withPath('path/to/act%3C%3Eion');
$newUri->getPath(); // 'path/to/act%3C%3Eion'

$newUri = $uri->withPath('/path/to/action/');
$newUri->getPath(); // '/path/to/action/'

# withQuery

Returns a new HttpSoft\Message\Uri instance with the specified query string component of the URI according to RFC 3986 Query.

public function withQuery($query): self;

$query can either be empty or starting with a question mark or not starting with a question mark.

$newUri = $uri->withQuery('?qu<>ery');
$newUri->getQuery(); // 'qu%3C%3Eery'

$newUri = $uri->withQuery('?qu%3C%3Eery');
$newUri->getQuery(); // 'qu%3C%3Eery'

$newUri = $uri->withQuery('query=str<>ing');
$newUri->getQuery(); // 'query=str%3C%3Eing'

$newUri = $uri->withQuery('query=str%3C%3Eing');
$newUri->getQuery(); // 'query=str%3C%3Eing'

$newUri = $uri->withQuery('?key1=value1&key2=value2');
$newUri->getQuery(); // 'key1=value1&key2=value2'

# withFragment

Returns a new HttpSoft\Message\Uri instance with the specified fragment (hash) component of the URI according to RFC 3986 Fragment.

public function withFragment($fragment): self;

$fragment can contain any string, it can start with the # character, or it cannot start with the # character.

$newUri = $uri->withQuery('frag<>ment');
$newUri->getQuery(); // 'frag%3C%3Ement'

$newUri = $uri->withQuery('#frag<>ment');
$newUri->getQuery(); // 'frag%3C%3Ement'

$newUri = $uri->withQuery('#frag%3C%3Ement');
$newUri->getQuery(); // 'frag%3C%3Ement'