Żądanie HTTP

Nette enkapsuluje żądanie HTTP w obiekty o zrozumiałym API, zapewniając jednocześnie filtr sanityzujący.

Żądanie HTTP jest reprezentowane przez obiekt Nette\Http\Request. Jeśli pracujesz z Nette, obiekt ten jest automatycznie tworzony przez framework i możesz go przekazać za pomocą wstrzykiwania zależności. W prezenterach wystarczy wywołać metodę $this->getHttpRequest(). Jeśli pracujesz poza Nette Framework, możesz utworzyć obiekt za pomocą RequestFactory.

Główną zaletą Nette jest to, że podczas tworzenia obiektu automatycznie oczyszcza wszystkie parametry wejściowe GET, POST, COOKIE, a także adres URL ze znaków sterujących i nieprawidłowych sekwencji UTF-8. Następnie można bezpiecznie pracować z tymi danymi. Oczyszczone dane są następnie wykorzystywane w prezenterach i formularzach.

→ Instalacja i wymagania

Nette\NRequest

Ten obiekt jest niezmienny. Nie posiada żadnych seterów, ma tylko jeden tzw. wither withUrl(), który nie modyfikuje obiektu, ale zwraca nową instancję ze zmienioną wartością.

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

Zwraca klon z innym adresem URL.

getUrl(): Nette\Http\UrlScript

Zwraca adres URL żądania jako obiekt UrlScript.

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

Ostrzeżenie: Przeglądarki nie wysyłają fragmentu do serwera, więc $url->getFragment() zwróci pusty ciąg znaków.

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

Zwraca parametry żądania GET.

$all = $httpRequest->getQuery(); // zwraca tablicę wszystkich parametrów z adresu URL
$id = $httpRequest->getQuery('id'); // zwraca parametr GET 'id' (lub null)

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

Zwraca parametry żądania POST.

$all = $httpRequest->getPost(); // zwraca tablicę wszystkich parametrów z POSTa
$id = $httpRequest->getPost('id'); // zwraca parametr POST 'id' (lub null)

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

Zwraca przesłanie jako obiekt Nette\Http\FileUpload:

$file = $httpRequest->getFile('avatar');
if ($file->hasFile()) { // czy jakiś plik został przesłany?
	$file->getUntrustedName(); // nazwa pliku przesłanego przez użytkownika
	$file->getSanitizedName(); // nazwa bez niebezpiecznych znaków
}

Określenie pola kluczowego dla dostępu do struktury zagnieżdżonej.

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

Ponieważ nie można ufać zewnętrznym danym, a zatem nie można polegać na formie struktury plików, jest to bezpieczniejsza metoda niż np. $request->getFiles()['my-form']['details']['avatar']co może się nie udać.

getFiles(): array

Zwraca drzewo wszystkich uploadów w znormalizowanej strukturze, której liście są obiektami Nette\Http\FileUpload:

$files = $httpRequest->getFiles();

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

Zwraca cookie lub null, jeśli nie istnieje.

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

getCookies(): array

Zwraca wszystkie ciasteczka.

$cookies = $httpRequest->getCookies();

getMethod(): string

Zwraca metodę HTTP, za pomocą której zostało wykonane żądanie.

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

isMethod(string $method): bool

Testuje metodę HTTP, za pomocą której zostało wykonane żądanie. Wielkość liter w parametrze nie ma znaczenia.

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

getHeader(string $header): ?string

Zwraca nagłówek HTTP lub null, jeśli nie istnieje. Wielkość liter w parametrze nie ma znaczenia.

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

getHeaders(): array

Zwraca wszystkie nagłówki HTTP jako tablicę asocjacyjną.

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

isSecured(): bool

Czy połączenie jest szyfrowane (HTTPS)? Może być konieczne skonfigurowanie proxy dla prawidłowej funkcjonalności.

isSameSite(): bool

Czy żądanie pochodzi z tej samej (pod)domeny i jest inicjowane przez kliknięcie na link? Nette używa pliku cookie _nss (dawniej nette-samesite), aby to wykryć.

isAjax(): bool

Czy to jest żądanie AJAX?

getRemoteAddress(): ?string

Zwraca adres IP użytkownika. Może być konieczne skonfigurowanie proxy dla prawidłowej funkcjonalności.

getRemoteHost(): ?string

Zwraca rozdzielczość DNS adresu IP użytkownika. Może być konieczne skonfigurowanie proxy dla prawidłowej funkcjonalności.

getBasicCredentials(): ?string

Zwraca dane uwierzytelniające dla uwierzytelniania Basic HTTP.

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

getRawBody(): ?string

Zwraca treść żądania HTTP.

$body = $httpRequest->getRawBody();

detectLanguage(array $langs): ?string

Wykrywa język. Przekaż tablicę języków obsługiwanych przez aplikację jako parametr $lang, a zwróci ona ten, który przeglądarka odwiedzającego wolałaby zobaczyć. Nie ma w tym żadnej magii, po prostu używa nagłówka Accept-Language. Jeśli nie ma dopasowania, zwraca null.

// przeglądarka wysyła np. Accept-Language: en-us;q=0.8,en;q=0.5,en;q=0.3

$langs = ['hu', 'pl', 'en']; // języki obsługiwane przez aplikację
echo $httpRequest->detectLanguage($langs); // pl

RequestFactory

Klasa Nette\Http\RequestFactory jest używana do tworzenia instancji Nette\Http\Request, która reprezentuje bieżące żądanie HTTP. (Jeśli pracujesz z Nette, obiekt żądania HTTP jest automatycznie tworzony przez framework).

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

Metoda fromGlobals() tworzy obiekt żądania na podstawie bieżących zmiennych globalnych PHP ($_GET, $_POST, $_COOKIE, $_FILES i $_SERVER). Podczas tworzenia obiektu automatycznie czyści wszystkie parametry wejściowe GET, POST, COOKIE, a także adres URL ze znaków sterujących i nieprawidłowych sekwencji UTF-8, co zapewnia bezpieczeństwo podczas późniejszej pracy z tymi danymi.

RequestFactory można skonfigurować przed wywołaniem fromGlobals():

• za pomocą metody $factory->setBinary() można wyłączyć automatyczne oczyszczanie parametrów wejściowych ze znaków sterujących i nieprawidłowych sekwencji UTF-8.
• za pomocą metody $factory->setProxy(...) można określić adres IP serwera proxy, który jest niezbędny do prawidłowego wykrycia adresu IP użytkownika.

RequestFactory umożliwia definiowanie filtrów, które automatycznie przekształcają części żądania URL. Filtry te usuwają niechciane znaki z adresów URL, które mogły zostać wstawione na przykład przez nieprawidłową implementację systemów komentarzy na różnych stronach internetowych:

// usunięcie spacji ze ścieżki
$requestFactory->urlFilters['path']['%20'] = '';

// usunięcie kropki, przecinka lub prawego nawiasu z końca identyfikatora URI
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// czyszczenie ścieżki z podwójnych ukośników (filtr domyślny)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

Pierwszy klucz 'path' lub 'url' określa, do której części adresu URL zostanie zastosowany filtr. Drugi klucz to wyrażenie regularne do wyszukania, a wartość to zamiennik, który zostanie użyty zamiast znalezionego tekstu.

Przesłane pliki

Metoda Nette\Http\Request::getFiles() zwraca tablicę wszystkich uploadów w znormalizowanej strukturze, której listki są obiektami Nette\Http\FileUpload. Zawierają one dane przesłane przez element formularza <input type=file>.

Struktura odzwierciedla nazewnictwo elementów w HTML. W najprostszym przypadku może to być pojedynczy nazwany element formularza złożony jako:

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

W tym przypadku $request->getFiles() zwraca tablicę:

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

Obiekt FileUpload jest tworzony nawet jeśli użytkownik nie przesłał żadnego pliku lub przesłanie nie powiodło się. Jeśli plik został załadowany, to zwraca się metoda hasFile():

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

W przypadku nazwy elementu z wykorzystaniem notacji tablicowej:

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

zwrócone drzewo wygląda tak:

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

Można również utworzyć tablicę plików:

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

W tym przypadku struktura wygląda tak:

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

Najlepszym sposobem podejścia do indeksu 1 zagnieżdżonej tablicy jest następujący sposób:

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

Ponieważ nie można ufać zewnętrznym danym, a zatem nie można polegać na formie struktury plików, jest to bezpieczniejszy sposób niż np. $request->getFiles()['my-form']['details']['avatars'][1]co może się nie udać.

Przegląd metod FileUpload

hasFile(): bool

Zwraca true, jeśli użytkownik przesłał plik.

isOk(): bool

Zwraca true, jeśli plik został przesłany pomyślnie.

getError(): int

Zwraca kod błędu podczas przesyłania pliku. Jest to jedna ze stałych UPLOAD_ERR_XXX. Jeśli przesyłanie zakończyło się sukcesem, zwraca UPLOAD_ERR_OK.

move(string $dest)

Przenosi przesłany plik do nowej lokalizacji. Jeśli plik docelowy już istnieje, zostanie on nadpisany.

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

getContents(): ?string

Zwraca zawartość przesłanego pliku. Jeśli przesłanie nie powiodło się, zwraca null.

getContentType(): ?string

Wykrywa typ zawartości MIME przesłanego pliku na podstawie jego sygnatury. Jeśli przesłanie nie powiodło się lub wykrycie nie powiodło się, zwraca null.

Wymaga rozszerzenia PHP fileinfo.

getUntrustedName(): string

Zwraca oryginalną nazwę pliku przesłaną przez przeglądarkę.

Nie należy ufać wartości zwracanej przez tę metodę. Klient mógł wysłać złośliwą nazwę pliku z zamiarem uszkodzenia lub zhakowania Twojej aplikacji.

getSanitizedName(): string

Zwraca oczyszczoną nazwę pliku. Zawiera tylko znaki ASCII [a-zA-Z0-9.-]. Jeśli nazwa nie zawiera takich znaków, zwraca 'unknown'. Jeśli plik jest obrazem JPEG, PNG, GIF lub WebP, zwraca również prawidłowe rozszerzenie.

Wymaga rozszerzenia PHP fileinfo.

getSuggestedExtension(): ?string

Zwraca odpowiednie rozszerzenie pliku (bez kropki) odpowiadające wykrytemu typowi MIME.

Wymaga rozszerzenia PHP fileinfo.

getUntrustedFullPath(): string

Zwraca oryginalną ścieżkę pliku, jak wysłane przez przeglądarkę, gdy folder został załadowany. Pełna ścieżka jest dostępna tylko w PHP 8.1 i wyższych. W poprzednich wersjach metoda ta zwracała oryginalną nazwę pliku.

Nie należy ufać wartości zwracanej przez tę metodę. Klient mógł wysłać złośliwą nazwę pliku z zamiarem uszkodzenia lub zhakowania Twojej aplikacji.

getSize(): int

Zwraca rozmiar przesłanego pliku. Zwraca 0 jeśli załadowanie nie powiodło się.

getTemporaryFile(): string

Zwraca ścieżkę do tymczasowej lokalizacji przesłanego pliku. Jeśli przesłanie nie powiodło się, zwraca ''.

isImage(): bool

Zwraca true, jeśli przesłany plik jest obrazem JPEG, PNG, GIF lub WebP. Wykrywanie oparte jest na jego sygnaturze i nie sprawdza integralności całego pliku. Możliwe jest określenie, czy obraz jest uszkodzony, na przykład próbując go załadować.

Wymaga rozszerzenia PHP fileinfo.

getImageSize(): ?array

Zwraca parę [šířka, výška] z wymiarami przesłanego obrazu. Jeśli przesłanie nie powiodło się lub nie jest to prawidłowy obraz, zwraca null.

toImage(): Nette\Utils\Image

Wczytuje obraz jako obiekt Image. Jeśli przesłanie nie powiodło się lub nie jest prawidłowym obrazem, rzuca wyjątek Nette\Utils\ImageException.