Cerere HTTP
***********

.[perex]
Nette încapsulează cererea HTTP în obiecte cu un API ușor de înțeles, oferind în același timp un filtru de curățare.

O solicitare HTTP este un obiect [api:Nette\Http\Request], pe care îl obțineți trecându-l folosind [injecția de dependență |dependency-injection:passing-dependencies]. În prezentatori, pur și simplu apelați `$httpRequest = $this->getHttpRequest()`.

Ceea ce este important este că Nette, atunci când [creează |#RequestFactory] acest obiect, curăță toți parametrii de intrare GET, POST și COOKIE, precum și URL-urile de caractere de control și secvențe UTF-8 invalide. Astfel, puteți continua să lucrați în siguranță cu datele. Datele curățate sunt apoi utilizate în prezentatori și formulare.

→ [Instalare și cerințe |@home#Installation]


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

Acest obiect este imuabil. Nu are setori, are doar un singur așa-numit wither `withUrl()`, care nu modifică obiectul, ci returnează o nouă instanță cu o valoare modificată.


withUrl(Nette\Http\UrlScript $url): Nette\Http\Request .[method]
----------------------------------------------------------------
Returnează o clonă cu o adresă URL diferită.


getUrl(): Nette\Http\UrlScript .[method]
----------------------------------------
Returnează adresa URL a cererii ca obiect [UrlScript |urls#UrlScript].

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

Avertisment: Browserele nu trimit un fragment către server, astfel încât `$url->getFragment()` va returna un șir gol.


getQuery(?string $key=null): string|array|null .[method]
--------------------------------------------------------
Returnează parametrii cererii GET:

```php
$all = $httpRequest->getQuery();    // matrice cu toți parametrii URL
$id = $httpRequest->getQuery('id'); // returnează parametrul GET "id" (sau nul)
```


getPost(?string $key=null): string|array|null .[method]
-------------------------------------------------------
Returnează parametrii cererii POST:

```php
$all = $httpRequest->getPost();     // matrice cu toți parametrii POST
$id = $httpRequest->getPost('id');  // returnează parametrul POST "id" (sau null)
```


getFile(string|string[] $key): Nette\Http\FileUpload|array|null .[method]
-------------------------------------------------------------------------
Returnează [încărcarea |#Uploaded Files] ca obiect [api:Nette\Http\FileUpload]:

```php
$file = $httpRequest->getFile('avatar');
if ($file->hasFile()) { // a fost încărcat vreun fișier?
	$file->getUntrustedName(); // numele fișierului trimis de utilizator
	$file->getSanitizedName(); // numele fără caractere periculoase
}
```

Specificați un tablou de chei pentru a accesa structura subarborelui.

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

Deoarece nu puteți avea încredere în datele din exterior și, prin urmare, nu vă bazați pe forma structurii, această metodă este mai sigură decât `$request->getFiles()['my-form']['details']['avatar']`, care poate da greș.


getFiles(): array .[method]
---------------------------
Returnează arborele de [fișiere de încărcare |#Uploaded Files] într-o structură normalizată, fiecare frunză fiind o instanță a [api:Nette\Http\FileUpload]:

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


getCookie(string $key): string|array|null .[method]
---------------------------------------------------
Returnează un cookie sau `null` dacă acesta nu există.

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


getCookies(): array .[method]
-----------------------------
Returnează toate cookie-urile:

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


getMethod(): string .[method]
-----------------------------
Returnează metoda HTTP cu care a fost făcută cererea.

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


isMethod(string $method): bool .[method]
----------------------------------------
Verifică metoda HTTP cu care a fost efectuată cererea. Parametrul nu ține cont de majuscule și minuscule.

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


getHeader(string $header): ?string .[method]
--------------------------------------------
Returnează un antet HTTP sau `null` dacă acesta nu există. Parametrul nu ține cont de majuscule și minuscule:

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


getHeaders(): array .[method]
-----------------------------
Returnează toate antetele HTTP ca matrice asociativă:

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


isSecured(): bool .[method]
---------------------------
Conexiunea este criptată (HTTPS)? Este posibil să fie necesar să configurați [un proxy |configuration#HTTP proxy] pentru o funcționalitate corespunzătoare.


isSameSite(): bool .[method]
----------------------------
Solicitarea provine de la același (sub)domeniu și este inițiată prin apăsarea unui link? Nette utilizează cookie-ul `_nss` (fost `nette-samesite`) pentru a detecta acest lucru.


isAjax(): bool .[method]
------------------------
Este o cerere AJAX?


getRemoteAddress(): ?string .[method]
-------------------------------------
Returnează adresa IP a utilizatorului. Este posibil să fie necesar să configurați [un proxy |configuration#HTTP proxy] pentru o funcționalitate corespunzătoare.


getRemoteHost(): ?string .[method deprecated]
---------------------------------------------
Returnează traducerea DNS a adresei IP a utilizatorului. Este posibil să fie necesar să configurați [un proxy |configuration#HTTP proxy] pentru o funcționalitate corespunzătoare.


getBasicCredentials(): ?string .[method]
----------------------------------------
Returnează acreditările de [autentificare HTTP de bază |https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication].

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


getRawBody(): ?string .[method]
-------------------------------
Returnează corpul solicitării HTTP:

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


detectLanguage(array $langs): ?string .[method]
-----------------------------------------------
Detectează limba. Ca parametru `$lang`, se trece o matrice de limbi pe care aplicația le acceptă, iar acesta o returnează pe cea preferată de browser. Nu este vorba de magie, metoda folosește doar antetul `Accept-Language`. Dacă nu se găsește nicio potrivire, se returnează `null`.

```php
// Antetul trimis de browser: Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // Limbi acceptate în aplicație
echo $httpRequest->detectLanguage($langs); // en
```


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

Obiectul cererii HTTP curente este creat de [api:Nette\Http\RequestFactory]. Dacă scrieți o aplicație care nu utilizează un container DI, creați o cerere după cum urmează:

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

RequestFactory poate fi configurat înainte de a apela `fromGlobals()`. Putem dezactiva toate măsurile de igienizare a parametrilor de intrare din secvențe UTF-8 invalide folosind `$factory->setBinary()`. Și, de asemenea, să configurăm un server proxy, care este important pentru detectarea corectă a adresei IP a utilizatorului folosind `$factory->setProxy(...)`.

Este posibil să curățăm URL-urile de caracterele care pot intra în ele din cauza sistemelor de comentarii prost implementate pe diverse alte site-uri web prin utilizarea filtrelor:

```php
// eliminați spațiile din cale
$requestFactory->urlFilters['path']['%20'] = '';

// elimină punctul, virgula sau paranteza dreaptă de la sfârșitul URL-ului
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// curăță calea de slash-uri duplicate (filtru implicit)
$requestFactory->urlFilters['path']['/{2,}'] = '/';
```


Fișiere încărcate .[#toc-uploaded-files]
========================================

Metoda `Nette\Http\Request::getFiles()` returnează un arbore de fișiere încărcate într-o structură normalizată, fiecare frunză fiind o instanță de [api:Nette\Http\FileUpload]. Aceste obiecte încapsulează datele trimise de către `<input type=file>` element de formular.

Structura reflectă denumirea elementelor din HTML. În cel mai simplu exemplu, acesta ar putea fi un singur element de formular cu nume, trimis ca:

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

În acest caz, `$request->getFiles()` returnează o matrice:

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

Obiectul `FileUpload` este creat chiar dacă utilizatorul nu a încărcat niciun fișier sau dacă încărcarea a eșuat. Metoda `hasFile()` returnează true în cazul în care a fost trimis un fișier:

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

În cazul unei intrări care utilizează notația de matrice pentru nume:

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

arborele returnat arată astfel:

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

De asemenea, puteți crea array-uri de fișiere:

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

În acest caz, structura arată astfel:

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

Cel mai bun mod de a accesa indexul 1 al unei matrice imbricate este după cum urmează:

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

Deoarece nu puteți avea încredere în datele din exterior și, prin urmare, nu vă bazați pe forma structurii, această metodă este mai sigură decât `$request->getFiles()['my-form']['details']['avatars'][1]`, care poate da greș.


Prezentare generală a metodelor `FileUpload` .{toc: FileUpload}
---------------------------------------------------------------


hasFile(): bool .[method]
-------------------------
Returnează `true` dacă utilizatorul a încărcat un fișier.


isOk(): bool .[method]
----------------------
Returnează `true` dacă fișierul a fost încărcat cu succes.


getError(): int .[method]
-------------------------
Returnează codul de eroare asociat cu fișierul încărcat. Acesta este una dintre constantele [UPLOAD_ERR_XXX |http://php.net/manual/en/features.file-upload.errors.php]. În cazul în care fișierul a fost încărcat cu succes, se returnează `UPLOAD_ERR_OK`.


move(string $dest) .[method]
----------------------------
Mută un fișier încărcat într-o nouă locație. Dacă fișierul de destinație există deja, acesta va fi suprascris.

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


getContents(): ?string .[method]
--------------------------------
Returnează conținutul fișierului încărcat. În cazul în care încărcarea nu a avut succes, se returnează `null`.


getContentType(): ?string .[method]
-----------------------------------
Detectează tipul de conținut MIME al fișierului încărcat pe baza semnăturii acestuia. În cazul în care încărcarea nu a avut succes sau detectarea a eșuat, se returnează `null`.

.[caution]
Necesită extensia PHP `fileinfo`.


getUntrustedName(): string .[method]
------------------------------------
Returnează numele original al fișierului, așa cum a fost transmis de către browser.

.[caution]
Nu aveți încredere în valoarea returnată de această metodă. Un client ar putea trimite un nume de fișier malițios cu intenția de a vă corupe sau de a vă sparge aplicația.


getSanitizedName(): string .[method]
------------------------------------
Returnează numele de fișier curățat. Acesta conține numai caractere ASCII `[a-zA-Z0-9.-]`. Dacă numele nu conține astfel de caractere, se returnează "necunoscut". Dacă fișierul este o imagine JPEG, PNG, GIF sau WebP, se returnează extensia corectă a fișierului.

.[caution]
Necesită extensia PHP `fileinfo`.


getSuggestedExtension(): ?string .[method]{data-version:3.2.4}
--------------------------------------------------------------
Returnează extensia de fișier corespunzătoare (fără punct) care corespunde tipului MIME detectat.

.[caution]
Necesită extensia PHP `fileinfo`.


getUntrustedFullPath(): string .[method]
----------------------------------------
Returnează calea completă originală, așa cum a fost transmisă de browser în timpul încărcării directorului. Calea completă este disponibilă numai în PHP 8.1 și versiunile ulterioare. În versiunile anterioare, această metodă returnează numele fișierului care nu este de încredere.

.[caution]
Nu aveți încredere în valoarea returnată de această metodă. Un client ar putea trimite un nume de fișier malițios cu intenția de a vă corupe sau de a vă pirata aplicația.


getSize(): int .[method]
------------------------
Returnează dimensiunea fișierului încărcat. În cazul în care încărcarea nu a avut succes, se returnează `0`.


getTemporaryFile(): string .[method]
------------------------------------
Returnează calea de acces la locația temporară a fișierului încărcat. În cazul în care încărcarea nu a avut succes, se returnează `''`.


isImage(): bool .[method]
-------------------------
Returnează `true` în cazul în care fișierul încărcat este o imagine JPEG, PNG, GIF sau WebP. Detectarea se bazează pe semnătura acestuia. Integritatea întregului fișier nu este verificată. Puteți afla dacă o imagine nu este coruptă, de exemplu, încercând să [o încărcați |#toImage].

.[caution]
Necesită extensia PHP `fileinfo`.


getImageSize(): ?array .[method]
--------------------------------
Returnează o pereche de `[width, height]` cu dimensiunile imaginii încărcate. În cazul în care încărcarea nu a avut succes sau nu este o imagine validă, se returnează `null`.


toImage(): Nette\Utils\Image .[method]
--------------------------------------
Încarcă o imagine sub forma unui obiect [Image |utils:images]. În cazul în care încărcarea nu a avut succes sau nu este o imagine validă, se aruncă o excepție `Nette\Utils\ImageException`.