HTTP заявка

Nette капсулира HTTP заявката в обекти с ясен API, като същевременно осигурява филтър за обработка.

HTTP заявката е обект Nette\Http\Request, който получавате, като го предавате с помощта на инжектиране на зависимости. В презентаторите просто извикайте $httpRequest = $this->getHttpRequest().

Важното е, че при създаването на този обект Nette ще изчисти всички входни параметри GET, POST и COOKIE, както и URL адреса от контролни символи и невалидни UTF-8 последователности. Следователно можете спокойно да продължите да работите с данните. След това почистените данни се използват в презентатори и формуляри.

→ Монтаж и изисквания

Nette\Http\Запитване

Този обект е неизменен. Той няма setters, има само един т.нар. 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

Връща “бисквитка” или null, ако тя не съществува.

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

getCookies(): array

Връща всички бисквитки:

$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 използва бисквитката _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

Обектът на текущата HTTP заявка се създава с помощта на Nette\Http\RequestFactory. Ако пишете приложение, което не използва DI-контейнер, създавате заявката по следния начин:

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

RequestFactory може да бъде конфигурирана преди извикването на fromGlobals(). Можем да деактивираме цялата обработка на входните параметри от невалидни UTF-8 последователности, като използваме $factory->setBinary(). Също така конфигурирайте прокси сървъра, което е важно за правилното идентифициране на IP адреса на потребителя с помощта на $factory->setProxy(...).

Можем да използваме филтри, за да изчистим URL адресите от знаци, които могат да попаднат в тях поради лошо реализирани системи за коментари в различни други сайтове:

// премахване на интервалите от пътя
$requestFactory->urlFilters['path']['%20'] = '';

// премахване на точката, запетаята или дясната скоба в края на URL адреса
$requestFactory->urlFilters['url']['['[.,)]$'] = '';

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

Качени файлове

Методът 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. Откриването се основава на неговия подпис. Целостта на целия файл не се проверява. Можете да разберете дали дадено изображение е повредено, например като се опитате да го изтеглите.