HTTP request
Nette zapouzdřuje HTTP požadavek do objektů se srozumitelným API a zároveň poskytuje sanitizační filtr.
HTTP požadavek představuje objekt Nette\Http\Request, ke
kterému se dostanete tak, že si jej necháte předat pomocí dependency
injection. V presenterech stačí jen zavolat $httpRequest = $this->getHttpRequest()
.
Co je důležité, tak že Nette když vytváří tento objekt, všechny vstupní parametry GET, POST, COOKIE a také URL pročistí od kontrolních znaků a neplatných UTF-8 sekvencí. Takže s daty pak můžete bezpečně dále pracovat. Očištěná data se následně používají v presenterech a formulářích.
Nette\Http\Request
Tento objekt je immutable (neměnný). Nemá žádné settery, má jen jeden tzv. wither withUrl()
, který objekt
nemění, ale vrací novou instanci se změněnou hodnotou.
withUrl(Nette\Http\UrlScript $url): Nette\Http\Request
Vrací klon s jinou URL.
getUrl(): Nette\Http\UrlScript
Vrací URL požadavku jako objekt UrlScript.
Upozornění: prohlížeče neodesílají na server fragment, takže $url->getFragment()
bude vracet prázdný
řetězec.
getQuery(?string $key=null): string|array|null
Vrací parametry GET požadavku.
getPost(?string $key=null): string|array|null
Vrací parametry POST požadavku.
getFile(string|string[] $key): Nette\Http\FileUpload|array|null
Vrací upload jako objekt Nette\Http\FileUpload:
Pro přístup do zanořené struktury uveďte pole klíčů.
Protože nelze důvěřovat datům zvenčí a tedy ani spoléhat na podobu struktury souborů, je bezpečnější tento způsob
než třeba $request->getFiles()['my-form']['details']['avatar']
, který může selhat.
getFiles(): array
Vrátí strom všech uploadů v normalizované struktuře, jejíž listy jsou objekty Nette\Http\FileUpload:
getCookie(string $key): string|array|null
Vrací cookie nebo null
, když neexistuje.
getCookies(): array
Vrací všechny cookies.
getMethod(): string
Vrací HTTP metodu, se kterou byl udělán požadavek.
isMethod(string $method): bool
Testuje HTTP metodu, se kterou byl udělán požadavek. Parametr je case-insensitive.
getHeader(string $header): ?string
Vrací HTTP hlavičku nebo null
, pokud neexistuje. Parametr je case-insensitive.
getHeaders(): array
Vrací všechny HTTP hlavičky jako asociativní pole.
isSecured(): bool
Je spojení šifrované (HTTPS)? Pro správnou funkčnost může být potřeba nastavit proxy.
isSameSite(): bool
Přichází požadavek ze stejné (sub)domény a je iniciován kliknutím na odkaz? Nette k detekci používá cookie
_nss
(dříve nette-samesite
).
isAjax(): bool
Jde o AJAXový požadavek?
getRemoteAddress(): ?string
Vrací IP adresu uživatele. Pro správnou funkčnost může být potřeba nastavit proxy.
getRemoteHost(): ?string
Vrací DNS překlad IP adresy uživatele. Pro správnou funkčnost může být potřeba nastavit proxy.
getBasicCredentials(): ?string
Vrací ověřovací údaje pro Basic HTTP authentication.
getRawBody(): ?string
Vrací tělo HTTP požadavku.
detectLanguage(array $langs): ?string
Detekuje jazyk. Jako parametr $lang
předáme pole s jazyky, které aplikace podporuje, a ona vrátí ten, který
by viděl návštěvníkův prohlížeč nejraději. Nejsou to žádná kouzla, jen se využívá hlavičky
Accept-Language
. Pokud nedojde k žádné shodě, vrací null
.
RequestFactory
Objekt aktuálního HTTP requestu vyrobí Nette\Http\RequestFactory. Pokud píšete aplikaci, která nepoužívá DI kontejner, vyrobíte request takto:
RequestFactory lze před zavoláním fromGlobals()
konfigurovat. Můžeme vypnout sanitizaci vstupních parametrů
od kontrolních znaků a neplatných UTF-8 sekvencí pomocí $factory->setBinary()
. A také nastavit proxy
server pomocí $factory->setProxy(...)
, což je důležité pro správnou detekci IP adresy uživatele.
Pomocí tzv. filtrů lze URL vyčistit od znaků, které se do něj mohou dostat např. kvůli špatně implementovaným komentářovým systémům na různých cizích webech:
Uploadované soubory
Metoda Nette\Http\Request::getFiles()
vrací pole všech uploadů v normalizované struktuře, jejíž listy jsou
objekty Nette\Http\FileUpload. Ty zapouzdřují data
odeslaná formulářovým prvkem <input type=file>
.
Struktura reflektuje pojmenování prvků v HTML. V nejjednodušším případě to může být jediný pojmenovaný element formuláře odeslaný jako:
V tomto případě $request->getFiles()
vrací pole:
Objekt FileUpload
se vytvoří i v případě, že uživatel žádný soubor neodeslal nebo odeslání selhalo.
Jestli byl soubor odeslán vrací metoda hasFile()
:
V případě názvu elementu používajícího notaci pro pole:
vypadá vrácený strom takto:
Lze vytvořit i pole souborů:
V takovém případě vypadá struktura takto:
Přistoupit k indexu 1 vnořeného pole lze nejlépe takto:
Protože nelze důvěřovat datům zvenčí a tedy ani spoléhat na podobu struktury souborů, je bezpečnější tento způsob
než třeba $request->getFiles()['my-form']['details']['avatars'][1]
, který může selhat.
Přehled metod FileUpload
hasFile(): bool
Vrací true
, pokud uživatel nějaký soubor uploadoval.
isOk(): bool
Vrací true
, pokud soubor byl nahrán úspěšně.
getError(): int
Vrací kód chyby při uploadu souboru. Jde o jednu z konstant UPLOAD_ERR_XXX. V případě, že upload proběhl
v pořádku, vrací UPLOAD_ERR_OK
.
move(string $dest)
Přesune nahraný soubor do nového umístění. Pokud cílový soubor již existuje, bude přepsán.
getContents(): ?string
Vrací obsah uploadovaného souboru. V případě, že upload nebyl úspěšný, vrací null
.
getContentType(): ?string
Detekuje MIME content type uploadovaného souboru na základě jeho signatury. V případě, že upload nebyl úspěšný nebo
detekce se nezdařila, vrací null
.
Vyžaduje PHP rozšíření fileinfo
.
getUntrustedName(): string
Vrací originální název souboru, jak jej odeslal prohlížeč.
Nevěřte hodnotě vrácené touto metodou. Klient mohl odeslat škodlivý název souboru s úmyslem poškodit nebo hacknout vaši aplikaci.
getSanitizedName(): string
Vrací sanitizovaný název souboru. Obsahuje pouze ASCII znaky [a-zA-Z0-9.-]
. Pokud název takové znaky
neobsahuje, vrátí 'unknown'
. Pokud je soubor obrázek ve formátu JPEG, PNG, GIF, WebP nebo AVIF, vrátí
i správnou příponu.
Vyžaduje PHP rozšíření fileinfo
.
getSuggestedExtension(): ?string
Vrací vhodnou příponu souboru (bez tečky) odpovídající zjištěnému MIME typu.
Vyžaduje PHP rozšíření fileinfo
.
getUntrustedFullPath(): string
Vrací originální cestu k souboru, jak ji odeslal prohlížeč při uploadu složky. Celá cesta je dostupná pouze v PHP 8.1 a vyšším. V předchozích verzích tato metoda vrací originální název souboru.
Nevěřte hodnotě vrácené touto metodou. Klient mohl odeslat škodlivý název souboru s úmyslem poškodit nebo hacknout vaši aplikaci.
getSize(): int
Vrací velikost uploadovaného souboru. V případě, že upload nebyl úspěšný, vrací 0
.
getTemporaryFile(): string
Vrací cestu k dočasné lokaci uploadovaného souboru. V případě, že upload nebyl úspěšný, vrací
''
.
isImage(): bool
Vrací true
, pokud nahraný soubor je obrázek ve formátu JPEG, PNG, GIF, WebP nebo AVIF. Detekce probíhá na
základě jeho signatury a neověřuje se integrita celého souboru. Zda není obrázek poškozený lze zjistit například
pokusem o jeho načtení.
Vyžaduje PHP rozšíření fileinfo
.
getImageSize(): ?array
Vrací dvojici [šířka, výška]
s rozměry uploadovaného obrázku. V případě, že upload nebyl
úspěšný nebo nejde o platný obrázek, vrací null
.
toImage(): Nette\Utils\Image
Načte obrázek jak objekt Image. V případě, že upload nebyl úspěšný
nebo nejde o platný obrázek, vyhodí výjimku Nette\Utils\ImageException
.