HTTP заявка

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

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

Основното предимство на 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

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