HTTP-запрос
***********

.[perex]
Nette инкапсулирует HTTP-запрос в объекты с понятным API, обеспечивая при этом фильтр санации.

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

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

→ [Установка и требования |@home#Installation]


Nette\Http\Request .[#toc-nette-http-request]
=============================================

Этот объект является неизменяемым. У него нет сеттеров, есть только один так называемый 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]
---------------------------------------------------
Возвращает cookie или `null`, если он не существует.

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


getCookies(): array .[method]
-----------------------------
Возвращает все файлы cookie:

```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 использует cookie `_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]
----------------------------------------
Возвращает учетные данные [базовой 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`.