Richiesta HTTP

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

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

L'importante è che Nette, quando crea 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

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

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

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

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

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) {
	// ...
}

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.

Richiesta HTTP

Richiesta Nette Http

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

getUrl(): Nette\Http\UrlScript

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

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

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

getFiles(): array

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

getCookies(): array

getMethod(): string

isMethod (string $method): bool

getHeader (string $header): ?string

getHeaders(): array

isSecured(): bool

isSameSite(): bool

isAjax(): bool

getRemoteAddress(): ?string

getRemoteHost(): ?string

getBasicCredentials(): ?string

getRawBody(): ?string

detectLanguage (array $langs): ?string

Fabbrica di richieste

File caricati

Panoramica dei metodi di FileUpload

hasFile(): bool

isOk(): bool

getError(): int

move (string $dest)

getContents(): ?string

getContentType(): ?string

getUntrustedName(): string

getSanitizedName(): string

getSuggestedExtension(): ?string

getUntrustedFullPath(): string

getSize(): int

getTemporaryFile(): string

isImage(): bool

getImageSize(): ?array

toImage(): Nette\Utils\Image

Panoramica dei metodi di `FileUpload`