Zahteva HTTP

Nette inkapsulira HTTP zahtevo v objekte z razumljivim API-jem in hkrati zagotavlja sanacijski filter.

HTTP zahtevo predstavlja objekt Nette\Http\Request. Če delate z Nette, ta objekt samodejno ustvari ogrodje in si ga lahko pustite predati s pomočjo dependency injection. V presenterjih je dovolj le poklicati metodo $this->getHttpRequest(). Če delate izven Nette Frameworka, si lahko ustvarite objekt s pomočjo RequestFactory.

Velika prednost Nette je, da pri ustvarjanju objekta samodejno očisti vse vhodne parametre GET, POST, COOKIE in tudi URL kontrolnih znakov in neveljavnih UTF-8 sekvenc. S temi podatki lahko nato varno nadalje delate. Očiščeni podatki se nato uporabljajo v presenterjih in obrazcih.

→ Namestitev in zahteve

Nette\Http\Request

Ta objekt je nespremenljiv (immutable). Nima nobenih setterjev, ima le en t.i. wither withUrl(), ki objekta ne spreminja, ampak vrača novo instanco s spremenjeno vrednostjo.

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

Vrača klon z drugim URL-jem.

getUrl(): Nette\Http\UrlScript

Vrača URL zahteve kot objekt UrlScript.

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

Opozorilo: brskalniki ne pošiljajo fragmenta na strežnik, zato bo $url->getFragment() vračal prazen niz.

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

Vrača parametre GET zahteve.

$all = $httpRequest->getQuery(); // vrača polje vseh parametrov iz URL-ja
$id = $httpRequest->getQuery('id'); // vrača GET parameter 'id' (ali null)

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

Vrača parametre POST zahteve.

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

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

Vrača naloženo datoteko kot objekt Nette\Http\FileUpload:

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

Za dostop do ugnezdene strukture navedite polje ključev.

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

Ker ni mogoče zaupati podatkom od zunaj in se torej tudi ne zanašati na obliko strukture datotek, je ta način varnejši kot na primer $request->getFiles()['my-form']['details']['avatar'], ki lahko odpove.

getFiles(): array

Vrne drevo vseh naloženih datotek v normalizirani strukturi, katere listi so objekti Nette\Http\FileUpload:

$files = $httpRequest->getFiles();

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

Vrača piškotek ali null, če ne obstaja.

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

getCookies(): array

Vrača vse piškotke.

$cookies = $httpRequest->getCookies();

getMethod(): string

Vrača HTTP metodo, s katero je bila narejena zahteva.

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

isMethod (string $method): bool

Testira HTTP metodo, s katero je bila narejena zahteva. Parameter je neobčutljiv na velikost črk.

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

getHeader (string $header): ?string

Vrača HTTP glavo ali null, če ne obstaja. Parameter je neobčutljiv na velikost črk.

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

getHeaders(): array

Vrača vse HTTP glave kot asociativno polje.

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

isSecured(): bool

Je povezava šifrirana (HTTPS)? Za pravilno delovanje je morda treba nastaviti proxy.

isSameSite(): bool

Ali zahteva prihaja iz iste (pod)domene in je sprožena s klikom na povezavo? Nette za zaznavanje uporablja piškotek _nss (prej nette-samesite).

isAjax(): bool

Gre za AJAX zahtevo?

getRemoteAddress(): ?string

Vrača IP naslov uporabnika. Za pravilno delovanje je morda treba nastaviti proxy.

getRemoteHost(): ?string

Vrača DNS prevod IP naslova uporabnika. Za pravilno delovanje je morda treba nastaviti proxy.

getBasicCredentials(): ?array

Vrača podatke za preverjanje pristnosti za Basic HTTP authentication.

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

getRawBody(): ?string

Vrača telo HTTP zahteve.

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

Zazna jezik. Kot parameter $lang predamo polje z jeziki, ki jih aplikacija podpira, in ona vrne tistega, ki bi ga brskalnik obiskovalca najraje videl. To niso nobene čarovnije, le uporablja se glava Accept-Language. Če ne pride do nobenega ujemanja, vrača null.

// brskalnik pošilja npr. Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // jeziki, ki jih podpira aplikacija
echo $httpRequest->detectLanguage($langs); // en

RequestFactory

Razred Nette\Http\RequestFactory služi za ustvarjanje instance Nette\Http\Request, ki predstavlja trenutno HTTP zahtevo. (Če delate z Nette, objekt HTTP zahteve samodejno ustvari ogrodje.)

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

Metoda fromGlobals() ustvari objekt zahteve na podlagi trenutnih globalnih spremenljivk PHP ($_GET, $_POST, $_COOKIE, $_FILES in $_SERVER). Pri ustvarjanju objekta samodejno očisti vse vhodne parametre GET, POST, COOKIE in tudi URL kontrolnih znakov in neveljavnih UTF-8 sekvenc, kar zagotavlja varnost pri nadaljnjem delu s temi podatki.

RequestFactory lahko pred klicem fromGlobals() konfigurirate:

z metodo $factory->setBinary() izklopite samodejno čiščenje vhodnih parametrov kontrolnih znakov in neveljavnih UTF-8 sekvenc.
z metodo $factory->setProxy(...) navedete IP naslov proxy strežniku, kar je nujno za pravilno zaznavanje IP naslova uporabnika.

RequestFactory omogoča definiranje filtrov, ki samodejno transformirajo dele URL zahteve. Ti filtri odstranjujejo nezaželene znake iz URL-ja, ki so tja lahko vstavljeni na primer z nepravilno implementacijo sistemov za komentarje na različnih spletnih mestih:

// odstranitev presledkov iz poti
$requestFactory->urlFilters['path']['%20'] = '';

// odstranitev pike, vejice ali desnega oklepaja s konca URI
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// čiščenje poti od podvojenih poševnic (privzeti filter)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

Prvi ključ 'path' ali 'url' določa, na kateri del URL-ja se filter uporabi. Drugi ključ je regularni izraz, ki se najde, in vrednost je nadomestilo, ki se uporabi namesto najdenega besedila.

Naložene datoteke

Metoda Nette\Http\Request::getFiles() vrača polje vseh naloženih datotek v normalizirani strukturi, katere listi so objekti Nette\Http\FileUpload. Ti inkapsulirajo podatke, poslane z elementom obrazca <input type=file>.

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

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

V tem primeru $request->getFiles() vrača polje:

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

Objekt FileUpload se ustvari tudi v primeru, da uporabnik ni poslal nobene datoteke ali je pošiljanje spodletelo. Ali je bila datoteka poslana, vrača metoda hasFile():

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

V primeru imena elementa, ki uporablja notacijo za polja:

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

izgleda vrnjeno drevo takole:

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

Lahko ustvarite tudi polje datotek:

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

V takem primeru izgleda struktura takole:

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

Dostop do indeksa 1 ugnezdenega polja je najbolje izvesti tako:

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

Pregled metod `FileUpload`

hasFile(): bool

Vrača true, če je uporabnik naložil kakšno datoteko.

isOk(): bool

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

getError(): int

Vrača kodo napake pri nalaganju datoteke. Gre za eno od konstant UPLOAD_ERR_XXX. V primeru, da je nalaganje potekalo v redu, vrača UPLOAD_ERR_OK.

move (string $dest)

Premakne naloženo datoteko na novo lokacijo. Če ciljna datoteka že obstaja, bo prepisana.

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

getContents(): ?string

Vrača vsebino naložene datoteke. V primeru, da nalaganje ni bilo uspešno, vrača null.

getContentType(): ?string

Zazna MIME content type naložene datoteke na podlagi njene signature. V primeru, da nalaganje ni bilo uspešno ali zaznavanje ni uspelo, vrača null.

Zahteva PHP razširitev fileinfo.

getUntrustedName(): string

Vrača originalno ime datoteke, kot ga je poslal brskalnik.

Ne zaupajte vrednosti, ki jo vrne ta metoda. Odjemalec je lahko poslal škodljivo ime datoteke z namenom poškodovati ali vdreti v vašo aplikacijo.

getSanitizedName(): string

Vrača sanirano ime datoteke. Vsebuje samo ASCII znake [a-zA-Z0-9.-]. Če ime takih znakov ne vsebuje, vrne 'unknown'. Če je datoteka slika v formatu JPEG, PNG, GIF, WebP ali AVIF, vrne tudi pravilno končnico.

Zahteva PHP razširitev fileinfo.

getSuggestedExtension(): ?string

Vrača primerno končnico datoteke (brez pike), ki ustreza zaznanemu MIME tipu.

Zahteva PHP razširitev fileinfo.

getUntrustedFullPath(): string

Vrača originalno pot do datoteke, kot jo je poslal brskalnik pri nalaganju mape. Celotna pot je na voljo samo v PHP 8.1 in višjih. V prejšnjih različicah ta metoda vrača originalno ime datoteke.

Ne zaupajte vrednosti, ki jo vrne ta metoda. Odjemalec je lahko poslal škodljivo ime datoteke z namenom poškodovati ali vdreti v vašo aplikacijo.

getSize(): int

Vrača velikost naložene datoteke. V primeru, da nalaganje ni bilo uspešno, vrača 0.

getTemporaryFile(): string

Vrača pot do začasne lokacije naložene datoteke. V primeru, da nalaganje ni bilo uspešno, vrača ''.

isImage(): bool

Vrača true, če je naložena datoteka slika v formatu JPEG, PNG, GIF, WebP ali AVIF. Zaznavanje poteka na podlagi njene signature in se ne preverja integriteta celotne datoteke. Ali slika ni poškodovana, lahko ugotovite na primer s poskusom njenega nalaganjem.

Zahteva PHP razširitev fileinfo.

getImageSize(): ?array

Vrača par [širina, višina] z dimenzijami naložene slike. V primeru, da nalaganje ni bilo uspešno ali ne gre za veljavno sliko, vrača null.

toImage(): Nette\Utils\Image

Naloži sliko kot objekt Image. V primeru, da nalaganje ni bilo uspešno ali ne gre za veljavno sliko, vrže izjemo Nette\Utils\ImageException.

Zahteva 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

Naložene datoteke

Pregled metod 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

Pregled metod `FileUpload`