Робота з URL

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

→ Встановлення та вимоги

Url

Клас Nette\Http\Url дозволяє легко працювати з URL та його окремими компонентами, які відображає ця схема:

scheme  user  password  host   port    path        query  fragment
  |      |      |        |      |       |            |       |
/--\   /--\ /------\ /-------\ /--\/----------\ /--------\ /----\
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

Клас Nette\Http\UrlImmutable є immutable (незмінною) альтернативою класу Url (подібно до того, як у PHP DateTimeImmutable є незмінною альтернативою DateTime). Замість сеттерів він має так звані wither-и, які не змінюють об'єкт, а повертають нові екземпляри зі зміненим значенням:

use Nette\Http\UrlImmutable;

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

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

echo $newUrl; // 'http://john:xyz%2A12@nette.org:8080/uk/?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

Клас 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, включаючи query string та фрагмент.
• pathInfo — сьогодні вже мало використовувана частина URL після назви скрипта

Для повернення частин URL доступні методи:

Об'єкти UrlScript зазвичай безпосередньо не створюємо, але їх повертає метод Nette\Http\Request::getUrl() з уже правильно налаштованими компонентами для поточного HTTP-запиту.