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.

Cererea HTTP este reprezentată de obiectul Nette\Http\Request. Dacă lucrați cu Nette, acest obiect este creat automat de cadru și vi se poate transmite folosind injectarea dependenței. În presenters, trebuie doar să apelați metoda $this->getHttpRequest(). Dacă lucrați în afara cadrului Nette, puteți crea obiectul utilizând RequestFactory.

Un avantaj major al Nette este că, la crearea obiectului, acesta dezinfectează automat toți parametrii de intrare GET, POST, COOKIE, precum și URL de caractere de control și secvențe UTF-8 invalide. Apoi puteți lucra în siguranță cu aceste date. Datele sanitizate sunt utilizate ulterior în prezentatoare ș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

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

Clasa Nette\Http\RequestFactory este utilizată pentru a crea o instanță a Nette\Http\Request, care reprezintă solicitarea HTTP curentă. (Dacă lucrați cu Nette, obiectul cerere HTTP este creat automat de către cadru).

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

Metoda fromGlobals() creează un obiect cerere bazat pe variabilele globale PHP curente ($_GET, $_POST, $_COOKIE, $_FILES și $_SERVER). La crearea obiectului, aceasta curăță automat toți parametrii de intrare GET, POST, COOKIE, precum și URL de caracterele de control și secvențele UTF-8 invalide, ceea ce asigură securitatea atunci când se lucrează ulterior cu aceste date.

RequestFactory poate fi configurat înainte de a apela fromGlobals():

utilizând metoda $factory->setBinary() se poate dezactiva curățarea automată a parametrilor de intrare de caractere de control și secvențe UTF-8 invalide.
utilizând metoda $factory->setProxy(...) se specifică adresa IP a serverului proxy, care este necesară pentru detectarea corectă a adresei IP a utilizatorului.

RequestFactory vă permite să definiți filtre care transformă automat părți ale solicitării URL. Aceste filtre elimină caracterele nedorite din URL-uri care ar fi putut fi introduse, de exemplu, prin implementarea incorectă a sistemelor de comentarii pe diverse site-uri web:

// eliminarea spațiilor din cale
$requestFactory->urlFilters['path']['%20'] = '';

// eliminarea unui punct, virgulă sau paranteză dreaptă de la sfârșitul URI
$requestFactory->urlFilters['url']['[.,)]$'] = '';

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

Prima cheie 'path' sau 'url' determină partea din URL la care va fi aplicat filtrul. A doua cheie este o expresie regulată care urmează să fie căutată, iar valoarea este înlocuirea care urmează să fie utilizată în locul textului găsit.

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`