Richiesta HTTP

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

La richiesta HTTP è rappresentata dall'oggetto Nette\Http\Request. Se si lavora con Nette, questo oggetto viene creato automaticamente dal framework e può essere passato tramite dependency injection. Nei presenter, è sufficiente chiamare il metodo $this->getHttpRequest(). Se si lavora al di fuori del framework Nette, è possibile creare l'oggetto utilizzando RequestFactory.

Un grande vantaggio di Nette è che, al momento della creazione dell'oggetto, sanifica automaticamente tutti i parametri di input GET, POST, COOKIE e gli URL dai caratteri di controllo e dalle sequenze UTF-8 non valide. È quindi possibile lavorare in modo sicuro con questi dati. I dati sanificati vengono successivamente utilizzati nei presentatori e nei moduli.

→ Installazione e requisiti

Richiesta Nette Http

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

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://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

Restituisce i parametri della richiesta GET:

$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

Restituisce i parametri della richiesta POST:

$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

Restituisce il caricamento come oggetto Nette\Http\FileUpload:

$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.

//<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

Restituisce un albero di file di upload in una struttura normalizzata, con ogni foglia un'istanza di 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.

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

isMethod (string $method): bool

Verifica il metodo HTTP con cui è stata effettuata la richiesta. Il parametro non fa distinzione tra maiuscole e minuscole.

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

getHeader (string $header): ?string

Restituisce un'intestazione HTTP o null se non esiste. Il parametro non fa distinzione tra maiuscole e minuscole:

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

getHeaders(): array

Restituisce tutte le intestazioni HTTP come array associativo:

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

isSecured(): bool

La connessione è criptata (HTTPS)? Potrebbe essere necessario impostare un proxy per una corretta funzionalità.

isSameSite(): bool

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

È una richiesta AJAX?

getRemoteAddress(): ?string

Restituisce l'indirizzo IP dell'utente. Potrebbe essere necessario impostare un proxy per una corretta funzionalità.

getRemoteHost(): ?string

Restituisce la traduzione DNS dell'indirizzo IP dell'utente. Potrebbe essere necessario impostare un proxy per una corretta funzionalità.

getBasicCredentials(): ?string

Restituisce le credenziali di autenticazione HTTP di base.

[$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, 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.

// 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

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

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

Il metodo fromGlobals() crea un oggetto richiesta basato sulle 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 l'URL dai caratteri di controllo e dalle sequenze UTF-8 non valide, garantendo così la sicurezza quando si lavorerà con questi dati in seguito.

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

  • con il metodo $factory->setBinary() si può disabilitare la pulizia automatica dei parametri di input dai caratteri di controllo e dalle sequenze UTF-8 non valide.
  • con il metodo $factory->setProxy(...) si specifica 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 della richiesta di URL. Questi filtri rimuovono dagli URL i caratteri indesiderati che possono essere stati inseriti, ad esempio, da un'errata implementazione dei sistemi di commento su vari siti web:

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

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

// pulizia del percorso da doppi slash (filtro predefinito)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

La prima chiave 'path' o 'url' determina quale parte dell'URL sarà applicata al filtro. La seconda chiave è un'espressione regolare da cercare e il valore è la sostituzione da usare al posto del testo trovato.

File caricati

Il metodo Nette\Http\Request::getFiles() restituisce un albero di file caricati in una struttura normalizzata, con ogni foglia un'istanza di 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:

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

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

[
	'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:

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

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

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

l'albero restituito finisce per assomigliare a questo:

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

È anche possibile creare array di file:

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

In questo caso la struttura appare come:

[
	'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:

$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

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 associato al file caricato. È una delle costanti UPLOAD_ERR_XXX. Se il file è stato caricato con successo, restituisce UPLOAD_ERR_OK.

move (string $dest)

Sposta un 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 è riuscito, restituisce null.

getContentType(): ?string

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.

Richiede l'estensione PHP fileinfo.

getUntrustedName(): string

Restituisce il nome originale del file come inviato dal browser.

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

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.

Richiede l'estensione PHP fileinfo.

getSuggestedExtension(): ?string

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

Richiede l'estensione PHP fileinfo.

getUntrustedFullPath(): string

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.

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

Restituisce la dimensione del file caricato. Se il caricamento non è riuscito, restituisce 0.

getTemporaryFile(): string

Restituisce il percorso della posizione temporanea del file caricato. Se il caricamento non è riuscito, restituisce ''.

isImage(): bool

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.

Richiede l'estensione PHP fileinfo.

getImageSize(): ?array

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

Carica un'immagine come oggetto Image. Se il caricamento non è avvenuto con successo o non è un'immagine valida, viene lanciata un'eccezione Nette\Utils\ImageException.

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