# Класс HttpSoft\Uri\Uri

Флагманский класс пакета HttpSoft\Uri, непосредственно реализующий Psr\Http\Message\UriInterface.

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

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

Исходный код на GitHub.

use HttpSoft\Uri\Uri;

$uri = new Uri('https://example.com/path/to/action?key1=value&key2=значение');

$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=value&key2=%D0%B7%D0%BD%D0%B0%D1%87%D0%B5%D0%BD%D0%B8%D0%B5'
$uri->getRawQuery(); // 'key1=value&key2=значение'

$uri->get(); // 'https://example.com/path/to/action?key1=value&key2=%D0%B7%D0%BD%D0%B0%D1%87%D0%B5%D0%BD%D0%B8%D0%B5'
// эквивалентно:
(string) $uri; // echo $uri;
// незакодированная:
$uri->raw(); // 'https://example.com/path/to/action?key1=value&key2=значение'

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

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

public function __construct(string $uri = UriData::EMPTY_STRING, UriNormalizerInterface $normalizer = null);

Для нормализации компонентов URI внутри HttpSoft\Uri\Uri используется HttpSoft\Uri\UriNormalizer по умолчанию, вы можете создать собственный нормалайзер, реализовав интерфейс HttpSoft\Uri\UriNormalizerInterface.

# get

Возвращает строковое представление URI. Используется внутри метода __toString().

public function get(): string;

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

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

$uri->get(); // '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-соединении), то он будет опущен.

# raw

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

public function raw(): string;

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

$uri = new Uri('https://example.com/pa<>th');

$uri->get(); // 'https://example.com/pa%3C%3Eth'
$uri->__toString(); // 'https://example.com/pa%3C%3Eth'
(string) $uri; // 'https://example.com/pa%3C%3Eth'
echo $uri; // 'https://example.com/pa%3C%3Eth'

$uri->raw(); // 'https://example.com/pa<>th'

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

# getScheme

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

public function getScheme(): string;

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

# getRawScheme

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

public function getRawScheme(): string;

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

# getAuthority

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

public function getAuthority(): string;

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

# getRawAuthority

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

public function getRawAuthority(): string;

Пример возвращаемых значений: 'us<>er:pass@example.com:8080', 'Example.com', ''.

# getUserInfo

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

public function getUserInfo(): string;

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

# getRawUserInfo

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

public function getRawUserInfo(): string;

Пример возвращаемых значений: 'user:password', 'us<>er', ''.

# getHost

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

public function getHost(): string;

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

# getRawHost

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

public function getRawHost(): string;

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

# getPort

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

public function getPort(): string;

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

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

# getRawPort

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

public function getRawPort(): string;

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

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

# getPath

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

public function getPath(): string;

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

# getRawPath

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

public function getRawPath(): string;

Пример возвращаемых значений: '/path/to/action', '/', ''.

# getQuery

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

public function getQuery(): string;

Пример возвращаемых значений: 'key1=value1&key2=value2', 'qu%24ery', ''.

# getRawQuery

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

public function getRawQuery(): string;

Пример возвращаемых значений: '?key1=value1&key2=value2', 'qu$ery', ''.

# getFragment

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

public function getFragment(): string;

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

# getRawFragment

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

public function getRawFragment(): string;

Пример возвращаемых значений: '#any-string', 'frag<>ment', ''.

# withScheme

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

public function withScheme($scheme): UriInterface;

Если $scheme невалидная или неподдерживаемая, будет брошено исключение \InvalidArgumentException. Поддерживаемые схемы: 'http' и 'https'.

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

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

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

$newUri = $uri->withScheme('https://');
$newUri->getScheme(); // 'https'
$newUri->getRawScheme(); // '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\Uri\Uri с указанным компонентом информации о пользователе URI в соответствии с RFC 3986 User Information.

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

Если $user пуст, userInfo будет равен пустой строке. Если не пуст $user и $pass, userInfo будет равен строке: 'user:pass'. Если не пуст $user, но пуст $pass, userInfo будет равен строке: 'user'.

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

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

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

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

# withHost

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

public function withHost($host): UriInterface;

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

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

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

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

# withPort

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

public function withPort($port): UriInterface;

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

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

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

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

$newUri = $uri->withPort(null);
$newUri->getPort(); // null
$newUri->getRawPort(); // 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\Uri\Uri с указанным компонентом пути из URI в соответствии с RFC 3986 Path.

public function withPath($path): UriInterface;

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

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

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

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

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

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

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

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

$uri->withPath('path/to/action?query=string') // throws InvalidArgumentException
$uri->withPath('path/to/action#fragment') // throws InvalidArgumentException

# withQuery

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

public function withQuery($query): UriInterface;

$query может быть либо пустым, либо начинаться со знака вопроса, либо не начинаться со знака вопроса. Если $query содержит символ #, будет брошено исключение \InvalidArgumentException.

$newUri = $uri->withQuery('?qu$ery');
$newUri->getQuery(); // 'qu%24ery'
$newUri->getRawQuery(); // '?qu$ery'

$newUri = $uri->withQuery('?qu%24ery');
$newUri->getQuery(); // 'qu%24ery'
$newUri->getRawQuery(); // '?qu%24ery'

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

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

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

$uri->withQuery('query=string#fragment') // throws InvalidArgumentException

# withFragment

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

public function withFragment($fragment): UriInterface;

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

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

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

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