HTTP kérés

A Nette a HTTP-kérést érthető API-val rendelkező objektumokba kapszulázza, miközben szanálási szűrőt 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 függőségi injektálással átadhatja. A prezenterekben csak a $this->getHttpRequest() metódust kell meghívni. Ha a Nette keretrendszeren kívül dolgozik, akkor az objektumot a RequestFactory segítségével hozhatja létre.

A Nette egyik fő előnye, hogy az objektum létrehozásakor automatikusan szanálja az összes bemeneti paramétert GET, POST, COOKIE, valamint az URL-t a vezérlő karakterektől és az érvénytelen UTF-8 szekvenciáktól. Ezután biztonságosan dolgozhat ezekkel az adatokkal. A fertőtlenített adatok a későbbiekben a prezenterekben és űrlapokban kerülnek felhasználásra.

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

Nette\Http\Request

Ez az objektum megváltoztathatatlan. Nincsenek setterei, csak egy úgynevezett wither withUrl(), amely nem változtatja meg az objektumot, hanem egy új példányt ad vissza a módosított értékkel.

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

Egy klónt ad vissza egy másik URL-címmel.

getUrl(): Nette\Http\UrlScript

Visszaadja a kérés URL-címét UrlScript objektumként.

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

Figyelmeztetés: A böngészők nem küldenek töredéket a kiszolgálónak, ezért a $url->getFragment() egy üres karakterláncot fog visszaadni.

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

Visszaadja a GET-kérelem paramétereit:

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

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

POST kérés paramétereinek visszaadása:

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

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

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

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

Adja meg a kulcsok tömbjét a részfa struktúrájának eléréséhez.

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

Mivel a kívülről érkező adatokat nem bízhatja meg, és ezért nem támaszkodik a struktúra formájára, ez a módszer biztonságosabb, mint a $request->getFiles()['my-form']['details']['avatar'], amely hibásan működhet.

getFiles(): array

Visszaadja a feltöltési fájlok fáját egy normalizált struktúrában, amelynek minden egyes levele a Nette\Http\FileUpload egy példánya:

$files = $httpRequest->getFiles();

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

Visszaad egy cookie-t vagy null, ha nem létezik.

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

getCookies(): array

Visszaadja az összes sütit:

$cookies = $httpRequest->getCookies();

getMethod(): string

Visszaadja a HTTP-módszert, amellyel a kérés történt.

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

isMethod(string $method): bool

Ellenőrzi a HTTP-módszert, amellyel a kérés érkezett. A paraméter nem érzékeny a nagy- és kisbetűkre.

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

getHeader(string $header): ?string

Visszaad egy HTTP-fejlécet vagy a null címet, ha az nem létezik. A paraméter nem érzékeny a nagy- és kisbetűkre:

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

getHeaders(): array

Az összes HTTP-fejlécet asszociatív tömbként adja vissza:

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

isSecured(): bool

A kapcsolat titkosított (HTTPS)? Lehet, hogy a megfelelő működéshez proxy-t kell beállítania.

isSameSite(): bool

A kérés ugyanarról az (al)tartományról érkezik, és egy linkre kattintva indult? A Nette a _nss cookie-t (korábban nette-samesite) használja ennek felismerésére.

isAjax(): bool

Ez egy AJAX-kérés?

getRemoteAddress(): ?string

Visszaadja a felhasználó IP-címét. A megfelelő működéshez szükség lehet egy 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 egy proxy beállítás ára.

getBasicCredentials(): ?string

Visszaadja a Basic HTTP hitelesítési hitelesítő adatokat.

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

getRawBody(): ?string

Visszaadja a HTTP-kérelem testét:

$body = $httpRequest->getRawBody();

detectLanguage(array $langs): ?string

Nyelv észlelése. A $lang paramétereként átadjuk az alkalmazás által támogatott nyelvek tömbjét, és a böngésző által preferált nyelvet adja vissza. Ez nem varázslat, a módszer csak a Accept-Language fejlécet használja. Ha nem talál egyezést, akkor a null értéket adja vissza.

// A böngésző által küldött fejléc: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

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

RequestFactory

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

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

A fromGlobals() módszer létrehoz egy kérési 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 a GET, POST, COOKIE, valamint az URL összes bemeneti paraméterét a vezérlő karakterektől és az érvénytelen UTF-8 szekvenciáktól, ami biztosítja a biztonságot az adatokkal való későbbi munka során.

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

• a $factory->setBinary() metódus segítségével kikapcsolható a bemeneti paraméterek automatikus tisztítása a vezérlő karakterektől és az érvénytelen UTF-8 szekvenciáktól.
• a $factory->setProxy(...) metódus segítségével megadhatja a proxy-kiszolgáló IP-címét, amely a felhasználó IP-címének helyes felismeréséhez szükséges.

A RequestFactory lehetővé teszi olyan szűrők definiálását, amelyek automatikusan átalakítják az URL-kérés egyes részeit. Ezek a szűrők eltávolítják a nem kívánt karaktereket az URL-ekből, amelyek például a különböző webhelyek kommentrendszerének helytelen megvalósítása miatt kerülhettek be:

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

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

// az útvonal megtisztítása a kettős kötőjelektől (alapértelmezett szűrő)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

Az első kulcs 'path' vagy 'url' határozza meg, hogy a szűrő az URL melyik részére kerüljön alkalmazásra. A második kulcs a keresendő reguláris kifejezés, az érték pedig a talált szöveg helyett használandó helyettesítő kifejezés.

Feltöltött fájlok

A Nette\Http\Request::getFiles() módszer egy normalizált struktúrájú, feltöltött fájlokat tartalmazó fát ad vissza, amelynek minden egyes levele a Nette\Http\FileUpload példánya. Ezek az objektumok tartalmazzák a feltöltött fájlokat, amelyeket a <input type=file> form elem által megadott adatokat.

A struktúra tükrözi a HTML elemeinek elnevezését. A legegyszerűbb példában ez lehet egy egyetlen elnevezett űrlapelem, amelyet a következőképpen küldtek be:

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

Ebben az esetben a $request->getFiles() tömböt ad vissza:

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

A FileUpload objektum akkor is létrejön, ha a felhasználó nem töltött fel semmilyen fájlt, vagy a feltöltés sikertelen volt. A hasFile() módszer true-t ad vissza, ha egy fájl elküldésre került:

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

Tömbös jelölést használó bemenet esetén a név:

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

A visszaadott fa végül így néz ki:

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

A fájlok tömbjeit is létrehozhatja:

<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. indexének elérésének legjobb módja a következő:

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

Mivel kívülről nem bízhatunk az adatokban, és ezért nem támaszkodunk a struktúra formájára, ez a módszer biztonságosabb, mint a $request->getFiles()['my-form']['details']['avatars'][1], amely meghibásodhat.

A FileUpload módszerek áttekintése

hasFile(): bool

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

isOk(): bool

Visszaadja a true értéket, ha a fájl feltöltése sikeres volt.

getError(): int

Visszaadja a feltöltött fájlhoz tartozó hibakódot. Ez az UPLOAD_ERR_XXX konstansok egyike. Ha a fájl feltöltése sikeres volt, akkor a UPLOAD_ERR_OK értéket adja vissza.

move(string $dest)

Egy feltöltött fájl áthelyezése egy új helyre. Ha a célfájl már létezik, a rendszer felülírja azt.

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

getContents(): ?string

Visszaadja a feltöltött fájl tartalmát. Ha a feltöltés nem volt sikeres, akkor a null értéket adja vissza.

getContentType(): ?string

A feltöltött fájl MIME-tartalomtípusát az aláírása alapján állapítja meg. Ha a feltöltés nem volt sikeres, vagy a felismerés sikertelen, akkor a null címet adja vissza.

PHP kiterjesztést igényel fileinfo.

getUntrustedName(): string

Visszaadja a böngésző által megadott eredeti fájlnevet.

Ne bízzon az e módszer által visszaadott értékben. Egy ügyfél rosszindulatú fájlnevet küldhet azzal a szándékkal, hogy megrongálja vagy feltörje az alkalmazást.

getSanitizedName(): string

Visszaadja a szanált fájlnevet. Csak ASCII karaktereket tartalmaz. [a-zA-Z0-9.-]. Ha a név nem tartalmaz ilyen karaktereket, akkor az ‚unknown‘ értéket adja vissza. Ha a fájl JPEG, PNG, GIF vagy WebP kép, akkor a megfelelő fájlkiterjesztést adja vissza.

PHP kiterjesztés szükséges fileinfo.

getSuggestedExtension(): ?string

Visszaadja az észlelt MIME-típusnak megfelelő fájlkiterjesztést (pont nélkül).

PHP-bővítményt igényel fileinfo.

getUntrustedFullPath(): string

Visszaadja a böngésző által a könyvtár feltöltése során megadott eredeti teljes elérési utat. A teljes elérési útvonal csak a PHP 8.1 és újabb verziókban érhető el. A korábbi verziókban ez a módszer a nem megbízható fájlnevet adja vissza.

Ne bízzon az e metódus által visszaadott értékben. Egy ügyfél rosszindulatú fájlnevet küldhet azzal a szándékkal, hogy megrongálja vagy feltörje az alkalmazást.

getSize(): int

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

getTemporaryFile(): string

Visszaadja a feltöltött fájl ideiglenes helyének elérési útvonalát. Ha a feltöltés nem volt sikeres, akkor a '' értéket adja vissza.

isImage(): bool

Visszaadja a true értéket, ha a feltöltött fájl JPEG, PNG, GIF vagy WebP kép. A felismerés az aláírás alapján történik. A teljes fájl sértetlenségét nem ellenőrzi. Azt, hogy egy kép nem sérült-e, például a betöltési próbálkozással állapíthatja meg.

PHP bővítményt igényel: fileinfo.

getImageSize(): ?array

Visszaad egy pár [width, height] a feltöltött kép méreteivel. Ha a feltöltés nem volt sikeres, vagy nem érvényes kép, akkor a null visszatér.

toImage(): Nette\Utils\Image

Képet tölt be Image objektumként. Ha a feltöltés nem volt sikeres vagy nem érvényes kép, akkor a Nette\Utils\ImageException kivételt dob.