Richiesta HTTP
**************

.[perex]
Nette incapsula la richiesta HTTP in oggetti con un'API comprensibile e fornisce un filtro di sanificazione.

Una richiesta HTTP è un oggetto [api:Nette\Http\Request], che si ottiene passandoglielo usando la [dependency injection |dependency-injection:passing-dependencies]. Nei presentatori è sufficiente chiamare `$httpRequest = $this->getHttpRequest()`.

L'importante è che Nette, quando [crea |#RequestFactory] questo oggetto, cancelli tutti i parametri di input GET, POST e COOKIE, nonché gli URL con caratteri di controllo e sequenze UTF-8 non valide. In questo modo si può continuare a lavorare con i dati in tutta sicurezza. I dati puliti vengono poi utilizzati nei presentatori e nei moduli.

→ [Installazione e requisiti |@home#Installation]


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

Questo oggetto è immutabile. Non ha setter, ha solo un cosiddetto wither `withUrl()`, che non modifica l'oggetto, ma restituisce una nuova istanza con un valore modificato.


withUrl(Nette\Http\UrlScript $url): Nette\Http\Request .[method]
----------------------------------------------------------------
Restituisce un clone con un URL diverso.


getUrl(): Nette\Http\UrlScript .[method]
----------------------------------------
Restituisce l'URL della richiesta come oggetto [UrlScript |urls#UrlScript].

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

Attenzione: I browser non inviano un frammento al server, quindi `$url->getFragment()` restituirà una stringa vuota.


getQuery(?string $key=null): string|array|null .[method]
--------------------------------------------------------
Restituisce i parametri della richiesta GET:

```php
$all = $httpRequest->getQuery(); // array di tutti i parametri URL
$id = $httpRequest->getQuery('id'); // restituisce il parametro GET 'id' (o null)
```


getPost(?string $key=null): string|array|null .[method]
-------------------------------------------------------
Restituisce i parametri della richiesta POST:

```php
$all = $httpRequest->getPost(); // array di tutti i parametri POST
$id = $httpRequest->getPost('id'); // restituisce il parametro POST 'id' (o null)
```


getFile(string|string[] $key): Nette\Http\FileUpload|array|null .[method]
-------------------------------------------------------------------------
Restituisce il [caricamento |#Uploaded Files] come oggetto [api:Nette\Http\FileUpload]:

```php
$file = $httpRequest->getFile('avatar');
if ($file->hasFile()) { // è stato caricato un file?
	$file->getUntrustedName(); // nome del file inviato dall'utente
	$file->getSanitizedName(); // il nome senza caratteri pericolosi
}
```

Specificare un array di chiavi per accedere alla struttura del sottoalbero.

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

Poiché non ci si può fidare dei dati provenienti dall'esterno e quindi non si fa affidamento sulla forma della struttura, questo metodo è più sicuro rispetto a `$request->getFiles()['my-form']['details']['avatar']`che può fallire.


getFiles(): array .[method]
---------------------------
Restituisce un albero di [file di upload |#Uploaded Files] in una struttura normalizzata, con ogni foglia un'istanza di [api:Nette\Http\FileUpload]:

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


getCookie(string $key): string|array|null .[method]
---------------------------------------------------
Restituisce un cookie o `null` se non esiste.

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


getCookies(): array .[method]
-----------------------------
Restituisce tutti i cookie:

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


getMethod(): string .[method]
-----------------------------
Restituisce il metodo HTTP con cui è stata effettuata la richiesta.

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


isMethod(string $method): bool .[method]
----------------------------------------
Verifica il metodo HTTP con cui è stata effettuata la richiesta. Il parametro non fa distinzione tra maiuscole e minuscole.

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


getHeader(string $header): ?string .[method]
--------------------------------------------
Restituisce un'intestazione HTTP o `null` se non esiste. Il parametro non fa distinzione tra maiuscole e minuscole:

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


getHeaders(): array .[method]
-----------------------------
Restituisce tutte le intestazioni HTTP come array associativo:

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


isSecured(): bool .[method]
---------------------------
La connessione è criptata (HTTPS)? Potrebbe essere necessario [impostare un proxy |configuration#HTTP proxy] per una corretta funzionalità.


isSameSite(): bool .[method]
----------------------------
La richiesta proviene dallo stesso (sotto)dominio ed è iniziata facendo clic su un link? Nette utilizza il cookie `_nss` (ex `nette-samesite`) per rilevarlo.


isAjax(): bool .[method]
------------------------
È una richiesta AJAX?


getRemoteAddress(): ?string .[method]
-------------------------------------
Restituisce l'indirizzo IP dell'utente. Potrebbe essere necessario [impostare un proxy |configuration#HTTP proxy] per una corretta funzionalità.


getRemoteHost(): ?string .[method deprecated]
---------------------------------------------
Restituisce la traduzione DNS dell'indirizzo IP dell'utente. Potrebbe essere necessario [impostare un proxy |configuration#HTTP proxy] per una corretta funzionalità.


getBasicCredentials(): ?string .[method]
----------------------------------------
Restituisce le credenziali di [autenticazione HTTP di base |https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication].

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


getRawBody(): ?string .[method]
-------------------------------
Restituisce il corpo della richiesta HTTP:

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


detectLanguage(array $langs): ?string .[method]
-----------------------------------------------
Rileva la lingua. Come parametro `$lang`, si passa un array di lingue supportate dall'applicazione e viene restituita quella preferita dal browser. Non è una magia, il metodo utilizza semplicemente l'intestazione `Accept-Language`. Se non c'è corrispondenza, restituisce `null`.

```php
// Intestazione inviata dal browser: Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // lingue supportate nell'applicazione
echo $httpRequest->detectLanguage($langs); // en
```


Fabbrica di richieste .[#toc-requestfactory]
============================================

L'oggetto della richiesta HTTP corrente viene creato da [api:Nette\Http\RequestFactory]. Se si sta scrivendo un'applicazione che non utilizza un contenitore DI, si crea una richiesta come segue:

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

La RequestFactory può essere configurata prima di chiamare `fromGlobals()`. Possiamo disabilitare tutta la sanitizzazione dei parametri di input da sequenze UTF-8 non valide, usando `$factory->setBinary()`. E anche impostare un server proxy, importante per il corretto rilevamento dell'indirizzo IP dell'utente, utilizzando `$factory->setProxy(...)`.

È possibile ripulire gli URL dai caratteri che possono entrare in essi a causa di sistemi di commento mal implementati su vari altri siti web, utilizzando dei filtri:

```php
// rimuovere gli spazi dal percorso
$requestFactory->urlFilters['path']['%20'] = '';

// rimuove il punto, la virgola o la parentesi destra alla fine dell'URL
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// pulisce il percorso dagli slash duplicati (filtro predefinito)
$requestFactory->urlFilters['path']['/{2,}'] = '/';
```


File caricati .[#toc-uploaded-files]
====================================

Il metodo `Nette\Http\Request::getFiles()` restituisce un albero di file caricati in una struttura normalizzata, con ogni foglia un'istanza di [api:Nette\Http\FileUpload]. Questi oggetti incapsulano i dati inviati dall'elemento del form. `<input type=file>` elemento del modulo.

La struttura riflette la denominazione degli elementi in HTML. Nell'esempio più semplice, potrebbe trattarsi di un singolo elemento del modulo con nome, inviato come:

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

In questo caso, `$request->getFiles()` restituisce un array:

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

L'oggetto `FileUpload` viene creato anche se l'utente non ha caricato alcun file o il caricamento è fallito. Il metodo `hasFile()` restituisce true se è stato inviato un file:

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

Nel caso di un input che utilizza la notazione array per il nome:

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

l'albero restituito finisce per assomigliare a questo:

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

È anche possibile creare array di file:

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

In questo caso la struttura appare come:

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

Il modo migliore per accedere all'indice 1 di un array annidato è il seguente:

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

Poiché non ci si può fidare dei dati provenienti dall'esterno e quindi non si fa affidamento sulla forma della struttura, questo metodo è più sicuro rispetto a `$request->getFiles()['my-form']['details']['avatars'][1]`che può fallire.


Panoramica dei metodi di `FileUpload` .{toc: FileUpload}
--------------------------------------------------------


hasFile(): bool .[method]
-------------------------
Restituisce `true` se l'utente ha caricato un file.


isOk(): bool .[method]
----------------------
Restituisce `true` se il file è stato caricato con successo.


getError(): int .[method]
-------------------------
Restituisce il codice di errore associato al file caricato. È una delle costanti [UPLOAD_ERR_XXX |http://php.net/manual/en/features.file-upload.errors.php]. Se il file è stato caricato con successo, restituisce `UPLOAD_ERR_OK`.


move(string $dest) .[method]
----------------------------
Sposta un file caricato in una nuova posizione. Se il file di destinazione esiste già, verrà sovrascritto.

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


getContents(): ?string .[method]
--------------------------------
Restituisce il contenuto del file caricato. Se il caricamento non è riuscito, restituisce `null`.


getContentType(): ?string .[method]
-----------------------------------
Rileva il tipo di contenuto MIME del file caricato in base alla sua firma. Se il caricamento non è riuscito o il rilevamento non è andato a buon fine, restituisce `null`.

.[caution]
Richiede l'estensione PHP `fileinfo`.


getUntrustedName(): string .[method]
------------------------------------
Restituisce il nome originale del file come inviato dal browser.

.[caution]
Non fidarsi del valore restituito da questo metodo. Un client potrebbe inviare un nome di file dannoso con l'intento di corrompere o hackerare l'applicazione.


getSanitizedName(): string .[method]
------------------------------------
Restituisce il nome del file sanificato. Contiene solo caratteri ASCII `[a-zA-Z0-9.-]`. Se il nome non contiene tali caratteri, restituisce "unknown". Se il file è un'immagine JPEG, PNG, GIF o WebP, restituisce l'estensione corretta.

.[caution]
Richiede l'estensione PHP `fileinfo`.


getSuggestedExtension(): ?string .[method]{data-version:3.2.4}
--------------------------------------------------------------
Restituisce l'estensione di file appropriata (senza il punto) corrispondente al tipo MIME rilevato.

.[caution]
Richiede l'estensione PHP `fileinfo`.


getUntrustedFullPath(): string .[method]
----------------------------------------
Restituisce il percorso completo originale inviato dal browser durante il caricamento della directory. Il percorso completo è disponibile solo in PHP 8.1 e versioni successive. Nelle versioni precedenti, questo metodo restituisce il nome del file non attendibile.

.[caution]
Non fidarsi del valore restituito da questo metodo. Un client potrebbe inviare un nome di file dannoso con l'intenzione di corrompere o hackerare l'applicazione.


getSize(): int .[method]
------------------------
Restituisce la dimensione del file caricato. Se il caricamento non è riuscito, restituisce `0`.


getTemporaryFile(): string .[method]
------------------------------------
Restituisce il percorso della posizione temporanea del file caricato. Se il caricamento non è riuscito, restituisce `''`.


isImage(): bool .[method]
-------------------------
Restituisce `true` se il file caricato è un'immagine JPEG, PNG, GIF o WebP. Il rilevamento si basa sulla sua firma. L'integrità dell'intero file non viene controllata. È possibile scoprire se un'immagine non è danneggiata, ad esempio provando a [caricarla |#toImage].

.[caution]
Richiede l'estensione PHP `fileinfo`.


getImageSize(): ?array .[method]
--------------------------------
Restituisce una coppia di elementi `[width, height]` con le dimensioni dell'immagine caricata. Se il caricamento non è riuscito o non è un'immagine valida, restituisce `null`.


toImage(): Nette\Utils\Image .[method]
--------------------------------------
Carica un'immagine come oggetto [Image |utils:images]. Se il caricamento non è avvenuto con successo o non è un'immagine valida, viene lanciata un'eccezione `Nette\Utils\ImageException`.