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