HTTP-запит

Nette інкапсулює HTTP-запит в об'єкти зі зрозумілим API, забезпечуючи при цьому фільтр санації.

HTTP-запит представляється об'єктом Nette\Http\Request. Якщо ви працюєте з Nette, цей об'єкт автоматично створюється фреймворком, і ви можете передати його вам за допомогою ін'єкції залежностей. У презентаторах вам просто потрібно викликати метод $this->getHttpRequest(). Якщо ви працюєте поза Nette Framework, ви можете створити об'єкт за допомогою RequestFactory.

Основною перевагою Nette є те, що при створенні об'єкта він автоматично очищає всі вхідні параметри GET, POST, COOKIE, а також URL-адресу від контрольних символів і невірних послідовностей UTF-8. Після цього ви можете спокійно працювати з цими даними. Очищені дані згодом використовуються в презентаціях і формах.

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

Nette\Http\Request

Цей об'єкт є незмінним. У нього немає сеттерів, є тільки один так званий wither withUrl(), який не змінює об'єкт, а повертає новий екземпляр зі зміненим значенням.

withUrl (Nette\Http\UrlScript $url): Nette\Http\Request

Повертає клон з іншим URL.

getUrl(): Nette\Http\UrlScript

Повертає URL запиту у вигляді об'єкта UrlScript.

$url = $httpRequest->getUrl();
echo $url; // https://nette.org/en/documentation?action=edit
echo $url->getHost(); // nette.org

Попередження: Браузери не надсилають фрагмент на сервер, тому $url->getFragment() поверне порожній рядок.

getQuery (?string $key=null): string|array|null

Повертає параметри GET-запиту:

$all = $httpRequest->getQuery(); // масив усіх URL параметрів
$id = $httpRequest->getQuery('id'); // повертає GET-параметр 'id' (або null)

getPost (?string $key=null): string|array|null

Повертає параметри POST-запиту:

$all = $httpRequest->getPost(); // масив усіх POST-параметрів
$id = $httpRequest->getPost('id'); // повертає POST-параметр 'id' (або null)

getFile (string|string[] $key): Nette\Http\FileUpload|array|null

Повертає вивантаження як об'єкт Nette\Http\FileUpload:

$file = $httpRequest->getFile('avatar');
if ($file->hasFile()) { // чи був завантажений якийсь файл?
	$file->getUntrustedName(); // ім'я файлу, відправленого користувачем
	$file->getSanitizedName(); // ім'я без небезпечних символів
}

Вкажіть масив ключів для доступу до структури піддерева.

//<input type="file" name="my-form[details][avatar]" multiple>
$file = $request->getFile(['my-form', 'details', 'avatar']);

Оскільки ви не можете довіряти даним ззовні і тому не покладаєтеся на форму структури, цей метод безпечніший, ніж $request->getFiles()['my-form']['details']['avatar']який може зазнати невдачі.

getFiles(): array

Повертає дерево файлів вивантаження в нормалізованій структурі, кожен аркуш якого є екземпляром Nette\Http\FileUpload:

$files = $httpRequest->getFiles();

getCookie (string $key): string|array|null

Повертає cookie або null, якщо він не існує.

$sessId = $httpRequest->getCookie('sess_id');

getCookies(): array

Повертає всі файли cookie:

$cookies = $httpRequest->getCookies();

getMethod(): string

Повертає метод HTTP, за допомогою якого було зроблено запит.

echo $httpRequest->getMethod(); // GET, POST, HEAD, PUT

isMethod (string $method): bool

Перевіряє метод HTTP, за допомогою якого було зроблено запит. Параметр не чутливий до регістру.

if ($httpRequest->isMethod('GET')) // ...

getHeader (string $header): ?string

Повертає HTTP-заголовок або null, якщо він не існує. Параметр не чутливий до регістру:

$userAgent = $httpRequest->getHeader('User-Agent');

getHeaders(): array

Повертає всі HTTP-заголовки у вигляді асоціативного масиву:

$headers = $httpRequest->getHeaders();
echo $headers['Content-Type'];

isSecured(): bool

Чи зашифровано з'єднання (HTTPS)? Можливо, вам буде потрібно налаштувати проксі-сервер для правильної роботи.

isSameSite(): bool

Запит виходить із того самого (під)домену та ініційований натисканням на посилання? Для визначення цього Nette використовує cookie _nss (раніше nette-samesite).

isAjax(): bool

Це AJAX-запит?

getRemoteAddress(): ?string

Повертає IP-адресу користувача. Для правильної роботи може знадобитися налаштування проксі-сервера.

getRemoteHost(): ?string

Повертає DNS-трансляцію IP-адреси користувача. Для правильної роботи може знадобитися налаштування проксі-сервера.

getBasicCredentials(): ?string

Повертає облікові дані базової HTTP-аутентифікації.

[$user, $password] = $httpRequest->getBasicCredentials();

getRawBody(): ?string

Повертає тіло HTTP-запиту:

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

Визначає мову. Як параметр $lang ми передаємо масив мов, які підтримує додаток, і він повертає ту, якій віддає перевагу браузер. Це не магія, метод просто використовує заголовок Accept-Language. Якщо збіг не досягнуто, повертається null.

// Заголовок, що надсилається браузером: Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // мови, що підтримуються в застосунку
echo $httpRequest->detectLanguage($langs); // en

RequestFactory

Клас Nette\Http\RequestFactory використовується для створення екземпляра Nette\Http\Request, який представляє поточний HTTP-запит. (Якщо ви працюєте з Nette, об'єкт HTTP-запиту створюється фреймворком автоматично).

$factory = new Nette\Http\RequestFactory;
$httpRequest = $factory->fromGlobals();

Метод fromGlobals() створює об'єкт запиту на основі поточних глобальних змінних PHP ($_GET, $_POST, $_COOKIE, $_FILES і $_SERVER). При створенні об'єкта він автоматично очищає всі вхідні параметри GET, POST, COOKIE, а також URL від контрольних символів і невірних послідовностей UTF-8, що забезпечує безпеку при подальшій роботі з цими даними.

RequestFactory можна налаштувати перед викликом fromGlobals():

за допомогою методу $factory->setBinary() можна відключити автоматичне очищення вхідних параметрів від контрольних символів і неприпустимих послідовностей UTF-8.
за допомогою методу $factory->setProxy(...) вказується IP-адреса проксі-сервера, яка необхідна для коректного визначення IP-адреси користувача.

RequestFactory дозволяє визначати фільтри, які автоматично перетворюють частини URL-запиту. Ці фільтри видаляють з URL-адрес небажані символи, які могли бути вставлені, наприклад, через некоректну реалізацію систем коментування на різних сайтах:

// видалення пробілів зі шляху
$requestFactory->urlFilters['path']['%20'] = '';

// видалення крапки, коми або правої дужки з кінця URI
$requestFactory->urlFilters['url']['['[.,)]$'] = '';

// очищення шляху від подвійних слешів (фільтр за замовчуванням)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

Перший ключ 'path' або 'url' визначає, до якої частини URL-адреси буде застосовано фільтр. Другий ключ – це регулярний вираз для пошуку, а значення – заміна, яка буде використана замість знайденого тексту.

Завантажені файли

Метод Nette\Http\Request::getFiles() повертає дерево завантажених файлів у нормалізованій структурі, кожен аркуш якого є екземпляром Nette\Http\FileUpload. Ці об'єкти інкапсулюють дані, представлені елементом <input type=file> елементом форми.

Структура відображає іменування елементів у HTML. У найпростішому прикладі це може бути один іменований елемент форми, представлений як:

<input type="file" name="avatar">

У цьому випадку $request->getFiles() повертає масив:

[
	'avatar' => /* FileUpload instance */
]

Об'єкт FileUpload створюється, навіть якщо користувач не завантажив жодного файлу або завантаження не вдалося. Метод hasFile() повертає true, якщо файл було надіслано:

$request->getFile('avatar')->hasFile();

У разі введення з використанням нотації масиву для імені:

<input type="file" name="my-form[details][avatar]">

дерево, що повертається, має такий вигляд:

[
	'my-form' => [
		'details' => [
			'avatar' => /* FileUpload instance */
		],
	],
]

Ви також можете створювати масиви файлів:

<input type="file" name="my-form[details][avatars][] multiple">

У такому разі структура має такий вигляд:

[
	'my-form' => [
		'details' => [
			'avatars' => [
				0 => /* FileUpload instance */,
				1 => /* FileUpload instance */,
				2 => /* FileUpload instance */,
			],
		],
	],
]

Найкращий спосіб доступу до індексу 1 вкладеного масиву такий:

$file = $request->getFile(['my-form', 'details', 'avatars', 1]);
if ($file instanceof FileUpload) {
	// ...
}

Оскільки ви не можете довіряти даним ззовні і тому не покладаєтеся на форму структури, цей метод є безпечнішим, ніж $request->getFiles()['my-form']['details']['avatars'][1]який може не спрацювати.

Огляд методів `FileUpload`

hasFile(): bool

Повертає true, якщо користувач завантажив файл.

isOk(): bool

Повертає true, якщо файл було завантажено успішно.

getError(): int

Повертає код помилки, пов'язаний із завантаженим файлом. Це може бути одна з констант UPLOAD_ERR_XXX. Якщо файл було завантажено успішно, повертається UPLOAD_ERR_OK.

move (string $dest)

Переміщує завантажений файл у нове місце. Якщо файл призначення вже існує, його буде перезаписано.

$file->move('/path/to/files/name.ext');

getContents(): ?string

Повертає вміст завантаженого файлу. Якщо завантаження не було успішним, повертається null.

getContentType(): ?string

Визначає MIME-тип вмісту завантажуваного файлу на основі його сигнатури. Якщо завантаження не було успішним або визначення не вдалося, повертається null.

Потрібне розширення PHP fileinfo.

getUntrustedName(): string

Повертає вихідне ім'я файлу, передане браузером.

Не довіряйте значенню, що повертається цим методом. Клієнт може надіслати шкідливе ім'я файлу з наміром зіпсувати або зламати ваш додаток.

getSanitizedName(): string

Повертає саніроване ім'я файлу. Воно містить тільки символи ASCII [a-zA-Z0-9.-]. Якщо ім'я не містить таких символів, повертається ‘unknown’. Якщо файл є зображенням JPEG, PNG, GIF або WebP, повертається правильне розширення файлу.

Потрібне розширення PHP fileinfo.

getSuggestedExtension(): ?string

Повертає відповідне розширення файлу (без крапки), що відповідає виявленому MIME-типу.

Вимагає розширення PHP fileinfo.

getUntrustedFullPath(): string

Повертає вихідний повний шлях, вказаний браузером під час завантаження каталогу. Повний шлях доступний тільки в PHP 8.1 і вище. У попередніх версіях цей метод повертає недовірене ім'я файлу.

getSize(): int

Повертає розмір завантаженого файлу. Якщо завантаження не було успішним, повертається 0.

getTemporaryFile(): string

Повертає шлях до тимчасового місця розташування завантаженого файлу. Якщо завантаження не було успішним, повертається ''.

isImage(): bool

Повертає true, якщо завантажений файл є зображенням JPEG, PNG, GIF або WebP. Виявлення засноване на його сигнатурі. Цілісність усього файлу не перевіряється. Ви можете дізнатися, чи не пошкоджено зображення, наприклад, спробувавши завантажити його.

Потрібне розширення PHP fileinfo.

getImageSize(): ?array

Повертає пару [width, height] з розмірами завантаженого зображення. Якщо завантаження не було успішним або це не дійсне зображення, повертається null.

toImage(): Nette\Utils\Image

Завантажує зображення як об'єкт Image. Якщо завантаження не було успішним або зображення не є дійсним, викидається виняток Nette\Utils\ImageException.

HTTP-запит

Nette\Http\Request

withUrl (Nette\Http\UrlScript $url): Nette\Http\Request

getUrl(): Nette\Http\UrlScript

getQuery (?string $key=null): string|array|null

getPost (?string $key=null): string|array|null

getFile (string|string[] $key): Nette\Http\FileUpload|array|null

getFiles(): array

getCookie (string $key): string|array|null

getCookies(): array

getMethod(): string

isMethod (string $method): bool

getHeader (string $header): ?string

getHeaders(): array

isSecured(): bool

isSameSite(): bool

isAjax(): bool

getRemoteAddress(): ?string

getRemoteHost(): ?string

getBasicCredentials(): ?string

getRawBody(): ?string

detectLanguage (array $langs): ?string

RequestFactory

Завантажені файли

Огляд методів FileUpload

hasFile(): bool

isOk(): bool

getError(): int

move (string $dest)

getContents(): ?string

getContentType(): ?string

getUntrustedName(): string

getSanitizedName(): string

getSuggestedExtension(): ?string

getUntrustedFullPath(): string

getSize(): int

getTemporaryFile(): string

isImage(): bool

getImageSize(): ?array

toImage(): Nette\Utils\Image

Огляд методів `FileUpload`