Работа с URL

Классы #Url, #UrlImmutable и #UrlScript позволяют легко генерировать, парсить и манипулировать URL.

→ Установка и требования

Url

Класс api:Nette\Http\Url позволяет легко работать с URL и его отдельными компонентами, которые отражены на этой схеме:

схема  пользователь  пароль  хост   порт    путь        запрос  фрагмент
  |      |      |        |      |       |            |       |
/--\   /--\ /------\ /-------\ /--\/----------\ /--------\ /----\
http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer
\______\__________________________/
    |               |
 hostUrl        authority

Генерация URL интуитивно понятна:

use Nette\Http\Url;

$url = new Url;
$url->setScheme('https')
	->setHost('localhost')
	->setPath('/edit')
	->setQueryParameter('foo', 'bar');

echo $url; // 'https://localhost/edit?foo=bar'

Также можно распарсить URL и далее манипулировать им:

$url = new Url(
	'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);

Класс Url реализует интерфейс JsonSerializable и имеет метод __toString(), так что объект можно вывести или использовать в данных, передаваемых в json_encode().

echo $url;
echo json_encode([$url]);

Компоненты URL

Для возврата или изменения отдельных компонентов URL вам доступны следующие методы:

Предупреждение: Когда вы работаете с URL, полученным из HTTP-запроса, имейте в виду, что он не будет содержать фрагмент, так как браузер не отправляет его на сервер.

Мы можем работать и с отдельными query-параметрами с помощью:

getDomain (int $level = 2): string

Возвращает правую или левую часть хоста. Так это работает, если хост www.nette.org:

isEqual (string|Url $anotherUrl): bool

Проверяет, идентичны ли два URL.

$url->isEqual('https://nette.org');

Url::isAbsolute (string $url): bool

Проверяет, является ли URL абсолютным. URL считается абсолютным, если он начинается со схемы (например, http, https, ftp), за которой следует двоеточие.

Url::isAbsolute('https://nette.org');    // true
Url::isAbsolute('//nette.org');          // false

Url::removeDotSegments (string $path): string

Нормализует путь в URL, удаляя специальные сегменты . и ... Метод удаляет избыточные элементы пути тем же способом, как это делают веб-браузеры.

Url::removeDotSegments('/path/../subtree/./file.txt');  // '/subtree/file.txt'
Url::removeDotSegments('/../foo/./bar');                // '/foo/bar'
Url::removeDotSegments('./today/../file.txt');          // 'file.txt'

UrlImmutable

Класс api:Nette\Http\UrlImmutable является immutable (неизменяемой) альтернативой классу #Url (подобно тому, как в PHP DateTimeImmutable является неизменяемой альтернативой DateTime). Вместо сеттеров у него есть так называемые withers, которые не изменяют объект, а возвращают новые экземпляры с измененным значением:

use Nette\Http\UrlImmutable;

$url = new UrlImmutable(
	'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);

$newUrl = $url
	->withUser('')
	->withPassword('')
	->withPath('/cs/');

echo $newUrl; // 'http://nette.org:8080/cs/?name=param#footer'

Класс UrlImmutable реализует интерфейс JsonSerializable и имеет метод __toString(), так что объект можно вывести или использовать в данных, передаваемых в json_encode().

echo $url;
echo json_encode([$url]);

Компоненты URL

Для возврата или изменения отдельных компонентов URL служат методы:

Метод withoutUserInfo() удаляет user и password.

Мы можем работать и с отдельными query-параметрами с помощью:

getDomain (int $level = 2): string

Возвращает правую или левую часть хоста. Так это работает, если хост www.nette.org:

resolve (string $reference): UrlImmutable

Выводит абсолютный URL тем же способом, каким браузер обрабатывает ссылки на HTML-странице:

• если ссылка является абсолютным URL (содержит схему), она используется без изменений
• если ссылка начинается с //, берется только схема из текущего URL
• если ссылка начинается с /, создается абсолютный путь от корня домена
• в остальных случаях URL составляется относительно текущего пути

$url = new UrlImmutable('https://example.com/path/page');
echo $url->resolve('../foo');           // 'https://example.com/foo'
echo $url->resolve('/bar');             // 'https://example.com/bar'
echo $url->resolve('sub/page.html');    // 'https://example.com/path/sub/page.html'

isEqual (string|Url $anotherUrl): bool

Проверяет, идентичны ли два URL.

$url->isEqual('https://nette.org');

UrlScript

Класс api:Nette\Http\UrlScript является потомком #UrlImmutable и расширяет его дополнительными виртуальными компонентами URL, такими как корневой каталог проекта и т.д. Как и родительский класс, это immutable (неизменяемый) объект.

Следующая диаграмма отображает компоненты, которые распознает UrlScript:

     baseUrl    basePath  relativePath  relativeUrl
        |          |        |               |
/---------------/-----\/--------\---------------------------\
http://nette.org/admin/script.php/pathinfo/?name=param#footer
                \_______________/\________/
                       |              |
                  scriptPath       pathInfo

• baseUrl — это базовый URL-адрес приложения, включая домен и часть пути к корневому каталогу приложения
• basePath — это часть пути к корневому каталогу приложения
• scriptPath — это путь к текущему скрипту
• relativePath — это имя скрипта (возможно, с дополнительными сегментами пути) относительно basePath
• relativeUrl — это вся часть URL после baseUrl, включая строку запроса и фрагмент.
• pathInfo — сегодня уже малоиспользуемая часть URL после имени скрипта

Для возврата частей URL доступны методы:

Объекты UrlScript обычно не создаются напрямую, но их возвращает метод Nette\Http\Request::getUrl()|request |Nette\Http\Request::getUrl()|request с уже правильно настроенными компонентами для текущего HTTP-запроса.