Cerere HTTP

Nette încapsulează cererea HTTP în obiecte cu un API ușor de înțeles, oferind în același timp un filtru de curățare.

O solicitare HTTP este un obiect Nette\Http\Request, pe care îl obțineți trecându-l folosind injecția de dependență. În prezentatori, pur și simplu apelați $httpRequest = $this->getHttpRequest().

Ceea ce este important este că Nette, atunci când creează acest obiect, curăță toți parametrii de intrare GET, POST și COOKIE, precum și URL-urile de caractere de control și secvențe UTF-8 invalide. Astfel, puteți continua să lucrați în siguranță cu datele. Datele curățate sunt apoi utilizate în prezentatori și formulare.

→ Instalare și cerințe

Nette\Http\Request

Acest obiect este imuabil. Nu are setori, are doar un singur așa-numit wither withUrl(), care nu modifică obiectul, ci returnează o nouă instanță cu o valoare modificată.

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

Returnează o clonă cu o adresă URL diferită.

getUrl(): Nette\Http\UrlScript

Returnează adresa URL a cererii ca obiect UrlScript.

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

Browserele nu trimit un fragment către server, astfel încât $url->getFragment() va returna un șir gol.

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

Returnează parametrii cererii GET:

$all = $httpRequest->getQuery();    // matrice cu toți parametrii URL
$id = $httpRequest->getQuery('id'); // returnează parametrul GET "id" (sau nul)

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

Returnează parametrii cererii POST:

$all = $httpRequest->getPost();     // matrice cu toți parametrii POST
$id = $httpRequest->getPost('id');  // returnează parametrul POST "id" (sau null)

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

Returnează încărcarea ca obiect Nette\Http\FileUpload:

$file = $httpRequest->getFile('avatar');
if ($file->hasFile()) { // a fost încărcat vreun fișier?
	$file->getUntrustedName(); // numele fișierului trimis de utilizator
	$file->getSanitizedName(); // numele fără caractere periculoase
}

Specificați un tablou de chei pentru a accesa structura subarborelui.

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

Deoarece nu puteți avea încredere în datele din exterior și, prin urmare, nu vă bazați pe forma structurii, această metodă este mai sigură decât $request->getFiles()['my-form']['details']['avatar'], care poate da greș.

getFiles(): array

Returnează arborele de fișiere de încărcare într-o structură normalizată, fiecare frunză fiind o instanță a Nette\Http\FileUpload:

$files = $httpRequest->getFiles();

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

Returnează un cookie sau null dacă acesta nu există.

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

getCookies(): array

Returnează toate cookie-urile:

$cookies = $httpRequest->getCookies();

getMethod(): string

Returnează metoda HTTP cu care a fost făcută cererea.

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

isMethod(string $method): bool

Verifică metoda HTTP cu care a fost efectuată cererea. Parametrul nu ține cont de majuscule și minuscule.

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

getHeader(string $header): ?string

Returnează un antet HTTP sau null dacă acesta nu există. Parametrul nu ține cont de majuscule și minuscule:

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

getHeaders(): array

Returnează toate antetele HTTP ca matrice asociativă:

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

isSecured(): bool

Conexiunea este criptată (HTTPS)? Este posibil să fie necesar să configurați un proxy pentru o funcționalitate corespunzătoare.

isSameSite(): bool

Solicitarea provine de la același (sub)domeniu și este inițiată prin apăsarea unui link? Nette utilizează cookie-ul _nss (fost nette-samesite) pentru a detecta acest lucru.

isAjax(): bool

Este o cerere AJAX?

getRemoteAddress(): ?string

Returnează adresa IP a utilizatorului. Este posibil să fie necesar să configurați un proxy pentru o funcționalitate corespunzătoare.

getRemoteHost(): ?string

Returnează traducerea DNS a adresei IP a utilizatorului. Este posibil să fie necesar să configurați un proxy pentru o funcționalitate corespunzătoare.

getBasicCredentials(): ?string

Returnează acreditările de autentificare HTTP de bază.

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

getRawBody(): ?string

Returnează corpul solicitării HTTP:

$body = $httpRequest->getRawBody();

detectLanguage(array $langs): ?string

Detectează limba. Ca parametru $lang, se trece o matrice de limbi pe care aplicația le acceptă, iar acesta o returnează pe cea preferată de browser. Nu este vorba de magie, metoda folosește doar antetul Accept-Language. Dacă nu se găsește nicio potrivire, se returnează null.

// Antetul trimis de browser: Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // Limbi acceptate în aplicație
echo $httpRequest->detectLanguage($langs); // en

RequestFactory

Obiectul cererii HTTP curente este creat de Nette\Http\RequestFactory. Dacă scrieți o aplicație care nu utilizează un container DI, creați o cerere după cum urmează:

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

RequestFactory poate fi configurat înainte de a apela fromGlobals(). Putem dezactiva toate măsurile de igienizare a parametrilor de intrare din secvențe UTF-8 invalide folosind $factory->setBinary(). Și, de asemenea, să configurăm un server proxy, care este important pentru detectarea corectă a adresei IP a utilizatorului folosind $factory->setProxy(...).

Este posibil să curățăm URL-urile de caracterele care pot intra în ele din cauza sistemelor de comentarii prost implementate pe diverse alte site-uri web prin utilizarea filtrelor:

// eliminați spațiile din cale
$requestFactory->urlFilters['path']['%20'] = '';

// elimină punctul, virgula sau paranteza dreaptă de la sfârșitul URL-ului
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// curăță calea de slash-uri duplicate (filtru implicit)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

Fișiere încărcate

Metoda Nette\Http\Request::getFiles() returnează un arbore de fișiere încărcate într-o structură normalizată, fiecare frunză fiind o instanță de Nette\Http\FileUpload. Aceste obiecte încapsulează datele trimise de către <input type=file> element de formular.

Structura reflectă denumirea elementelor din HTML. În cel mai simplu exemplu, acesta ar putea fi un singur element de formular cu nume, trimis ca:

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

În acest caz, $request->getFiles() returnează o matrice:

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

Obiectul FileUpload este creat chiar dacă utilizatorul nu a încărcat niciun fișier sau dacă încărcarea a eșuat. Metoda hasFile() returnează true în cazul în care a fost trimis un fișier:

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

În cazul unei intrări care utilizează notația de matrice pentru nume:

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

arborele returnat arată astfel:

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

De asemenea, puteți crea array-uri de fișiere:

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

În acest caz, structura arată astfel:

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

Cel mai bun mod de a accesa indexul 1 al unei matrice imbricate este după cum urmează:

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

Prezentare generală a metodelor `FileUpload`

hasFile(): bool

Returnează true dacă utilizatorul a încărcat un fișier.

isOk(): bool

Returnează true dacă fișierul a fost încărcat cu succes.

getError(): int

Returnează codul de eroare asociat cu fișierul încărcat. Acesta este una dintre constantele UPLOAD_ERR_XXX. În cazul în care fișierul a fost încărcat cu succes, se returnează UPLOAD_ERR_OK.

move(string $dest)

Mută un fișier încărcat într-o nouă locație. Dacă fișierul de destinație există deja, acesta va fi suprascris.

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

getContents(): ?string

Returnează conținutul fișierului încărcat. În cazul în care încărcarea nu a avut succes, se returnează null.

getContentType(): ?string

Detectează tipul de conținut MIME al fișierului încărcat pe baza semnăturii acestuia. În cazul în care încărcarea nu a avut succes sau detectarea a eșuat, se returnează null.

Necesită extensia PHP fileinfo.

getUntrustedName(): string

Returnează numele original al fișierului, așa cum a fost transmis de către browser.

Nu aveți încredere în valoarea returnată de această metodă. Un client ar putea trimite un nume de fișier malițios cu intenția de a vă corupe sau de a vă sparge aplicația.

getSanitizedName(): string

Returnează numele de fișier curățat. Acesta conține numai caractere ASCII [a-zA-Z0-9.-]. Dacă numele nu conține astfel de caractere, se returnează “necunoscut”. Dacă fișierul este o imagine JPEG, PNG, GIF sau WebP, se returnează extensia corectă a fișierului.

Necesită extensia PHP fileinfo.

getSuggestedExtension(): ?string

Returnează extensia de fișier corespunzătoare (fără punct) care corespunde tipului MIME detectat.

Necesită extensia PHP fileinfo.

getUntrustedFullPath(): string

Returnează calea completă originală, așa cum a fost transmisă de browser în timpul încărcării directorului. Calea completă este disponibilă numai în PHP 8.1 și versiunile ulterioare. În versiunile anterioare, această metodă returnează numele fișierului care nu este de încredere.

Nu aveți încredere în valoarea returnată de această metodă. Un client ar putea trimite un nume de fișier malițios cu intenția de a vă corupe sau de a vă pirata aplicația.

getSize(): int

Returnează dimensiunea fișierului încărcat. În cazul în care încărcarea nu a avut succes, se returnează 0.

getTemporaryFile(): string

Returnează calea de acces la locația temporară a fișierului încărcat. În cazul în care încărcarea nu a avut succes, se returnează ''.

isImage(): bool

Returnează true în cazul în care fișierul încărcat este o imagine JPEG, PNG, GIF sau WebP. Detectarea se bazează pe semnătura acestuia. Integritatea întregului fișier nu este verificată. Puteți afla dacă o imagine nu este coruptă, de exemplu, încercând să o încărcați.

Necesită extensia PHP fileinfo.

getImageSize(): ?array

Returnează o pereche de [width, height] cu dimensiunile imaginii încărcate. În cazul în care încărcarea nu a avut succes sau nu este o imagine validă, se returnează null.

toImage(): Nette\Utils\Image

Încarcă o imagine sub forma unui obiect Image. În cazul în care încărcarea nu a avut succes sau nu este o imagine validă, se aruncă o excepție Nette\Utils\ImageException.

Cerere HTTP

Nette\Http\Request

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

RequestFactory

Fișiere încărcate

Prezentare generală a metodelor 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

Prezentare generală a metodelor `FileUpload`