Zahteva HTTP
************

.[perex]
Nette zapakira zahtevo HTTP v predmete z razumljivim API-jem, hkrati pa zagotavlja filter za čiščenje.

Zahteva HTTP je objekt [api:Nette\Http\Request], ki ga dobite tako, da ga posredujete z uporabo [vbrizgavanja odvisnosti |dependency-injection:passing-dependencies]. V predvajalnikih preprosto pokličite `$httpRequest = $this->getHttpRequest()`.

Pomembno je, da Nette pri [ustvarjanju |#RequestFactory] tega objekta očisti vse vhodne parametre GET, POST in COOKIE ter naslove URL kontrolnih znakov in neveljavnih zaporedij UTF-8. Tako lahko varno nadaljujete delo s podatki. Očiščeni podatki se nato uporabljajo v predstavitvenih programih in obrazcih.

→ [Namestitev in zahteve |@home#Installation]


Nette\Http\Praševanje .[#toc-nette-http-request]
================================================

Ta predmet je nespremenljiv. Nima nastavljalcev, ima le en tako imenovani wither `withUrl()`, ki ne spremeni objekta, temveč vrne novo instanco s spremenjeno vrednostjo.


withUrl(Nette\Http\UrlScript $url): Nette\Http\Request .[method]
----------------------------------------------------------------
Vrne klon z drugačnim naslovom URL.


getUrl(): Nette\Http\UrlScript .[method]
----------------------------------------
Vrne URL zahteve kot predmet [UrlScript |urls#UrlScript].

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

Opozorilo: Brskalniki strežniku ne pošiljajo fragmentov, zato bo `$url->getFragment()` vrnil prazen niz.


getQuery(?string $key=null): string|array|null .[method]
--------------------------------------------------------
Vrne parametre zahteve GET:

```php
$all = $httpRequest->getQuery();    // polje vseh parametrov URL
$id = $httpRequest->getQuery('id'); // vrne parameter GET 'id' (ali null)
```


getPost(?string $key=null): string|array|null .[method]
-------------------------------------------------------
Vrne parametre zahteve POST:

```php
$all = $httpRequest->getPost();     // polje vseh parametrov POST
$id = $httpRequest->getPost('id');  // vrne parameter POST 'id' (ali null)
```


getFile(string|string[] $key): Nette\Http\FileUpload|array|null .[method]
-------------------------------------------------------------------------
Vrne [prenos |#Uploaded Files] kot predmet [api:Nette\Http\FileUpload]:

```php
$file = $httpRequest->getFile('avatar');
if ($file->hasFile()) { // je bila naložena katera koli datoteka?
	$file->getUntrustedName(); // ime datoteke, ki jo je poslal uporabnik
	$file->getSanitizedName(); // ime brez nevarnih znakov
}
```

Navedite polje ključev za dostop do strukture poddrevesa.

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

Ker ne morete zaupati podatkom od zunaj in se zato ne zanašate na obliko strukture, je ta metoda varnejša kot `$request->getFiles()['my-form']['details']['avatar']`ki je lahko neuspešna.


getFiles(): array .[method]
---------------------------
Vrne drevo [datotek za prenos v |#Uploaded Files] normalizirani strukturi, pri čemer je vsak list primerek [api:Nette\Http\FileUpload]:

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


getCookie(string $key): string|array|null .[method]
---------------------------------------------------
Vrne piškotek ali `null`, če ne obstaja.

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


getCookies(): array .[method]
-----------------------------
Vrne vse piškotke:

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


getMethod(): string .[method]
-----------------------------
Vrne metodo HTTP, s katero je bila zahteva izvedena.

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


isMethod(string $method): bool .[method]
----------------------------------------
Preveri metodo HTTP, s katero je bila izvedena zahteva. Pri parametru se ne razlikujejo velike in male črke.

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


getHeader(string $header): ?string .[method]
--------------------------------------------
Vrne glavo HTTP ali `null`, če ta ne obstaja. Pri parametru se ne razlikujejo velike in male črke:

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


getHeaders(): array .[method]
-----------------------------
Vrne vse glave HTTP kot asociativno polje:

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


isSecured(): bool .[method]
---------------------------
Ali je povezava šifrirana (HTTPS)? Za pravilno delovanje boste morda morali nastaviti [posrednika |configuration#HTTP proxy].


isSameSite(): bool .[method]
----------------------------
Ali zahteva prihaja iz iste (pod)domene in se sproži s klikom na povezavo? Nette to zazna s piškotkom `_nss` (prej `nette-samesite`).


isAjax(): bool .[method]
------------------------
Ali gre za zahtevo AJAX?


getRemoteAddress(): ?string .[method]
-------------------------------------
Vrne uporabnikov naslov IP. Za pravilno delovanje boste morda morali nastaviti [proxy strežnik |configuration#HTTP proxy].


getRemoteHost(): ?string .[method deprecated]
---------------------------------------------
Vrne prevod DNS uporabnikovega naslova IP. Za pravilno delovanje boste morda morali nastaviti [posrednika |configuration#HTTP proxy].


getBasicCredentials(): ?string .[method]
----------------------------------------
Vrne [osnovne |https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication] poverilnice za [avtentikacijo HTTP |https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication].

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


getRawBody(): ?string .[method]
-------------------------------
Vrne telo zahteve HTTP:

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


detectLanguage(array $langs): ?string .[method]
-----------------------------------------------
zazna jezik. Kot parameter `$lang` posredujemo polje jezikov, ki jih aplikacija podpira, in vrne tistega, ki ga ima brskalnik najraje. Ne gre za čarovnijo, metoda samo uporabi glavo `Accept-Language`. Če ni nobenega ujemanja, vrne `null`.

```php
// Naslovnica, ki jo pošlje brskalnik: Jezik: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // jeziki, podprti v aplikaciji
echo $httpRequest->detectLanguage($langs); // en
```


RequestFactory .[#toc-requestfactory]
=====================================

Predmet trenutne zahteve HTTP ustvari [api:Nette\Http\RequestFactory]. Če pišete aplikacijo, ki ne uporablja vsebnika DI, ustvarite zahtevo na naslednji način:

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

RequestFactory lahko konfigurirate pred klicem `fromGlobals()`. Z uporabo spletne strani `$factory->setBinary()` lahko onemogočimo vso sanitizacijo vhodnih parametrov iz neveljavnih zaporedij UTF-8. Prav tako lahko nastavimo strežnik proxy, kar je pomembno za pravilno zaznavanje uporabnikovega naslova IP z uporabo `$factory->setProxy(...)`.

Z uporabo filtrov je mogoče naslove URL očistiti znakov, ki lahko vanje pridejo zaradi slabo izvedenih sistemov komentarjev na različnih drugih spletnih mestih:

```php
// odstranite presledke s poti
$requestFactory->urlFilters['path']['%20'] = '';

// odstranite piko, vejico ali desni oklepaj na koncu naslova URL.
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// očisti pot podvojenih poševnic (privzeti filter)
$requestFactory->urlFilters['path']['/{2,}'] = '/';
```


Naložene datoteke .[#toc-uploaded-files]
========================================

Metoda `Nette\Http\Request::getFiles()` vrne drevo naloženih datotek v normalizirani strukturi, pri čemer je vsak list primerek objekta [api:Nette\Http\FileUpload]. Ti objekti vsebujejo podatke, ki jih je predložil `<input type=file>` element obrazca.

Struktura odraža poimenovanje elementov v jeziku HTML. V najpreprostejšem primeru je to lahko en poimenovan element obrazca, ki se odda kot:

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

V tem primeru `$request->getFiles()` vrne polje:

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

Objekt `FileUpload` se ustvari, tudi če uporabnik ni naložil nobene datoteke ali če nalaganje ni bilo uspešno. Metoda `hasFile()` vrne true, če je bila datoteka poslana:

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

V primeru vnosa, ki za ime uporablja zapis v obliki polja:

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

vrnjeno drevo je videti takole:

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

Ustvarite lahko tudi polja datotek:

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

V takem primeru je struktura videti kot:

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

Najboljši način za dostop do indeksa 1 ugnezdenega polja je naslednji:

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

Ker ne morete zaupati podatkom od zunaj in se zato ne zanašate na obliko strukture, je ta metoda varnejša od `$request->getFiles()['my-form']['details']['avatars'][1]`ki je lahko neuspešna.


Pregled metod `FileUpload` .{toc: FileUpload}
---------------------------------------------


hasFile(): bool .[method]
-------------------------
Vrne `true`, če je uporabnik naložil datoteko.


isOk(): bool .[method]
----------------------
Vrne `true`, če je bila datoteka uspešno naložena.


getError(): int .[method]
-------------------------
Vrne kodo napake, povezano z naloženo datoteko. To je ena od konstant [UPLOAD_ERR_XXX |http://php.net/manual/en/features.file-upload.errors.php]. Če je bila datoteka uspešno naložena, se vrne `UPLOAD_ERR_OK`.


move(string $dest) .[method]
----------------------------
Premakne naloženo datoteko na novo lokacijo. Če ciljna datoteka že obstaja, se prepiše.

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


getContents(): ?string .[method]
--------------------------------
Vrne vsebino naložene datoteke. Če nalaganje ni bilo uspešno, vrne `null`.


getContentType(): ?string .[method]
-----------------------------------
Določi vrsto vsebine MIME naložene datoteke na podlagi njenega podpisa. Če nalaganje ni bilo uspešno ali pa je bilo zaznavanje neuspešno, vrne `null`.

.[caution]
Zahteva razširitev PHP `fileinfo`.


getUntrustedName(): string .[method]
------------------------------------
Vrne izvirno ime datoteke, kot ga je posredoval brskalnik.

.[caution]
Ne zaupajte vrednosti, ki jo vrne ta metoda. Odjemalec lahko pošlje zlonamerno ime datoteke z namenom, da bi poškodoval ali vdrl v vašo aplikacijo.


getSanitizedName(): string .[method]
------------------------------------
Vrne prečiščeno ime datoteke. Vsebuje samo znake ASCII `[a-zA-Z0-9.-]`. Če ime ne vsebuje takih znakov, vrne 'unknown'. Če je datoteka slika JPEG, PNG, GIF ali WebP, vrne pravilno končnico datoteke.

.[caution]
Zahteva razširitev PHP `fileinfo`.


getSuggestedExtension(): ?string .[method]{data-version:3.2.4}
--------------------------------------------------------------
Vrne ustrezno razširitev datoteke (brez pike), ki ustreza zaznani vrsti MIME.

.[caution]
Zahteva razširitev PHP `fileinfo`.


getUntrustedFullPath(): string .[method]
----------------------------------------
Vrne izvirno celotno pot, kot jo je posredoval brskalnik med nalaganjem imenika. Polna pot je na voljo samo v PHP 8.1 in novejših različicah. V prejšnjih različicah ta metoda vrne ime nezaupljive datoteke.

.[caution]
Ne zaupajte vrednosti, ki jo vrne ta metoda. Odjemalec lahko pošlje zlonamerno ime datoteke z namenom, da bi poškodoval ali vdrl v vašo aplikacijo.


getSize(): int .[method]
------------------------
Vrne velikost naložene datoteke. Če nalaganje ni bilo uspešno, vrne `0`.


getTemporaryFile(): string .[method]
------------------------------------
Vrne pot do začasne lokacije naložene datoteke. Če nalaganje ni bilo uspešno, vrne `''`.


isImage(): bool .[method]
-------------------------
Vrne `true`, če je naložena datoteka slika JPEG, PNG, GIF ali WebP. Odkrivanje temelji na njenem podpisu. Celovitost celotne datoteke se ne preverja. Ali slika ni poškodovana, lahko ugotovite na primer tako, da jo poskusite [naložiti |#toImage].

.[caution]
Zahteva razširitev PHP `fileinfo`.


getImageSize(): ?array .[method]
--------------------------------
Vrne par `[width, height]` z merami naložene slike. Če nalaganje ni bilo uspešno ali slika ni veljavna, vrne `null`.


toImage(): Nette\Utils\Image .[method]
--------------------------------------
Naloži sliko kot objekt [Image |utils:images]. Če nalaganje ni bilo uspešno ali slika ni veljavna, se vrže izjema `Nette\Utils\ImageException`.