HTTP kérés

A Nette a HTTP kérést érthető API-val rendelkező objektumokba zárja, és egyúttal szanitizáló szűrőt is biztosít.

A HTTP kérést a Nette\Http\Request objektum képviseli. Ha a Nette-tel dolgozik, ezt az objektumot a keretrendszer automatikusan létrehozza, és dependency injection segítségével átadhatja magának. A presenterekben elég csak a $this->getHttpRequest() metódust meghívni. Ha a Nette Frameworkön kívül dolgozik, létrehozhatja az objektumot a RequestFactory segítségével.

A Nette nagy előnye, hogy az objektum létrehozásakor automatikusan megtisztítja az összes GET, POST, COOKIE bemeneti paramétert, valamint az URL-t a vezérlőkarakterektől és az érvénytelen UTF-8 szekvenciáktól. Ezekkel az adatokkal ezután biztonságosan dolgozhat tovább. A megtisztított adatokat ezután a presenterekben és az űrlapokban használják.

→ Telepítés és követelmények

Nette\Http\Request

Ez az objektum immutable (megváltoztathatatlan). Nincsenek setterei, csak egy ún. wither withUrl() metódusa van, amely nem változtatja meg az objektumot, hanem egy új példányt ad vissza megváltozott értékkel.

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

Egy klónt ad vissza más URL-lel.

getUrl(): Nette\Http\UrlScript

Visszaadja a kérés URL-jét UrlScript objektumként.

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

Figyelmeztetés: a böngészők nem küldik el a fragmentet a szerverre, így a $url->getFragment() üres stringet fog visszaadni.

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

Visszaadja a GET kérés paramétereit.

$all = $httpRequest->getQuery(); // visszaadja az összes paraméter tömbjét az URL-ből
$id = $httpRequest->getQuery('id'); // visszaadja a 'id' GET paramétert (vagy null-t)

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

Visszaadja a POST kérés paramétereit.

$all = $httpRequest->getPost(); // visszaadja az összes paraméter tömbjét a POST-ból
$id = $httpRequest->getPost('id'); // visszaadja a 'id' POST paramétert (vagy null-t)

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

Visszaadja a feltöltést Nette\Http\FileUpload objektumként:

$file = $httpRequest->getFile('avatar');
if ($file?->hasFile()) { // feltöltöttek valamilyen fájlt?
	$file->getUntrustedName(); // a felhasználó által küldött fájlnév
	$file->getSanitizedName(); // név veszélyes karakterek nélkül
}

A beágyazott struktúrához való hozzáféréshez adjon meg egy kulcsokból álló tömböt.

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

Mivel nem lehet megbízni a kívülről érkező adatokban, és így a fájlok struktúrájának formájában sem, ez a módszer biztonságosabb, mint például a $request->getFiles()['my-form']['details']['avatar'], amely meghiúsulhat.

getFiles(): array

Visszaadja az összes feltöltés fáját normalizált struktúrában, amelynek levelei Nette\Http\FileUpload objektumok:

$files = $httpRequest->getFiles();

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

Visszaadja a cookie-t vagy null-t, ha nem létezik.

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

getCookies(): array

Visszaadja az összes cookie-t.

$cookies = $httpRequest->getCookies();

getMethod(): string

Visszaadja a HTTP metódust, amellyel a kérés történt.

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

isMethod (string $method): bool

Teszteli a HTTP metódust, amellyel a kérés történt. A paraméter kis- és nagybetű érzéketlen.

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

getHeader (string $header): ?string

Visszaadja a HTTP fejlécet vagy null-t, ha nem létezik. A paraméter kis- és nagybetű érzéketlen.

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

getHeaders(): array

Visszaadja az összes HTTP fejlécet asszociatív tömbként.

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

isSecured(): bool

Titkosított a kapcsolat (HTTPS)? A megfelelő működéshez szükség lehet a proxy beállítására.

isSameSite(): bool

Ugyanarról a (sub)domainről érkezik a kérés, és egy linkre kattintással indították? A Nette a _nss cookie-t (korábban nette-samesite) használja az észleléshez.

isAjax(): bool

AJAX kérésről van szó?

getRemoteAddress(): ?string

Visszaadja a felhasználó IP címét. A megfelelő működéshez szükség lehet a proxy beállítására.

getRemoteHost(): ?string

Visszaadja a felhasználó IP címének DNS fordítását. A megfelelő működéshez szükség lehet a proxy beállítására.

getBasicCredentials(): ?array

Visszaadja a Basic HTTP authentication hitelesítési adatait.

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

getRawBody(): ?string

Visszaadja a HTTP kérés törzsét.

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

Észleli a nyelvet. Paraméterként $lang átadjuk az alkalmazás által támogatott nyelvek tömbjét, és visszaadja azt, amelyet a látogató böngészője legszívesebben látna. Ez nem varázslat, csak az Accept-Language fejlécet használja. Ha nincs egyezés, null-t ad vissza.

// a böngésző pl. Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3 küld

$langs = ['hu', 'pl', 'en']; // az alkalmazás által támogatott nyelvek
echo $httpRequest->detectLanguage($langs); // en

RequestFactory

A Nette\Http\RequestFactory osztály egy Nette\Http\Request példány létrehozására szolgál, amely az aktuális HTTP kérést reprezentálja. (Ha a Nette-tel dolgozik, a HTTP kérés objektumot a keretrendszer automatikusan létrehozza.)

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

A fromGlobals() metódus létrehozza a kérés objektumot az aktuális PHP globális változók ($_GET, $_POST, $_COOKIE, $_FILES és $_SERVER) alapján. Az objektum létrehozásakor automatikusan megtisztítja az összes GET, POST, COOKIE bemeneti paramétert, valamint az URL-t a vezérlőkarakterektől és az érvénytelen UTF-8 szekvenciáktól, ami biztosítja a biztonságot ezen adatok további feldolgozása során.

A RequestFactory konfigurálható a fromGlobals() meghívása előtt:

a $factory->setBinary() metódussal kikapcsolhatja a bemeneti paraméterek automatikus tisztítását a vezérlőkarakterektől és az érvénytelen UTF-8 szekvenciáktól.
a $factory->setProxy(...) metódussal megadhatja a proxy szerver IP címét, ami szükséges a felhasználó IP címének helyes észleléséhez.

A RequestFactory lehetővé teszi szűrők definiálását, amelyek automatikusan átalakítják a kérés URL-jének részeit. Ezek a szűrők eltávolítják a nem kívánt karaktereket az URL-ből, amelyeket például a különböző webhelyeken lévő kommentrendszerek helytelen implementációja miatt helyezhettek oda:

// szóközök eltávolítása az útvonalból
$requestFactory->urlFilters['path']['%20'] = '';

// pont, vessző vagy jobb zárójel eltávolítása az URI végéről
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// az útvonal tisztítása a dupla perjelektől (alapértelmezett szűrő)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

Az első kulcs, a 'path' vagy 'url', meghatározza, hogy a szűrő az URL melyik részére vonatkozik. A második kulcs a keresendő reguláris kifejezés, az érték pedig a helyettesítés, amelyet a talált szöveg helyett használnak.

Feltöltött fájlok

A Nette\Http\Request::getFiles() metódus visszaadja az összes feltöltés tömbjét normalizált struktúrában, amelynek levelei Nette\Http\FileUpload objektumok. Ezek az <input type=file> űrlap elem által küldött adatokat zárják magukba.

A struktúra tükrözi az elemek elnevezését a HTML-ben. A legegyszerűbb esetben ez egyetlen elnevezett űrlap elem lehet, amelyet így küldtek:

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

Ebben az esetben a $request->getFiles() a következő tömböt adja vissza:

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

A FileUpload objektum akkor is létrejön, ha a felhasználó nem küldött fájlt, vagy a küldés sikertelen volt. Azt, hogy a fájl elküldésre került-e, a hasFile() metódus adja vissza:

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

Ha az elem neve tömb jelölést használ:

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

a visszaadott fa így néz ki:

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

Létrehozhatunk fájlok tömbjét is:

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

Ebben az esetben a struktúra így néz ki:

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

A beágyazott tömb 1-es indexéhez való hozzáférés a legjobb módja a következő:

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

A `FileUpload` metódusainak áttekintése

hasFile(): bool

Visszaadja a true értéket, ha a felhasználó feltöltött valamilyen fájlt.

isOk(): bool

Visszaadja a true értéket, ha a fájl sikeresen feltöltésre került.

getError(): int

Visszaadja a fájlfeltöltés hibakódját. Ez az egyik UPLOAD_ERR_XXX konstans. Ha a feltöltés rendben lezajlott, UPLOAD_ERR_OK-t ad vissza.

move (string $dest)

Áthelyezi a feltöltött fájlt egy új helyre. Ha a célfájl már létezik, felülíródik.

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

getContents(): ?string

Visszaadja a feltöltött fájl tartalmát. Ha a feltöltés sikertelen volt, null-t ad vissza.

getContentType(): ?string

Észleli a feltöltött fájl MIME content type-ját az aláírása alapján. Ha a feltöltés sikertelen volt, vagy az észlelés nem sikerült, null-t ad vissza.

Szükséges a fileinfo PHP kiterjesztés.

getUntrustedName(): string

Visszaadja a fájl eredeti nevét, ahogy a böngésző küldte.

Ne bízzon a metódus által visszaadott értékben. A kliens rosszindulatú fájlnevet küldhetett azzal a szándékkal, hogy károsítsa vagy feltörje az alkalmazását.

getSanitizedName(): string

Visszaadja a szanitizált fájlnevet. Csak ASCII karaktereket [a-zA-Z0-9.-] tartalmaz. Ha a név nem tartalmaz ilyen karaktereket, 'unknown'-t ad vissza. Ha a fájl JPEG, PNG, GIF, WebP vagy AVIF formátumú kép, akkor a helyes kiterjesztést is visszaadja.

Szükséges a fileinfo PHP kiterjesztés.

getSuggestedExtension(): ?string

Visszaadja a fájl megfelelő kiterjesztését (pont nélkül), amely megfelel az észlelt MIME típusnak.

Szükséges a fileinfo PHP kiterjesztés.

getUntrustedFullPath(): string

Visszaadja a fájl eredeti elérési útját, ahogy a böngésző küldte a mappa feltöltésekor. A teljes elérési út csak PHP 8.1 és újabb verziókban érhető el. Korábbi verziókban ez a metódus az eredeti fájlnevet adja vissza.

Ne bízzon a metódus által visszaadott értékben. A kliens rosszindulatú fájlnevet küldhetett azzal a szándékkal, hogy károsítsa vagy feltörje az alkalmazását.

getSize(): int

Visszaadja a feltöltött fájl méretét. Ha a feltöltés sikertelen volt, 0-t ad vissza.

getTemporaryFile(): string

Visszaadja a feltöltött fájl ideiglenes helyének elérési útját. Ha a feltöltés sikertelen volt, ''-t ad vissza.

isImage(): bool

Visszaadja a true értéket, ha a feltöltött fájl JPEG, PNG, GIF, WebP vagy AVIF formátumú kép. Az észlelés az aláírása alapján történik, és nem ellenőrzi az egész fájl integritását. Azt, hogy a kép nem sérült-e, például a betöltésével lehet megállapítani.

Szükséges a fileinfo PHP kiterjesztés.

getImageSize(): ?array

Visszaadja a [szélesség, magasság] párt a feltöltött kép méreteivel. Ha a feltöltés sikertelen volt, vagy nem érvényes képről van szó, null-t ad vissza.

toImage(): Nette\Utils\Image

Betölti a képet Image objektumként. Ha a feltöltés sikertelen volt, vagy nem érvényes képről van szó, Nette\Utils\ImageException kivételt dob.

HTTP kérés

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

Feltöltött fájlok

A FileUpload metódusainak áttekintése

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

A `FileUpload` metódusainak áttekintése