Zahteva HTTP

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

Zahtevo HTTP predstavlja objekt Nette\Http\Request. Če delate z Nette, ta objekt samodejno ustvari ogrodje, lahko pa vam ga posreduje z uporabo vbrizgavanja odvisnosti. V programu Presenters morate samo poklicati metodo $this->getHttpRequest(). Če delate zunaj ogrodja Nette, lahko objekt ustvarite z uporabo RequestFactory.

Glavna prednost programa Nette je, da pri ustvarjanju objekta samodejno očisti vse vhodne parametre GET, POST, COOKIE in URL od kontrolnih znakov in neveljavnih zaporedij UTF-8. S temi podatki lahko nato varno delate. Sanitizirani podatki se nato uporabljajo v predstavitvah 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

Razred Nette\Http\RequestFactory se uporablja za ustvarjanje primerka Nette\Http\Request, ki predstavlja trenutno zahtevo HTTP. (Če delate z Nette, je objekt zahteve HTTP samodejno ustvarjen v okviru.)

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

Metoda fromGlobals() ustvari predmet 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 naslov URL kontrolnih znakov in neveljavnih zaporedij UTF-8, kar zagotavlja varnost pri kasnejšem delu s temi podatki.

RequestFactory lahko konfigurirate pred klicem fromGlobals():

z metodo $factory->setBinary() lahko onemogočite samodejno čiščenje vhodnih parametrov od kontrolnih znakov in neveljavnih zaporedij UTF-8.
z uporabo metode $factory->setProxy(...) določite naslov IP posredniškega strežnika, ki je potreben za pravilno zaznavanje uporabnikovega naslova IP.

RequestFactory omogoča opredelitev filtrov, ki samodejno preoblikujejo dele zahteve URL. Ti filtri iz naslovov URL odstranijo neželene znake, ki so bili morda vstavljeni na primer zaradi nepravilne implementacije sistemov komentarjev na različnih spletnih mestih:

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

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

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

Prvi ključ 'path' ali 'url' določa, za kateri del URL-ja bo uporabljen filter. Drugi ključ je regularni izraz, ki se išče, vrednost pa je zamenjava, ki se uporabi namesto najdenega besedila.

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.

Zahteva HTTP

Nette\Http\Praševanje

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

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`