# Класс HttpSoft\Message\Uri

Класс, реализующий Psr\Http\Message\UriInterface.

Валидирует и нормализует компоненты URI в соответствии со спецификацией RFC 3986.

Объект HttpSoft\Message\Uri является неизменяемым. Вы можете использовать сеттеры (с префиксом with), которые возвращают новый экземпляр класса HttpSoft\Message\Uri с измененными данными.

Исходный код на 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;

# Публичные методы

Оригинальное подробное описание методов смотрите в Psr\Http\Message\UriInterface.

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

# __toString

Возвращает строковое представление URI.

public function __toString(): string;

При первом вызове метода генерируется и кэшируется строковое представление URI, а при повторных вызовах строка возвращается из кеша без генерации.

$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'

Если порт стандартный (80 при http-соединении или 443 при https-соединении), то он будет опущен.

# getScheme

Возвращает нормализованный компонент схемы из URI в соответствии с RFC 3986 Scheme.

public function getScheme(): string;

Пример возвращаемых значений: 'http', 'https', ''.

# getAuthority

Возвращает нормализованный компонент полномочий из URI в соответствии с RFC 3986 Authority.

public function getAuthority(): string;

Пример возвращаемых значений: 'us%3C%3Eer:pass@example.com:8080', 'example.com', ''.

# getUserInfo

Возвращает нормализованный компонент информации о пользователе из URI в соответствии с RFC 3986 User Information.

public function getUserInfo(): string;

Пример возвращаемых значений: 'user:password', 'us%3C%3Eer', ''.

# getHost

Возвращает нормализованный компонент хоста из URI в соответствии с RFC 3986 Host.

public function getHost(): string;

Пример возвращаемых значений: '127.0.0.1', 'example.com', ''.

# getPort

Возвращает нормализованный компонент порта из URI в соответствии с RFC 3986 Port.

public function getPort(): string;

Пример возвращаемых значений: 1, 65535, null.

Если порт стандартный (80 при http-соединении или 443 при https-соединении), то будет возвращен null.

# getPath

Возвращает нормализованный компонент пути из URI в соответствии с RFC 3986 Path.

public function getPath(): string;

Пример возвращаемых значений: '/path/to/act%3C%3Eion', '/', ''.

# getQuery

Возвращает нормализованный компонент строки запроса из URI в соответствии с RFC 3986 Query.

public function getQuery(): string;

Пример возвращаемых значений: 'key1=value1&key2=val%3C%3Eue2', 'qu%3C%3Eery', ''.

# getFragment

Возвращает нормализованный компонент фрагмента (хеша) из URI в соответствии с RFC 3986 Fragment.

public function getFragment(): string;

Пример возвращаемых значений: 'any-string', 'frag%3C%3Ement', ''.

# withScheme

Возвращает новый экземпляр HttpSoft\Message\Uri с указанным компонентом схемы URI в соответствии с RFC 3986 Scheme.

public function withScheme($scheme): self;

Если $scheme невалидная или неподдерживаемая, будет брошено исключение \InvalidArgumentException. Поддерживаемые схемы: 'http' и '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

Возвращает новый экземпляр HttpSoft\Message\Uri с указанным компонентом информации о пользователе URI в соответствии с RFC 3986 User Information.

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

Если $user пуст, userInfo будет равен пустой строке. Если не пуст $user и $pass, userInfo будет равен строке: 'user:pass'. Если не пуст $user, но пуст $pass, userInfo будет равен строке: '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

Возвращает новый экземпляр HttpSoft\Message\Uri с указанным компонентом хоста из URI в соответствии с RFC 3986 Host.

public function withHost($host): self;

Все заглавные латинские буквы будут приведены к строчным.

$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

Возвращает новый экземпляр HttpSoft\Message\Uri с указанным компонентом порта из URI в соответствии с RFC 3986 Port.

public function withPort($port): self;

Если $port не целое число (8080) или не число в строковом представлении ('8080'), или меньше 1, или больше 65535, или не равно null, будет брошено исключение \InvalidArgumentException.

$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

Возвращает новый экземпляр HttpSoft\Message\Uri с указанным компонентом пути из URI в соответствии с RFC 3986 Path.

public function withPath($path): self;

$path может быть либо пустым, либо абсолютным (начинаться со слэша), либо бескорневым (не начинаться со слэша).

$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

Возвращает новый экземпляр HttpSoft\Message\Uri с указанным компонентом строки запроса из URI в соответствии с RFC 3986 Query.

public function withQuery($query): self;

$query может быть либо пустым, либо начинаться со знака вопроса, либо не начинаться со знака вопроса.

$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

Возвращает новый экземпляр HttpSoft\Message\Uri с указанным компонентом фрагмента (хеша) из URI в соответствии с RFC 3986 Fragment.

public function withFragment($fragment): self;

$fragment может содержать любую строку, может начинаться с символа #, а может не начинаться с символа #.

$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'