HTTP request
************

.[perex]
Nette zapouzdřuje HTTP požadavek do objektů se srozumitelným API a zároveň poskytuje sanitizační filtr.

HTTP požadavek představuje objekt [api:Nette\Http\Request]. Pokud pracujete s Nette, tento objekt je automaticky vytvořen frameworkem a můžete si jej nechat předat pomocí [dependency injection |dependency-injection:passing-dependencies]. V presenterech stačí jen zavolat metodu `$this->getHttpRequest()`. Pokud pracujete mimo Nette Framework, můžete si vytvořit objekt pomocí [#RequestFactory].

Velkou předností Nette je, že při vytváření objektu automaticky pročišťuje všechny vstupní parametry GET, POST, COOKIE a také URL od kontrolních znaků a neplatných UTF-8 sekvencí. S těmito daty pak můžete bezpečně dále pracovat. Očištěná data se následně používají v presenterech a formulářích.

→ [Instalace a požadavky |@home#Instalace]


Nette\Http\Request
==================

Tento objekt je immutable (neměnný). Nemá žádné settery, má jen jeden tzv. wither `withUrl()`, který objekt nemění, ale vrací novou instanci se změněnou hodnotou.


withUrl(Nette\Http\UrlScript $url): Nette\Http\Request .[method]
----------------------------------------------------------------
Vrací klon s jinou URL.


getUrl(): Nette\Http\UrlScript .[method]
----------------------------------------
Vrací URL požadavku jako objekt [UrlScript |urls#UrlScript].

```php
$url = $httpRequest->getUrl();
echo $url; // https://doc.nette.org/cs/?action=edit
echo $url->getHost(); // nette.org
```

Upozornění: prohlížeče neodesílají na server fragment, takže `$url->getFragment()` bude vracet prázdný řetězec.


getQuery(?string $key=null): string|array|null .[method]
--------------------------------------------------------
Vrací parametry GET požadavku.

```php
$all = $httpRequest->getQuery(); // vrací pole všech parametrů z URL
$id = $httpRequest->getQuery('id'); // vrací GET parametr 'id' (nebo null)
```


getPost(?string $key=null): string|array|null .[method]
-------------------------------------------------------
Vrací parametry POST požadavku.

```php
$all = $httpRequest->getPost(); // vrací pole všech parametrů z POST
$id = $httpRequest->getPost('id'); // vrací POST parametr 'id' (nebo null)
```


getFile(string|string[] $key): Nette\Http\FileUpload|array|null .[method]
-------------------------------------------------------------------------
Vrací [upload |#Uploadované soubory] jako objekt [api:Nette\Http\FileUpload]:

```php
$file = $httpRequest->getFile('avatar');
if ($file?->hasFile()) { // byl nějaký soubor nahraný?
	$file->getUntrustedName(); // jméno souboru odeslané uživatelem
	$file->getSanitizedName(); // jméno bez nebezpečných znaků
}
```

Pro přístup do zanořené struktury uveďte pole klíčů.

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

Protože nelze důvěřovat datům zvenčí a tedy ani spoléhat na podobu struktury souborů, je bezpečnější tento způsob než třeba `$request->getFiles()['my-form']['details']['avatar']`, který může selhat.


getFiles(): array .[method]
---------------------------
Vrátí strom [všech uploadů |#Uploadované soubory] v normalizované struktuře, jejíž listy jsou objekty [api:Nette\Http\FileUpload]:

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


getCookie(string $key): string|array|null .[method]
---------------------------------------------------
Vrací cookie nebo `null`, když neexistuje.

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


getCookies(): array .[method]
-----------------------------
Vrací všechny cookies.

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


getMethod(): string .[method]
-----------------------------
Vrací HTTP metodu, se kterou byl udělán požadavek.

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


isMethod(string $method): bool .[method]
----------------------------------------
Testuje HTTP metodu, se kterou byl udělán požadavek. Parametr je case-insensitive.

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


getHeader(string $header): ?string .[method]
--------------------------------------------
Vrací HTTP hlavičku nebo `null`, pokud neexistuje. Parametr je case-insensitive.

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


getHeaders(): array .[method]
-----------------------------
Vrací všechny HTTP hlavičky jako asociativní pole.

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


isSecured(): bool .[method]
---------------------------
Je spojení šifrované (HTTPS)? Pro správnou funkčnost může být potřeba [nastavit proxy |configuration#HTTP proxy].


isSameSite(): bool .[method]
----------------------------
Přichází požadavek ze stejné (sub)domény a je iniciován kliknutím na odkaz? Nette k detekci používá cookie `_nss` (dříve `nette-samesite`).


isAjax(): bool .[method]
------------------------
Jde o AJAXový požadavek?


getRemoteAddress(): ?string .[method]
-------------------------------------
Vrací IP adresu uživatele. Pro správnou funkčnost může být potřeba [nastavit proxy |configuration#HTTP proxy].


getRemoteHost(): ?string .[method deprecated]
---------------------------------------------
Vrací DNS překlad IP adresy uživatele. Pro správnou funkčnost může být potřeba [nastavit proxy |configuration#HTTP proxy].


getBasicCredentials(): ?array .[method]
---------------------------------------
Vrací ověřovací údaje pro [Basic HTTP authentication |https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication].

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


getRawBody(): ?string .[method]
-------------------------------
Vrací tělo HTTP požadavku.

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


detectLanguage(array $langs): ?string .[method]
-----------------------------------------------
Detekuje jazyk. Jako parametr `$lang` předáme pole s jazyky, které aplikace podporuje, a ona vrátí ten, který by viděl návštěvníkův prohlížeč nejraději. Nejsou to žádná kouzla, jen se využívá hlavičky `Accept-Language`. Pokud nedojde k žádné shodě, vrací `null`.

```php
// prohlížeč odesílá např. Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // jazyky podporované aplikací
echo $httpRequest->detectLanguage($langs); // en
```


RequestFactory
==============

Třída [api:Nette\Http\RequestFactory] slouží k vytvoření instance `Nette\Http\Request`, která reprezentuje aktuální HTTP požadavek. (Pokud pracujete s Nette, objekt HTTP požadavku je automaticky vytvořen frameworkem.)

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

Metoda `fromGlobals()` vytvoří objekt požadavku na základě aktuálních globálních proměnných PHP (`$_GET`, `$_POST`, `$_COOKIE`, `$_FILES` a `$_SERVER`). Při vytváření objektu automaticky pročišťuje všechny vstupní parametry GET, POST, COOKIE a také URL od kontrolních znaků a neplatných UTF-8 sekvencí, což zajišťuje bezpečnost při další práci s těmito daty.

RequestFactory lze před zavoláním `fromGlobals()` konfigurovat:

- metodou `$factory->setBinary()` vypnete automatické čištění vstupních parametrů od kontrolních znaků a neplatných UTF-8 sekvencí.
- metodou `$factory->setProxy(...)` uvedete IP adresu [proxy serveru |configuration#HTTP proxy], což je nezbytné pro správnou detekci IP adresy uživatele.

RequestFactory umožňuje definovat filtry, které automaticky transformují části URL požadavku. Tyto filtry odstraňují nežádoucí znaky z URL, které tam mohou být vloženy například nesprávnou implementací komentářových systémů na různých webech:

```php
// odstranění mezer z cesty
$requestFactory->urlFilters['path']['%20'] = '';

// odstranění tečky, čárky nebo pravé závorky z konce URI
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// vyčištění cesty od zdvojených lomítek (výchozí filtr)
$requestFactory->urlFilters['path']['/{2,}'] = '/';
```

První klíč `'path'` nebo `'url'` určuje, na kterou část URL se filtr použije. Druhý klíč je regulární výraz, který se má vyhledat, a hodnota je náhrada, která se použije místo nalezeného textu.


Uploadované soubory
===================

Metoda `Nette\Http\Request::getFiles()` vrací pole všech uploadů v normalizované struktuře, jejíž listy jsou objekty [api:Nette\Http\FileUpload]. Ty zapouzdřují data odeslaná formulářovým prvkem `<input type=file>`.

Struktura reflektuje pojmenování prvků v HTML. V nejjednodušším případě to může být jediný pojmenovaný element formuláře odeslaný jako:

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

V tomto případě `$request->getFiles()` vrací pole:

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

Objekt `FileUpload` se vytvoří i v případě, že uživatel žádný soubor neodeslal nebo odeslání selhalo. Jestli byl soubor odeslán vrací metoda `hasFile()`:

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

V případě názvu elementu používajícího notaci pro pole:

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

vypadá vrácený strom takto:

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

Lze vytvořit i pole souborů:

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

V takovém případě vypadá struktura takto:

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

Přistoupit k indexu 1 vnořeného pole lze nejlépe takto:

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

Protože nelze důvěřovat datům zvenčí a tedy ani spoléhat na podobu struktury souborů, je bezpečnější tento způsob než třeba `$request->getFiles()['my-form']['details']['avatars'][1]`, který může selhat.


Přehled metod `FileUpload` .{toc: FileUpload}
---------------------------------------------


hasFile(): bool .[method]
-------------------------
Vrací `true`, pokud uživatel nějaký soubor uploadoval.


isOk(): bool .[method]
----------------------
Vrací `true`, pokud soubor byl nahrán úspěšně.


getError(): int .[method]
-------------------------
Vrací kód chyby při uploadu souboru. Jde o jednu z konstant [UPLOAD_ERR_XXX|http://php.net/manual/en/features.file-upload.errors.php]. V případě, že upload proběhl v pořádku, vrací `UPLOAD_ERR_OK`.


move(string $dest) .[method]
----------------------------
Přesune nahraný soubor do nového umístění. Pokud cílový soubor již existuje, bude přepsán.

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


getContents(): ?string .[method]
--------------------------------
Vrací obsah uploadovaného souboru. V případě, že upload nebyl úspěšný, vrací `null`.


getContentType(): ?string .[method]
-----------------------------------
Detekuje MIME content type uploadovaného souboru na základě jeho signatury. V případě, že upload nebyl úspěšný nebo detekce se nezdařila, vrací `null`.

.[caution]
Vyžaduje PHP rozšíření `fileinfo`.


getUntrustedName(): string .[method]
------------------------------------
Vrací originální název souboru, jak jej odeslal prohlížeč.

.[caution]
Nevěřte hodnotě vrácené touto metodou. Klient mohl odeslat škodlivý název souboru s úmyslem poškodit nebo hacknout vaši aplikaci.


getSanitizedName(): string .[method]
------------------------------------
Vrací sanitizovaný název souboru. Obsahuje pouze ASCII znaky `[a-zA-Z0-9.-]`. Pokud název takové znaky neobsahuje, vrátí `'unknown'`. Pokud je soubor obrázek ve formátu JPEG, PNG, GIF, WebP nebo AVIF, vrátí i správnou příponu.

.[caution]
Vyžaduje PHP rozšíření `fileinfo`.


getSuggestedExtension(): ?string .[method]{data-version:3.2.4}
--------------------------------------------------------------
Vrací vhodnou příponu souboru (bez tečky) odpovídající zjištěnému MIME typu.

.[caution]
Vyžaduje PHP rozšíření `fileinfo`.


getUntrustedFullPath(): string .[method]
----------------------------------------
Vrací originální cestu k souboru, jak ji odeslal prohlížeč při uploadu složky. Celá cesta je dostupná pouze v PHP 8.1 a vyšším. V předchozích verzích tato metoda vrací originální název souboru.

.[caution]
Nevěřte hodnotě vrácené touto metodou. Klient mohl odeslat škodlivý název souboru s úmyslem poškodit nebo hacknout vaši aplikaci.


getSize(): int .[method]
------------------------
Vrací velikost uploadovaného souboru. V případě, že upload nebyl úspěšný, vrací `0`.


getTemporaryFile(): string .[method]
------------------------------------
Vrací cestu k dočasné lokaci uploadovaného souboru. V případě, že upload nebyl úspěšný, vrací `''`.


isImage(): bool .[method]
-------------------------
Vrací `true`, pokud nahraný soubor je obrázek ve formátu JPEG, PNG, GIF, WebP nebo AVIF. Detekce probíhá na základě jeho signatury a neověřuje se integrita celého souboru. Zda není obrázek poškozený lze zjistit například pokusem o jeho [načtení |#toImage].

.[caution]
Vyžaduje PHP rozšíření `fileinfo`.


getImageSize(): ?array .[method]
--------------------------------
Vrací dvojici `[šířka, výška]` s rozměry uploadovaného obrázku. V případě, že upload nebyl úspěšný nebo nejde o platný obrázek, vrací `null`.


toImage(): Nette\Utils\Image .[method]
--------------------------------------
Načte obrázek jak objekt [Image|utils:images]. V případě, že upload nebyl úspěšný nebo nejde o platný obrázek, vyhodí výjimku `Nette\Utils\ImageException`.