HTTP-Anfrage

Nette kapselt die HTTP-Anfrage in Objekte mit einer verständlichen API und bietet gleichzeitig einen Bereinigungsfilter.

Die HTTP-Anfrage wird durch das Objekt Nette\Http\Request repräsentiert. Wenn Sie mit Nette arbeiten, wird dieses Objekt automatisch vom Framework erstellt und Sie können es sich mittels Dependency Injection übergeben lassen. In Presentern reicht es aus, die Methode $this->getHttpRequest() aufzurufen. Wenn Sie außerhalb des Nette Frameworks arbeiten, können Sie das Objekt mithilfe von RequestFactory erstellen.

Ein großer Vorteil von Nette ist, dass beim Erstellen des Objekts alle Eingabeparameter GET, POST, COOKIE sowie die URL automatisch von Steuerzeichen und ungültigen UTF-8-Sequenzen bereinigt werden. Mit diesen Daten können Sie dann sicher weiterarbeiten. Die bereinigten Daten werden anschließend in Presentern und Formularen verwendet.

→ Installation und Anforderungen

Nette\Http\Request

Dieses Objekt ist immutable (unveränderlich). Es hat keine Setter, sondern nur einen sogenannten Wither withUrl(), der das Objekt nicht ändert, sondern eine neue Instanz mit dem geänderten Wert zurückgibt.

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

Gibt einen Klon mit einer anderen URL zurück.

getUrl(): Nette\Http\UrlScript

Gibt die URL der Anfrage als UrlScript-Objekt zurück.

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

Warnung: Browser senden kein Fragment an den Server, daher gibt $url->getFragment() einen leeren String zurück.

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

Gibt die GET-Parameter der Anfrage zurück.

$all = $httpRequest->getQuery(); // Gibt ein Array aller Parameter aus der URL zurück
$id = $httpRequest->getQuery('id'); // Gibt den GET-Parameter 'id' zurück (oder null)

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

Gibt die POST-Parameter der Anfrage zurück.

$all = $httpRequest->getPost(); // Gibt ein Array aller Parameter aus POST zurück
$id = $httpRequest->getPost('id'); // Gibt den POST-Parameter 'id' zurück (oder null)

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

Gibt den Upload als Nette\Http\FileUpload-Objekt zurück:

$file = $httpRequest->getFile('avatar');
if ($file?->hasFile()) { // Wurde eine Datei hochgeladen?
	$file->getUntrustedName(); // Vom Benutzer gesendeter Dateiname
	$file->getSanitizedName(); // Name ohne gefährliche Zeichen
}

Für den Zugriff auf eine verschachtelte Struktur geben Sie ein Array von Schlüsseln an.

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

Da man externen Daten nicht vertrauen kann und sich daher auch nicht auf die Struktur der Dateien verlassen kann, ist dieser Weg sicherer als z.B. $request->getFiles()['my-form']['details']['avatar'], was fehlschlagen kann.

getFiles(): array

Gibt einen Baum aller Uploads in einer normalisierten Struktur zurück, deren Blätter Nette\Http\FileUpload-Objekte sind:

$files = $httpRequest->getFiles();

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

Gibt ein Cookie zurück oder null, wenn es nicht existiert.

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

getCookies(): array

Gibt alle Cookies zurück.

$cookies = $httpRequest->getCookies();

getMethod(): string

Gibt die HTTP-Methode zurück, mit der die Anfrage gemacht wurde.

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

isMethod (string $method): bool

Testet die HTTP-Methode, mit der die Anfrage gemacht wurde. Der Parameter ist case-insensitive.

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

getHeader (string $header): ?string

Gibt einen HTTP-Header zurück oder null, wenn er nicht existiert. Der Parameter ist case-insensitive.

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

getHeaders(): array

Gibt alle HTTP-Header als assoziatives Array zurück.

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

isSecured(): bool

Ist die Verbindung verschlüsselt (HTTPS)? Für die korrekte Funktion kann es notwendig sein, einen Proxy einzurichten.

isSameSite(): bool

Kommt die Anfrage von derselben (Sub-)Domain und wird sie durch Klicken auf einen Link initiiert? Nette verwendet zur Erkennung das Cookie _nss (früher nette-samesite).

isAjax(): bool

Ist es eine AJAX-Anfrage?

getRemoteAddress(): ?string

Gibt die IP-Adresse des Benutzers zurück. Für die korrekte Funktion kann es notwendig sein, einen Proxy einzurichten.

getRemoteHost(): ?string

Gibt die DNS-Auflösung der IP-Adresse des Benutzers zurück. Für die korrekte Funktion kann es notwendig sein, einen Proxy einzurichten.

getBasicCredentials(): ?array

Gibt die Anmeldeinformationen für die Basic HTTP-Authentifizierung zurück.

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

getRawBody(): ?string

Gibt den Körper der HTTP-Anfrage zurück.

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

Erkennt die Sprache. Als Parameter $lang übergeben wir ein Array mit den von der Anwendung unterstützten Sprachen, und sie gibt diejenige zurück, die der Browser des Besuchers am liebsten sehen würde. Das ist keine Magie, es wird nur der Accept-Language-Header verwendet. Wenn keine Übereinstimmung gefunden wird, gibt sie null zurück.

// Der Browser sendet z.B. Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

$langs = ['hu', 'pl', 'en']; // Von der Anwendung unterstützte Sprachen
echo $httpRequest->detectLanguage($langs); // en

RequestFactory

Die Klasse Nette\Http\RequestFactory dient zur Erstellung einer Instanz von Nette\Http\Request, die die aktuelle HTTP-Anfrage repräsentiert. (Wenn Sie mit Nette arbeiten, wird das HTTP-Anfrageobjekt automatisch vom Framework erstellt.)

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

Die Methode fromGlobals() erstellt das Anfrageobjekt basierend auf den aktuellen globalen PHP-Variablen ($_GET, $_POST, $_COOKIE, $_FILES und $_SERVER). Beim Erstellen des Objekts bereinigt sie automatisch alle Eingabeparameter GET, POST, COOKIE sowie die URL von Steuerzeichen und ungültigen UTF-8-Sequenzen, was die Sicherheit bei der weiteren Arbeit mit diesen Daten gewährleistet.

RequestFactory kann vor dem Aufruf von fromGlobals() konfiguriert werden:

Mit der Methode $factory->setBinary() deaktivieren Sie die automatische Bereinigung der Eingabeparameter von Steuerzeichen und ungültigen UTF-8-Sequenzen.
Mit der Methode $factory->setProxy(...) geben Sie die IP-Adresse des Proxy-Servers an, was für die korrekte Erkennung der IP-Adresse des Benutzers notwendig ist.

RequestFactory ermöglicht die Definition von Filtern, die Teile der Anfrage-URL automatisch transformieren. Diese Filter entfernen unerwünschte Zeichen aus der URL, die dort beispielsweise durch eine falsche Implementierung von Kommentarsystemen auf verschiedenen Websites eingefügt werden können:

// Entfernung von Leerzeichen aus dem Pfad
$requestFactory->urlFilters['path']['%20'] = '';

// Entfernung von Punkt, Komma oder rechter Klammer am Ende der URI
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// Bereinigung des Pfades von doppelten Schrägstrichen (Standardfilter)
$requestFactory->urlFilters['path']['/{2,}'] = '/';

Der erste Schlüssel 'path' oder 'url' bestimmt, auf welchen Teil der URL der Filter angewendet wird. Der zweite Schlüssel ist der reguläre Ausdruck, der gesucht werden soll, und der Wert ist der Ersatz, der anstelle des gefundenen Textes verwendet wird.

Hochgeladene Dateien

Die Methode Nette\Http\Request::getFiles() gibt ein Array aller Uploads in einer normalisierten Struktur zurück, deren Blätter Nette\Http\FileUpload-Objekte sind. Diese kapseln die Daten, die von einem Formularelement <input type=file> gesendet wurden.

Die Struktur spiegelt die Benennung der Elemente in HTML wider. Im einfachsten Fall kann dies ein einzelnes benanntes Formularelement sein, das wie folgt gesendet wird:

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

In diesem Fall gibt $request->getFiles() ein Array zurück:

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

Das FileUpload-Objekt wird auch dann erstellt, wenn der Benutzer keine Datei gesendet hat oder das Senden fehlgeschlagen ist. Ob eine Datei gesendet wurde, gibt die Methode hasFile() zurück:

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

Im Falle eines Elementnamens, der die Array-Notation verwendet:

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

sieht der zurückgegebene Baum so aus:

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

Es kann auch ein Array von Dateien erstellt werden:

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

In einem solchen Fall sieht die Struktur so aus:

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

Der Zugriff auf den Index 1 des verschachtelten Arrays erfolgt am besten so:

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

Übersicht der `FileUpload`-Methoden

hasFile(): bool

Gibt true zurück, wenn der Benutzer eine Datei hochgeladen hat.

isOk(): bool

Gibt true zurück, wenn die Datei erfolgreich hochgeladen wurde.

getError(): int

Gibt den Fehlercode beim Hochladen der Datei zurück. Es handelt sich um eine der Konstanten UPLOAD_ERR_XXX. Wenn der Upload erfolgreich war, gibt sie UPLOAD_ERR_OK zurück.

move (string $dest)

Verschiebt die hochgeladene Datei an einen neuen Speicherort. Wenn die Zieldatei bereits existiert, wird sie überschrieben.

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

getContents(): ?string

Gibt den Inhalt der hochgeladenen Datei zurück. Wenn der Upload nicht erfolgreich war, gibt sie null zurück.

getContentType(): ?string

Erkennt den MIME-Inhaltstyp der hochgeladenen Datei anhand ihrer Signatur. Wenn der Upload nicht erfolgreich war oder die Erkennung fehlschlug, gibt sie null zurück.

Erfordert die PHP-Erweiterung fileinfo.

getUntrustedName(): string

Gibt den ursprünglichen Dateinamen zurück, wie er vom Browser gesendet wurde.

Vertrauen Sie nicht dem von dieser Methode zurückgegebenen Wert. Ein Client könnte einen bösartigen Dateinamen gesendet haben, um Ihre Anwendung zu beschädigen oder zu hacken.

getSanitizedName(): string

Gibt den bereinigten Dateinamen zurück. Enthält nur ASCII-Zeichen [a-zA-Z0-9.-]. Wenn der Name keine solchen Zeichen enthält, gibt sie 'unknown' zurück. Wenn die Datei ein Bild im Format JPEG, PNG, GIF, WebP oder AVIF ist, gibt sie auch die korrekte Erweiterung zurück.

Erfordert die PHP-Erweiterung fileinfo.

getSuggestedExtension(): ?string

Gibt die passende Dateierweiterung (ohne Punkt) zurück, die dem erkannten MIME-Typ entspricht.

Erfordert die PHP-Erweiterung fileinfo.

getUntrustedFullPath(): string

Gibt den ursprünglichen Dateipfad zurück, wie er vom Browser beim Hochladen eines Ordners gesendet wurde. Der vollständige Pfad ist nur in PHP 8.1 und höher verfügbar. In früheren Versionen gibt diese Methode den ursprünglichen Dateinamen zurück.

Vertrauen Sie nicht dem von dieser Methode zurückgegebenen Wert. Ein Client könnte einen bösartigen Dateinamen gesendet haben, um Ihre Anwendung zu beschädigen oder zu hacken.

getSize(): int

Gibt die Größe der hochgeladenen Datei zurück. Wenn der Upload nicht erfolgreich war, gibt sie 0 zurück.

getTemporaryFile(): string

Gibt den Pfad zum temporären Speicherort der hochgeladenen Datei zurück. Wenn der Upload nicht erfolgreich war, gibt sie '' zurück.

isImage(): bool

Gibt true zurück, wenn die hochgeladene Datei ein Bild im Format JPEG, PNG, GIF, WebP oder AVIF ist. Die Erkennung erfolgt anhand ihrer Signatur und die Integrität der gesamten Datei wird nicht überprüft. Ob ein Bild beschädigt ist, kann beispielsweise durch den Versuch, es zu Laden, festgestellt werden.

Erfordert die PHP-Erweiterung fileinfo.

getImageSize(): ?array

Gibt ein Paar [Breite, Höhe] mit den Abmessungen des hochgeladenen Bildes zurück. Wenn der Upload nicht erfolgreich war oder es sich nicht um ein gültiges Bild handelt, gibt sie null zurück.

toImage(): Nette\Utils\Image

Lädt das Bild als Image-Objekt. Wenn der Upload nicht erfolgreich war oder es sich nicht um ein gültiges Bild handelt, wird eine Ausnahme Nette\Utils\ImageException ausgelöst.

HTTP-Anfrage

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

Hochgeladene Dateien

Übersicht der FileUpload-Methoden

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

Übersicht der `FileUpload`-Methoden