HTTP Request

Nette incapsula la richiesta HTTP in oggetti con un'API comprensibile e fornisce allo stesso tempo un filtro di sanificazione.

La richiesta HTTP è rappresentata dall'oggetto Nette\Http\Request. Se lavorate con Nette, questo oggetto viene creato automaticamente dal framework e potete riceverlo tramite dependency injection. Nei presenter, basta chiamare il metodo $this->getHttpRequest(). Se lavorate al di fuori del Nette Framework, potete creare l'oggetto usando RequestFactory.

Un grande vantaggio di Nette è che durante la creazione dell'oggetto, pulisce automaticamente tutti i parametri di input GET, POST, COOKIE e anche l'URL dai caratteri di controllo e dalle sequenze UTF-8 non valide. Potete quindi lavorare in sicurezza con questi dati. I dati puliti vengono successivamente utilizzati nei presenter e nei form.

→ Installazione e requisiti

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 il valore modificato.

withUrl (Nette\Http\UrlScript $url): Nette\Http\Request

Restituisce un clone con un URL diverso.

getUrl(): Nette\Http\UrlScript

Restituisce l'URL della richiesta come oggetto UrlScript.

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

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

getQuery (?string $key=null): string|array|null

Restituisce i parametri GET della richiesta.

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

getPost (?string $key=null): string|array|null

Restituisce i parametri POST della richiesta.

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

getFile (string|string[] $key): Nette\Http\FileUpload|array|null

Restituisce l'upload come oggetto Nette\Http\FileUpload:

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

Per accedere alla struttura nidificata, specificare un array di chiavi.

//<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 nemmeno fare affidamento sulla forma della struttura dei file, questo metodo è più sicuro rispetto, ad esempio, a $request->getFiles()['my-form']['details']['avatar'], che potrebbe fallire.

getFiles(): array

Restituisce l'albero di tutti gli upload in una struttura normalizzata, le cui foglie sono oggetti Nette\Http\FileUpload:

$files = $httpRequest->getFiles();

getCookie (string $key): string|array|null

Restituisce un cookie o null se non esiste.

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

getCookies(): array

Restituisce tutti i cookie.

$cookies = $httpRequest->getCookies();

getMethod(): string

Restituisce il metodo HTTP con cui è stata effettuata la richiesta.

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

isMethod (string $method): bool

Verifica il metodo HTTP con cui è stata effettuata la richiesta. Il parametro è case-insensitive.

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

getHeader (string $header): ?string

Restituisce un header HTTP o null se non esiste. Il parametro è case-insensitive.

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

getHeaders(): array

Restituisce tutti gli header HTTP come array associativo.

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

isSecured(): bool

La connessione è crittografata (HTTPS)? Potrebbe essere necessario impostare il proxy per un corretto funzionamento.

isSameSite(): bool

La richiesta proviene dallo stesso (sotto)dominio ed è stata avviata facendo clic su un link? Nette utilizza il cookie _nss (precedentemente nette-samesite) per il rilevamento.

isAjax(): bool

È una richiesta AJAX?

getRemoteAddress(): ?string

Restituisce l'indirizzo IP dell'utente. Potrebbe essere necessario impostare il proxy per un corretto funzionamento.

getRemoteHost(): ?string

Restituisce la traduzione DNS dell'indirizzo IP dell'utente. Potrebbe essere necessario impostare il proxy per un corretto funzionamento.

getBasicCredentials(): ?array

Restituisce le credenziali di autenticazione per Basic HTTP authentication.

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

getRawBody(): ?string

Restituisce il corpo della richiesta HTTP.

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

Rileva la lingua. Come parametro $lang passiamo un array con le lingue supportate dall'applicazione, e restituirà quella che il browser del visitatore preferirebbe vedere. Non c'è magia, si utilizza semplicemente l'header Accept-Language. Se non c'è corrispondenza, restituisce null.

// il browser invia ad es. Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

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

RequestFactory

La classe Nette\Http\RequestFactory serve per creare un'istanza di Nette\Http\Request, che rappresenta la richiesta HTTP corrente. (Se lavorate con Nette, l'oggetto della richiesta HTTP viene creato automaticamente dal framework.)

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

Il metodo fromGlobals() crea l'oggetto della richiesta in base alle variabili globali PHP correnti ($_GET, $_POST, $_COOKIE, $_FILES e $_SERVER). Durante la creazione dell'oggetto, pulisce automaticamente tutti i parametri di input GET, POST, COOKIE e anche l'URL dai caratteri di controllo e dalle sequenze UTF-8 non valide, garantendo la sicurezza nel successivo lavoro con questi dati.

RequestFactory può essere configurata prima di chiamare fromGlobals():

  • con il metodo $factory->setBinary() disabilitate la pulizia automatica dei parametri di input dai caratteri di controllo e dalle sequenze UTF-8 non valide.
  • con il metodo $factory->setProxy(...) specificate l'indirizzo IP del server proxy, necessario per il corretto rilevamento dell'indirizzo IP dell'utente.

RequestFactory consente di definire filtri che trasformano automaticamente parti dell'URL della richiesta. Questi filtri rimuovono caratteri indesiderati dall'URL, che possono essere inseriti lì, ad esempio, da un'implementazione errata dei sistemi di commento su vari siti web:

// rimozione degli spazi dal percorso
$requestFactory->urlFilters['path']['%20'] = '';

// rimozione di punto, virgola o parentesi destra dalla fine dell'URI
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// pulizia del percorso dalle doppie barre (filtro predefinito)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

La prima chiave 'path' o 'url' specifica a quale parte dell'URL applicare il filtro. La seconda chiave è l'espressione regolare da cercare e il valore è la sostituzione da utilizzare al posto del testo trovato.

File Caricati

Il metodo Nette\Http\Request::getFiles() restituisce un array di tutti gli upload in una struttura normalizzata, le cui foglie sono oggetti Nette\Http\FileUpload. Questi incapsulano i dati inviati dall'elemento del form <input type=file>.

La struttura riflette la denominazione degli elementi in HTML. Nel caso più semplice, può essere un singolo elemento del form nominato inviato come:

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

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

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

L'oggetto FileUpload viene creato anche nel caso in cui l'utente non abbia inviato alcun file o l'invio sia fallito. Il metodo hasFile() restituisce se il file è stato inviato:

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

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

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

l'albero restituito appare così:

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

È possibile creare anche un array di file:

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

In tal caso, la struttura appare così:

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

Il modo migliore per accedere all'indice 1 dell'array nidificato è il seguente:

$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 nemmeno fare affidamento sulla forma della struttura dei file, questo metodo è più sicuro rispetto, ad esempio, a $request->getFiles()['my-form']['details']['avatars'][1], che potrebbe fallire.

Panoramica dei metodi FileUpload

hasFile(): bool

Restituisce true se l'utente ha caricato un file.

isOk(): bool

Restituisce true se il file è stato caricato con successo.

getError(): int

Restituisce il codice di errore durante il caricamento del file. È una delle costanti UPLOAD_ERR_XXX. Se il caricamento è avvenuto correttamente, restituisce UPLOAD_ERR_OK.

move (string $dest)

Sposta il file caricato in una nuova posizione. Se il file di destinazione esiste già, verrà sovrascritto.

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

getContents(): ?string

Restituisce il contenuto del file caricato. Se il caricamento non è andato a buon fine, restituisce null.

getContentType(): ?string

Rileva il tipo di contenuto MIME del file caricato in base alla sua firma. Se il caricamento non è andato a buon fine o il rilevamento fallisce, restituisce null.

Richiede l'estensione PHP fileinfo.

getUntrustedName(): string

Restituisce il nome originale del file, come inviato dal browser.

Non fidatevi del valore restituito da questo metodo. Il client potrebbe aver inviato un nome di file dannoso con l'intenzione di danneggiare o hackerare la vostra applicazione.

getSanitizedName(): string

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 in formato JPEG, PNG, GIF, WebP o AVIF, restituisce anche l'estensione corretta.

Richiede l'estensione PHP fileinfo.

getSuggestedExtension(): ?string

Restituisce un'estensione di file appropriata (senza punto) corrispondente al tipo MIME rilevato.

Richiede l'estensione PHP fileinfo.

getUntrustedFullPath(): string

Restituisce il percorso originale del file, come inviato dal browser durante il caricamento di una cartella. Il percorso completo è disponibile solo in PHP 8.1 e versioni successive. Nelle versioni precedenti, questo metodo restituisce il nome originale del file.

Non fidatevi del valore restituito da questo metodo. Il client potrebbe aver inviato un nome di file dannoso con l'intenzione di danneggiare o hackerare la vostra applicazione.

getSize(): int

Restituisce la dimensione del file caricato. Se il caricamento non è andato a buon fine, restituisce 0.

getTemporaryFile(): string

Restituisce il percorso della posizione temporanea del file caricato. Se il caricamento non è andato a buon fine, restituisce ''.

isImage(): bool

Restituisce true se il file caricato è un'immagine in formato JPEG, PNG, GIF, WebP o AVIF. Il rilevamento avviene in base alla sua firma e non viene verificata l'integrità dell'intero file. È possibile verificare se un'immagine è danneggiata, ad esempio, provando a caricarla.

Richiede l'estensione PHP fileinfo.

getImageSize(): ?array

Restituisce la coppia [larghezza, altezza] con le dimensioni dell'immagine caricata. Se il caricamento non è andato a buon fine o non si tratta di un'immagine valida, restituisce null.

toImage(): Nette\Utils\Image

Carica l'immagine come oggetto Image. Se il caricamento non è andato a buon fine o non si tratta di un'immagine valida, lancia un'eccezione Nette\Utils\ImageException.

  1. Documentazione
  2. Nette HTTP
  3. HTTP Request
versione: 4.0