request.texy

HTTP заявка
***********

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

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

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

→ [Монтаж и изисквания |@home#Installation]


Nette\Http\Запитване .[#toc-nette-http-request]
===============================================

Този обект е неизменен. Той няма setters, има само един т.нар. wither `withUrl()`, който не променя обекта, а връща нова инстанция с променената стойност.


withUrl(Nette\Http\UrlScript $url): Nette\Http\Request .[method]
----------------------------------------------------------------
Връща клонинг с различен URL адрес.


getUrl(): Nette\Http\UrlScript .[method]
----------------------------------------
Връща URL адреса на заявката като обект [UrlScript |urls#UrlScript].

```php
$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 .[method]
-------------------------------------------------------
Връща параметрите на заявката GET:

```php
$all = $httpRequest->getQuery(); // масив от всички параметри на URL
$id = $httpRequest->getQuery('id'); // връща GET параметър 'id' (или null)
```


getPost(string $key=null): string|array|null .[method]
------------------------------------------------------
Връща параметрите на заявката POST:

```php
$all = $httpRequest->getPost(); // масив от всички POST параметри
$id = $httpRequest->getPost('id'); // връща POST параметър 'id' (или null)
```


getFile(string|string[] $key): Nette\Http\FileUpload|array|null .[method]
-------------------------------------------------------------------------
Връща [качването |#Uploaded-Files] като обект [api:Nette\Http\FileUpload]:

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

Посочете масив от ключове за достъп до структурата на поддървото.

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

Тъй като не можете да се доверите на данните отвън и следователно не разчитате на формата на структурата, този метод е по-безопасен от `$request->getFiles()['my-form']['details']['avatar']`които могат да се провалят.


getFiles(): array .[method]
---------------------------
Връща дърво на [файловете за разтоварване |#Uploaded-Files] в нормализирана структура, като всеки лист е инстанция на [api:Nette\Http\FileUpload]:

```php
$files = $httpRequest->getFiles();
```


getCookie(string $key): string|array|null .[method]
---------------------------------------------------
Връща "бисквитка" или `null`, ако тя не съществува.

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


getCookies(): array .[method]
-----------------------------
Връща всички бисквитки:

```php
$cookies = $httpRequest->getCookies();
```


getMethod(): string .[method]
-----------------------------
Връща HTTP метода, с който е направена заявката.

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


isMethod(string $method): bool .[method]
----------------------------------------
Проверява HTTP метода, с който е направена заявката. Параметърът не е чувствителен към големи и малки букви.

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


getHeader(string $header): ?string .[method]
--------------------------------------------
Връща HTTP заглавието или `null`, ако то не съществува. Параметърът не е чувствителен към големи и малки букви:

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


getHeaders(): array .[method]
-----------------------------
Връща всички HTTP заглавия като асоциативен масив:

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


isSecured(): bool .[method]
---------------------------
Криптирана ли е връзката (HTTPS)? Може да се наложи да конфигурирате [прокси сървър |configuration#HTTP-Proxy], за да работи правилно.


isSameSite(): bool .[method]
----------------------------
Заявката идва от същия (под)домейн и се инициира от кликване върху връзка? Nette използва бисквитката `_nss` (преди `nette-samesite`), за да определи това.


isAjax(): bool .[method]
------------------------
Това заявка AJAX ли е?


getRemoteAddress(): ?string .[method]
-------------------------------------
Връща IP адреса на потребителя. Може да се наложи да настроите [прокси сървър |configuration#HTTP-Proxy], за да работи правилно.


getRemoteHost(): ?string .[method deprecated]
---------------------------------------------
Връща DNS превода на IP адреса на потребителя. Може да се наложи да настроите [прокси сървър |configuration#HTTP-Proxy], за да работи правилно.


getBasicCredentials(): ?string .[method]
----------------------------------------
Връща [основните идентифика |https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication] ционни данни за [удостоверяване по HTTP |https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication].

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


getRawBody(): ?string .[method]
-------------------------------
Връща тялото на HTTP заявката:

```php
$body = $httpRequest->getRawBody();
```


detectLanguage(array $langs): ?string .[method]
-----------------------------------------------
Определя езика. Предаваме масив от езици, които приложението поддържа, като параметър на `$lang` и той връща предпочитания от браузъра език. Това не е магия, методът просто използва заглавието `Accept-Language`. Ако не бъде намерено съвпадение, се връща `null`.

```php
// Заглавие, изпратено от браузъра: 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 .[#toc-requestfactory]
=====================================

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

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

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

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

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

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

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


Качени файлове .[#toc-uploaded-files]
=====================================

Методът `Nette\Http\Request::getFiles()` връща дърво от изтеглени файлове в нормализирана структура, като всеки лист е инстанция на [api:Nette\Http\FileUpload]. Тези обекти капсулират данните, представени от `<input type=file>` елемент на формата.

Структурата отразява наименованието на елементите в HTML. В най-простия пример това може да бъде един именуван елемент на формуляра, представен като:

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

В този случай `$request->getFiles()` връща масив:

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

Обектът `FileUpload` се създава, дори ако потребителят не е качил никакъв файл или качването е неуспешно. Методът `hasFile()` връща true, ако файлът е бил качен:

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

В случай на въвеждане, при което се използва масивна нотация за името:

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

дървото, което трябва да се върне, е следното:

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

Можете също така да създавате масиви от файлове:

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

В този случай структурата изглежда по следния начин

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

Най-добрият начин за достъп до индекс 1 на вложен масив е следният:

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

Тъй като не можете да се доверите на външните данни и следователно не разчитате на формата на структурата, този метод е по-безопасен от `$request->getFiles()['my-form']['details']['avatars'][1]`което може да не работи.


Преглед на методите `FileUpload` .{toc: FileUpload}
---------------------------------------------------


hasFile(): bool .[method]
-------------------------
Връща `true`, ако потребителят е качил файл.


isOk(): bool .[method]
----------------------
Връща `true`, ако файлът е изтеглен успешно.


getError(): int .[method]
-------------------------
Връща кода за грешка, свързан с качения файл. Това може да бъде една от константите [UPLOAD_ERR_XXX |http://php.net/manual/en/features.file-upload.errors.php]. Ако файлът е бил качен успешно, се връща `UPLOAD_ERR_OK`.


move(string $dest) .[method]
----------------------------
Премества качения файл на ново място. Ако файлът на дестинацията вече съществува, той ще бъде презаписан.

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


getContents(): ?string .[method]
--------------------------------
Връща съдържанието на качения файл. Ако качването не е било успешно, се връща `null`.


getContentType(): ?string .[method]
-----------------------------------
Определя типа на съдържанието MIME на изтегления файл въз основа на неговата сигнатура. Ако качването не е било успешно или откриването е било неуспешно, се връща `null`.

.[caution]
Изисква разширението на PHP `fileinfo`.


getUntrustedName(): string .[method]
------------------------------------
Връща оригиналното име на файла, както е предадено от браузъра.

.[caution]
Не се доверявайте на стойността, върната от този метод. Клиентът може да изпрати злонамерено име на файл с намерението да повреди или хакне вашето приложение.


getSanitizedName(): string .[method]
------------------------------------
Връща обработено име на файл. Той съдържа само ASCII символи. `[a-zA-Z0-9.-]`. Ако името не съдържа такива знаци, се връща символът 'unknown'. Ако файлът е JPEG, PNG, GIF или WebP изображение, се връща правилното разширение на файла.

.[caution]
Изисква разширение на PHP `fileinfo`.


getSuggestedExtension(): ?string .[method]{data-version:3.2.4}
--------------------------------------------------------------
Връща съответното разширение на файла (без точка), съответстващо на открития тип MIME.

.[caution]
Изисква PHP разширение `fileinfo`.


getUntrustedFullPath(): string .[method]
----------------------------------------
Връща оригиналния пълен път, зададен от браузъра при зареждането на директорията. Пълният път е наличен само в PHP 8.1 и по-нови версии. В предишните версии този метод връща ненадеждно име на файл.

.[caution]
Не се доверявайте на стойността, върната от този метод. Клиентът може да изпрати злонамерено име на файл с намерението да повреди или отвлече вашето приложение.


getSize(): int .[method]
------------------------
Връща размера на качения файл. Ако качването не е било успешно, се връща `0`.


getTemporaryFile(): string .[method]
------------------------------------
Връща пътя до временното местоположение на изтегления файл. Ако качването не е било успешно, се връща `''`.


isImage(): bool .[method]
-------------------------
Връща `true`, ако каченият файл е изображение JPEG, PNG, GIF или WebP. Откриването се основава на неговия подпис. Целостта на целия файл не се проверява. Можете да разберете дали дадено изображение е повредено, например като се опитате да [го изтеглите |#toImage].

.[caution]
Изисква разширението на PHP `fileinfo`.


getImageSize(): ?array .[method]
--------------------------------
Връща двойка от `[width, height]` с размерите на каченото изображение. Ако качването не е било успешно или изображението не е валидно, се връща `null`.


toImage(): Nette\Utils\Image .[method]
--------------------------------------
Зарежда изображението като обект [Image |utils:images]. Ако качването е неуспешно или изображението не е валидно, се изхвърля изключение на адрес `Nette\Utils\ImageException`.