Zahteva HTTP

Nette zapakira zahtevo HTTP v predmete z razumljivim API-jem, hkrati pa zagotavlja filter za čiščenje.

Zahteva HTTP je objekt Nette\Http\Request, ki ga dobite tako, da ga posredujete z uporabo vbrizgavanja odvisnosti. V predvajalnikih preprosto pokličite $httpRequest = $this->getHttpRequest().

Pomembno je, da Nette pri ustvarjanju tega objekta očisti vse vhodne parametre GET, POST in COOKIE ter naslove URL kontrolnih znakov in neveljavnih zaporedij UTF-8. Tako lahko varno nadaljujete delo s podatki. Očiščeni podatki se nato uporabljajo v predstavitvenih programih in obrazcih.

→ Namestitev in zahteve

Nette\Http\Praševanje

Ta predmet je nespremenljiv. Nima nastavljalcev, ima le en tako imenovani wither withUrl(), ki ne spremeni objekta, temveč vrne novo instanco s spremenjeno vrednostjo.

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

Vrne klon z drugačnim naslovom URL.

getUrl(): Nette\Http\UrlScript

Vrne URL zahteve kot predmet UrlScript.

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

Opozorilo: Brskalniki strežniku ne pošiljajo fragmentov, zato bo $url->getFragment() vrnil prazen niz.

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

Vrne parametre zahteve GET:

$all = $httpRequest->getQuery();    // polje vseh parametrov URL
$id = $httpRequest->getQuery('id'); // vrne parameter GET 'id' (ali null)

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

Vrne parametre zahteve POST:

$all = $httpRequest->getPost();     // polje vseh parametrov POST
$id = $httpRequest->getPost('id');  // vrne parameter POST 'id' (ali null)

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

Vrne prenos kot predmet Nette\Http\FileUpload:

$file = $httpRequest->getFile('avatar');
if ($file->hasFile()) { // je bila naložena katera koli datoteka?
	$file->getUntrustedName(); // ime datoteke, ki jo je poslal uporabnik
	$file->getSanitizedName(); // ime brez nevarnih znakov
}

Navedite polje ključev za dostop do strukture poddrevesa.

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

Ker ne morete zaupati podatkom od zunaj in se zato ne zanašate na obliko strukture, je ta metoda varnejša kot $request->getFiles()['my-form']['details']['avatar']ki je lahko neuspešna.

getFiles(): array

Vrne drevo datotek za prenos v normalizirani strukturi, pri čemer je vsak list primerek Nette\Http\FileUpload:

$files = $httpRequest->getFiles();

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

Vrne piškotek ali null, če ne obstaja.

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

getCookies(): array

Vrne vse piškotke:

$cookies = $httpRequest->getCookies();

getMethod(): string

Vrne metodo HTTP, s katero je bila zahteva izvedena.

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

isMethod (string $method): bool

Preveri metodo HTTP, s katero je bila izvedena zahteva. Pri parametru se ne razlikujejo velike in male črke.

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

getHeader (string $header): ?string

Vrne glavo HTTP ali null, če ta ne obstaja. Pri parametru se ne razlikujejo velike in male črke:

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

getHeaders(): array

Vrne vse glave HTTP kot asociativno polje:

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

isSecured(): bool

Ali je povezava šifrirana (HTTPS)? Za pravilno delovanje boste morda morali nastaviti posrednika.

isSameSite(): bool

Ali zahteva prihaja iz iste (pod)domene in se sproži s klikom na povezavo? Nette to zazna s piškotkom _nss (prej nette-samesite).

isAjax(): bool

Ali gre za zahtevo AJAX?

getRemoteAddress(): ?string

Vrne uporabnikov naslov IP. Za pravilno delovanje boste morda morali nastaviti proxy strežnik.

getRemoteHost(): ?string

Vrne prevod DNS uporabnikovega naslova IP. Za pravilno delovanje boste morda morali nastaviti posrednika.

getBasicCredentials(): ?string

Vrne osnovne poverilnice za avtentikacijo HTTP.

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

getRawBody(): ?string

Vrne telo zahteve HTTP:

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

zazna jezik. Kot parameter $lang posredujemo polje jezikov, ki jih aplikacija podpira, in vrne tistega, ki ga ima brskalnik najraje. Ne gre za čarovnijo, metoda samo uporabi glavo Accept-Language. Če ni nobenega ujemanja, vrne null.

// Naslovnica, ki jo pošlje brskalnik: Jezik: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // jeziki, podprti v aplikaciji
echo $httpRequest->detectLanguage($langs); // en

RequestFactory

Predmet trenutne zahteve HTTP ustvari Nette\Http\RequestFactory. Če pišete aplikacijo, ki ne uporablja vsebnika DI, ustvarite zahtevo na naslednji način:

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

RequestFactory lahko konfigurirate pred klicem fromGlobals(). Z uporabo spletne strani $factory->setBinary() lahko onemogočimo vso sanitizacijo vhodnih parametrov iz neveljavnih zaporedij UTF-8. Prav tako lahko nastavimo strežnik proxy, kar je pomembno za pravilno zaznavanje uporabnikovega naslova IP z uporabo $factory->setProxy(...).

Z uporabo filtrov je mogoče naslove URL očistiti znakov, ki lahko vanje pridejo zaradi slabo izvedenih sistemov komentarjev na različnih drugih spletnih mestih:

// odstranite presledke s poti
$requestFactory->urlFilters['path']['%20'] = '';

// odstranite piko, vejico ali desni oklepaj na koncu naslova URL.
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// očisti pot podvojenih poševnic (privzeti filter)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

Naložene datoteke

Metoda Nette\Http\Request::getFiles() vrne drevo naloženih datotek v normalizirani strukturi, pri čemer je vsak list primerek objekta Nette\Http\FileUpload. Ti objekti vsebujejo podatke, ki jih je predložil <input type=file> element obrazca.

Struktura odraža poimenovanje elementov v jeziku HTML. V najpreprostejšem primeru je to lahko en poimenovan element obrazca, ki se odda kot:

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

V tem primeru $request->getFiles() vrne polje:

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

Objekt FileUpload se ustvari, tudi če uporabnik ni naložil nobene datoteke ali če nalaganje ni bilo uspešno. Metoda hasFile() vrne true, če je bila datoteka poslana:

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

V primeru vnosa, ki za ime uporablja zapis v obliki polja:

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

vrnjeno drevo je videti takole:

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

Ustvarite lahko tudi polja datotek:

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

V takem primeru je struktura videti kot:

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

Najboljši način za dostop do indeksa 1 ugnezdenega polja je naslednji:

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

Ker ne morete zaupati podatkom od zunaj in se zato ne zanašate na obliko strukture, je ta metoda varnejša od $request->getFiles()['my-form']['details']['avatars'][1]ki je lahko neuspešna.

Pregled metod FileUpload

hasFile(): bool

Vrne true, če je uporabnik naložil datoteko.

isOk(): bool

Vrne true, če je bila datoteka uspešno naložena.

getError(): int

Vrne kodo napake, povezano z naloženo datoteko. To je ena od konstant UPLOAD_ERR_XXX. Če je bila datoteka uspešno naložena, se vrne UPLOAD_ERR_OK.

move (string $dest)

Premakne naloženo datoteko na novo lokacijo. Če ciljna datoteka že obstaja, se prepiše.

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

getContents(): ?string

Vrne vsebino naložene datoteke. Če nalaganje ni bilo uspešno, vrne null.

getContentType(): ?string

Določi vrsto vsebine MIME naložene datoteke na podlagi njenega podpisa. Če nalaganje ni bilo uspešno ali pa je bilo zaznavanje neuspešno, vrne null.

Zahteva razširitev PHP fileinfo.

getUntrustedName(): string

Vrne izvirno ime datoteke, kot ga je posredoval brskalnik.

Ne zaupajte vrednosti, ki jo vrne ta metoda. Odjemalec lahko pošlje zlonamerno ime datoteke z namenom, da bi poškodoval ali vdrl v vašo aplikacijo.

getSanitizedName(): string

Vrne prečiščeno ime datoteke. Vsebuje samo znake ASCII [a-zA-Z0-9.-]. Če ime ne vsebuje takih znakov, vrne ‘unknown’. Če je datoteka slika JPEG, PNG, GIF ali WebP, vrne pravilno končnico datoteke.

Zahteva razširitev PHP fileinfo.

getSuggestedExtension(): ?string

Vrne ustrezno razširitev datoteke (brez pike), ki ustreza zaznani vrsti MIME.

Zahteva razširitev PHP fileinfo.

getUntrustedFullPath(): string

Vrne izvirno celotno pot, kot jo je posredoval brskalnik med nalaganjem imenika. Polna pot je na voljo samo v PHP 8.1 in novejših različicah. V prejšnjih različicah ta metoda vrne ime nezaupljive datoteke.

Ne zaupajte vrednosti, ki jo vrne ta metoda. Odjemalec lahko pošlje zlonamerno ime datoteke z namenom, da bi poškodoval ali vdrl v vašo aplikacijo.

getSize(): int

Vrne velikost naložene datoteke. Če nalaganje ni bilo uspešno, vrne 0.

getTemporaryFile(): string

Vrne pot do začasne lokacije naložene datoteke. Če nalaganje ni bilo uspešno, vrne ''.

isImage(): bool

Vrne true, če je naložena datoteka slika JPEG, PNG, GIF ali WebP. Odkrivanje temelji na njenem podpisu. Celovitost celotne datoteke se ne preverja. Ali slika ni poškodovana, lahko ugotovite na primer tako, da jo poskusite naložiti.

Zahteva razširitev PHP fileinfo.

getImageSize(): ?array

Vrne par [width, height] z merami naložene slike. Če nalaganje ni bilo uspešno ali slika ni veljavna, vrne null.

toImage(): Nette\Utils\Image

Naloži sliko kot objekt Image. Če nalaganje ni bilo uspešno ali slika ni veljavna, se vrže izjema Nette\Utils\ImageException.