Cerere HTTP

Nette încapsulează cererea HTTP în obiecte cu o API inteligibilă și, în același timp, oferă un filtru de igienizare.

Cererea HTTP este reprezentată de obiectul Nette\Http\Request. Dacă lucrați cu Nette, acest obiect este creat automat de framework și îl puteți primi prin injecție de dependențe. În presentere, este suficient să apelați metoda $this->getHttpRequest(). Dacă lucrați în afara Nette Framework, puteți crea obiectul folosind RequestFactory.

Un mare avantaj al Nette este că, la crearea obiectului, curăță automat toți parametrii de intrare GET, POST, COOKIE și, de asemenea, URL-ul de caractere de control și secvențe UTF-8 invalide. Cu aceste date puteți lucra în siguranță în continuare. Datele curățate sunt apoi utilizate în presentere și formulare.

→ Instalare și cerințe

Nette\Http\Request

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

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

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

getUrl(): Nette\Http\UrlScript

Returnează URL-ul cererii ca obiect UrlScript.

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

Atenție: browserele nu trimit fragmentul către server, așa că $url->getFragment() va returna un șir gol.

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

Returnează parametrii GET ai cererii.

$all = $httpRequest->getQuery(); // returnează un array cu toți parametrii din URL
$id = $httpRequest->getQuery('id'); // returnează parametrul GET 'id' (sau null)

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

Returnează parametrii POST ai cererii.

$all = $httpRequest->getPost(); // returnează un array cu toți parametrii din 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(); // nume fără caractere periculoase
}

Pentru a accesa structura imbricată, specificați un array de chei.

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

Deoarece nu se poate avea încredere în datele din exterior și, prin urmare, nici în structura fișierelor, această metodă este mai sigură decât, de exemplu, $request->getFiles()['my-form']['details']['avatar'], care poate eșua.

getFiles(): array

Returnează arborele tuturor încărcărilor într-o structură normalizată, ale cărei frunze sunt obiecte Nette\Http\FileUpload:

$files = $httpRequest->getFiles();

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

Returnează cookie-ul sau null dacă 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.

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

isMethod (string $method): bool

Testează metoda HTTP cu care a fost făcută cererea. Parametrul este case-insensitive.

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

getHeader (string $header): ?string

Returnează antetul HTTP sau null dacă nu există. Parametrul este case-insensitive.

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

getHeaders(): array

Returnează toate antetele HTTP ca un array asociativ.

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

isSecured(): bool

Este conexiunea criptată (HTTPS)? Pentru o funcționare corectă, poate fi necesar să configurați proxy-ul.

isSameSite(): bool

Cererea provine de pe același (sub)domeniu și este inițiată printr-un clic pe un link? Nette utilizează cookie-ul _nss (anterior nette-samesite) pentru detectare.

isAjax(): bool

Este o cerere AJAX?

getRemoteAddress(): ?string

Returnează adresa IP a utilizatorului. Pentru o funcționare corectă, poate fi necesar să configurați proxy-ul.

getRemoteHost(): ?string

Returnează rezoluția DNS a adresei IP a utilizatorului. Pentru o funcționare corectă, poate fi necesar să configurați proxy-ul.

getBasicCredentials(): ?array

Returnează datele de autentificare pentru Basic HTTP authentication.

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

getRawBody(): ?string

Returnează corpul cererii HTTP.

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

Detectează limba. Ca parametru $lang, transmitem un array cu limbile suportate de aplicație, iar aceasta va returna limba preferată de browserul vizitatorului. Nu este magie, ci doar utilizează antetul Accept-Language. Dacă nu există nicio potrivire, returnează null.

// browserul trimite, de ex., Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // limbi suportate de aplicație
echo $httpRequest->detectLanguage($langs); // en

RequestFactory

Clasa Nette\Http\RequestFactory servește la crearea unei instanțe Nette\Http\Request, care reprezintă cererea HTTP curentă. (Dacă lucrați cu Nette, obiectul cererii HTTP este creat automat de framework.)

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

Metoda fromGlobals() creează obiectul cererii pe baza variabilelor globale PHP curente ($_GET, $_POST, $_COOKIE, $_FILES și $_SERVER). La crearea obiectului, curăță automat toți parametrii de intrare GET, POST, COOKIE și, de asemenea, URL-ul de caractere de control și secvențe UTF-8 invalide, ceea ce asigură siguranța în lucrul ulterior cu aceste date.

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

prin metoda $factory->setBinary() dezactivați curățarea automată a parametrilor de intrare de caractere de control și secvențe UTF-8 invalide.
prin metoda $factory->setProxy(...) specificați adresa IP a serverului proxy, ceea ce este necesar pentru detectarea corectă a adresei IP a utilizatorului.

RequestFactory permite definirea filtrelor care transformă automat părți ale URL-ului cererii. Aceste filtre elimină caracterele nedorite din URL, care pot fi introduse acolo, de exemplu, printr-o implementare incorectă a sistemelor de comentarii pe diverse site-uri web:

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

// eliminarea punctului, virgulei sau parantezei drepte de la sfârșitul URI-ului
$requestFactory->urlFilters['url']['[.,)]$'] = '';

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

Prima cheie 'path' sau 'url' specifică la ce parte a URL-ului se aplică filtrul. A doua cheie este expresia regulată care trebuie căutată, iar valoarea este înlocuirea care se utilizează în locul textului găsit.

Fișiere încărcate

Metoda Nette\Http\Request::getFiles() returnează un array cu toate încărcările într-o structură normalizată, ale cărei frunze sunt obiecte Nette\Http\FileUpload. Acestea încapsulează datele trimise de elementul de formular <input type=file>.

Structura reflectă denumirea elementelor în HTML. În cel mai simplu caz, poate fi un singur element de formular numit, trimis ca:

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

În acest caz, $request->getFiles() returnează un array:

[
	'avatar' => /* Instanță FileUpload */
]

Obiectul FileUpload este creat chiar și în cazul în care utilizatorul nu a trimis niciun fișier sau trimiterea a eșuat. Dacă fișierul a fost trimis, returnează metoda hasFile():

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

În cazul numelui elementului care utilizează notația pentru array-uri:

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

arborele returnat arată astfel:

[
	'my-form' => [
		'details' => [
			'avatar' => /* Instanță FileUpload */
		],
	],
]

Se poate crea și un array de fișiere:

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

În acest caz, structura arată astfel:

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

Accesarea indexului 1 al array-ului imbricat se face cel mai bine astfel:

$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 la încărcarea fișierului. Este una dintre constantele UPLOAD_ERR_XXX. Dacă încărcarea a avut succes, returnează UPLOAD_ERR_OK.

move (string $dest)

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

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

getContents(): ?string

Returnează conținutul fișierului încărcat. Dacă încărcarea nu a avut succes, returnează null.

getContentType(): ?string

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

Necesită extensia PHP fileinfo.

getUntrustedName(): string

Returnează numele original al fișierului, așa cum a fost trimis de browser.

Nu aveți încredere în valoarea returnată de această metodă. Clientul ar fi putut trimite un nume de fișier dăunător cu intenția de a deteriora sau de a pirata aplicația dvs.

getSanitizedName(): string

Returnează numele de fișier igienizat. Conține doar caractere ASCII [a-zA-Z0-9.-]. Dacă numele nu conține astfel de caractere, returnează 'unknown'. Dacă fișierul este o imagine în format JPEG, PNG, GIF, WebP sau AVIF, returnează și extensia corectă.

Necesită extensia PHP fileinfo.

getSuggestedExtension(): ?string

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

Necesită extensia PHP fileinfo.

getUntrustedFullPath(): string

Returnează calea originală a fișierului, așa cum a fost trimisă de browser la încărcarea unui folder. Calea completă este disponibilă numai în PHP 8.1 și versiunile ulterioare. În versiunile anterioare, această metodă returnează numele original al fișierului.

Nu aveți încredere în valoarea returnată de această metodă. Clientul ar fi putut trimite un nume de fișier dăunător cu intenția de a deteriora sau de a pirata aplicația dvs.

getSize(): int

Returnează dimensiunea fișierului încărcat. Dacă încărcarea nu a avut succes, returnează 0.

getTemporaryFile(): string

Returnează calea către locația temporară a fișierului încărcat. Dacă încărcarea nu a avut succes, returnează ''.

isImage(): bool

Returnează true dacă fișierul încărcat este o imagine în format JPEG, PNG, GIF, WebP sau AVIF. Detectarea se bazează pe semnătura sa și nu verifică integritatea întregului fișier. Dacă imaginea este deteriorată poate fi determinat, de exemplu, încercând să o încărcați.

Necesită extensia PHP fileinfo.

getImageSize(): ?array

Returnează o pereche [lățime, înălțime] cu dimensiunile imaginii încărcate. Dacă încărcarea nu a avut succes sau nu este o imagine validă, returnează null.

toImage(): Nette\Utils\Image

Încarcă imaginea ca obiect Image. Dacă încărcarea nu a avut succes sau nu este o imagine validă, 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(): ?array

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`