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 mit Hilfe von Dependency Injection an sich selbst weitergeben lassen. In Presentern müssen Sie nur die Methode $this->getHttpRequest() aufrufen. Wenn Sie außerhalb des Nette-Frameworks arbeiten, können Sie das Objekt mit RequestFactory erstellen.

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

→ Installation und Voraussetzungen

Nette\Http\Request

Dieses Objekt ist unveränderlich. Es hat keine Setter, sondern nur einen sogenannten Wither withUrl(), der das Objekt nicht verändert, sondern eine neue Instanz mit einem 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 Objekt UrlScript zurück.

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

Warnung: Browser senden keine Fragmente an den Server, so dass $url->getFragment() einen leeren String zurückgibt.

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

Gibt GET-Anfrageparameter zurück:

$all = $httpRequest->getQuery(); // Array mit allen URL-Parametern
$id = $httpRequest->getQuery('id'); // liefert den GET-Parameter 'id' (oder null)

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

Gibt die Parameter der POST-Anforderung zurück:

$all = $httpRequest->getPost(); // Array mit allen POST-Parametern
$id = $httpRequest->getPost('id'); // gibt den POST-Parameter 'id' (oder null) zurück

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

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

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

Geben Sie ein Array von Schlüsseln für den Zugriff auf die Teilbaumstruktur an.

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

Da man den Daten von außen nicht trauen kann und sich daher nicht auf die Form der Struktur verlassen kann, ist diese Methode sicherer als $request->getFiles()['my-form']['details']['avatar'], die fehlschlagen kann.

getFiles(): array

Gibt einen Baum von Upload-Dateien in einer normalisierten Struktur zurück, wobei jedes Blatt eine Instanz von Nette\Http\FileUpload ist:

$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 gestellt wurde.

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

isMethod (string $method): bool

Prüft die HTTP-Methode, mit der die Anfrage gestellt wurde. Der Parameter unterscheidet nicht zwischen Groß- und Kleinschreibung.

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

getHeader (string $header): ?string

Gibt einen HTTP-Header zurück oder null, wenn er nicht existiert. Der Parameter unterscheidet nicht zwischen Groß- und Kleinschreibung:

$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)? Möglicherweise müssen Sie einen Proxy ein richten, damit die Verbindung funktioniert.

isSameSite(): bool

Kommt die Anfrage von der gleichen (Sub-)Domain und wird durch Anklicken eines Links ausgelöst? Nette verwendet das Cookie _nss (früher nette-samesite), um dies zu erkennen.

isAjax(): bool

Handelt es sich um eine AJAX-Anfrage?

getRemoteAddress(): ?string

Gibt die IP-Adresse des Benutzers zurück. Für eine ordnungsgemäße Funktion müssen Sie möglicherweise einen Proxy ein richten.

getRemoteHost(): ?string

Gibt die DNS-Übersetzung der IP-Adresse des Benutzers zurück. Für eine ordnungsgemäße Funktion müssen Sie möglicherweise einen Proxy ein richten.

getBasicCredentials(): ?string

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

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

getRawBody(): ?string

Gibt den Body der HTTP-Anfrage zurück:

$body = $httpRequest->getRawBody();

detectLanguage (array $langs): ?string

Ermittelt die Sprache. Als Parameter $lang wird eine Reihe von Sprachen übergeben, die die Anwendung unterstützt, und es wird die vom Browser bevorzugte Sprache zurückgegeben. Es handelt sich nicht um Magie, die Methode verwendet einfach die Kopfzeile Accept-Language. Wird keine Übereinstimmung erzielt, gibt sie null zurück.

// Vom Browser gesendeter Header: Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3

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

RequestFactory

Die Klasse Nette\Http\RequestFactory wird verwendet, um eine Instanz von Nette\Http\Request zu erstellen, die die aktuelle HTTP-Anfrage darstellt. (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 ein Anfrageobjekt auf der Grundlage der aktuellen globalen PHP-Variablen ($_GET, $_POST, $_COOKIE, $_FILES und $_SERVER). Bei der Erstellung des Objekts werden automatisch alle Eingabeparameter GET, POST, COOKIE sowie die URL von Steuerzeichen und ungültigen UTF-8-Sequenzen bereinigt, was die Sicherheit bei der späteren Arbeit mit diesen Daten gewährleistet.

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

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

Mit RequestFactory können Sie Filter definieren, die Teile der URL-Anfrage automatisch umwandeln. Diese Filter entfernen unerwünschte Zeichen aus URLs, die z. B. durch die fehlerhafte Implementierung von Kommentarsystemen auf verschiedenen Websites eingefügt worden sein können:

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

// Entfernen eines Punktes, eines Kommas oder einer rechten Klammer am Ende des URI
$requestFactory->urlFilters['url']['[.,)]$'] = '';

// Bereinigung des Pfads 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 ein regulärer Ausdruck, nach dem gesucht wird, und der Wert ist die Ersetzung, die anstelle des gefundenen Textes verwendet werden soll.

Hochgeladene Dateien

Die Methode Nette\Http\Request::getFiles() gibt einen Baum von Upload-Dateien in einer normalisierten Struktur zurück, wobei jedes Blatt eine Instanz von Nette\Http\FileUpload ist. Diese Objekte kapseln die Daten, die vom <input type=file> Formular-Element übermittelt wurden.

Die Struktur spiegelt die Benennung von Elementen in HTML wider. Im einfachsten Beispiel könnte dies ein einzelnes benanntes Formularelement sein, das wie folgt übermittelt wird:

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

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

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

Das Objekt FileUpload wird auch dann erstellt, wenn der Benutzer keine Datei hochgeladen hat oder der Upload fehlgeschlagen ist. Die Methode hasFile() gibt true zurück, wenn eine Datei gesendet wurde:

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

Im Falle einer Eingabe mit Array-Notation für den Namen:

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

Der zurückgegebene Baum sieht dann wie folgt aus:

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

Sie können auch Arrays von Dateien erstellen:

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

In einem solchen Fall sieht die Struktur wie folgt aus:

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

Der beste Weg, um auf den Index 1 eines verschachtelten Arrays zuzugreifen, ist wie folgt:

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

Da man den Daten von außen nicht trauen kann und daher nicht auf die Form der Struktur angewiesen ist, ist diese Methode sicherer als $request->getFiles()['my-form']['details']['avatars'][1], die fehlschlagen kann.

Überblick über die 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 mit der hochgeladenen Datei verbundenen Fehlercode zurück. Es handelt sich um eine der Konstanten UPLOAD_ERR_XXX. Wurde die Datei erfolgreich hochgeladen, wird UPLOAD_ERR_OK zurückgegeben.

move (string $dest)

Verschiebt eine 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, wird null zurückgegeben.

getContentType(): ?string

Ermittelt den MIME-Inhaltstyp der hochgeladenen Datei anhand ihrer Signatur. Wenn der Upload nicht erfolgreich war oder die Erkennung fehlgeschlagen ist, wird null zurückgegeben.

Erfordert die PHP-Erweiterung fileinfo.

getUntrustedName(): string

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

Vertrauen Sie nicht auf den von dieser Methode zurückgegebenen Wert. Ein Client könnte einen bösartigen Dateinamen mit der Absicht senden, Ihre Anwendung zu beschädigen oder zu hacken.

getSanitizedName(): string

Gibt den bereinigten Dateinamen zurück. Er enthält nur ASCII-Zeichen [a-zA-Z0-9.-]. Enthält der Name keine solchen Zeichen, wird “unbekannt” zurückgegeben. Wenn die Datei ein JPEG-, PNG-, GIF- oder WebP-Bild ist, wird die korrekte Dateierweiterung zurückgegeben.

Erfordert die PHP-Erweiterung fileinfo.

getSuggestedExtension(): ?string

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

Erfordert die PHP-Erweiterung fileinfo.

getUntrustedFullPath(): string

Gibt den vollständigen Originalpfad zurück, den der Browser beim Hochladen des Verzeichnisses angegeben hat. Der vollständige Pfad ist nur in PHP 8.1 und höher verfügbar. In früheren Versionen gibt diese Methode den nicht vertrauenswürdigen Dateinamen zurück.

Vertrauen Sie dem von dieser Methode zurückgegebenen Wert nicht. Ein Client könnte einen bösartigen Dateinamen mit der Absicht senden, 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, wird 0 zurückgegeben.

getTemporaryFile(): string

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

isImage(): bool

Gibt true zurück, wenn die hochgeladene Datei ein JPEG-, PNG-, GIF- oder WebP-Bild ist. Die Erkennung basiert auf ihrer Signatur. Die Integrität der gesamten Datei wird nicht geprüft. Sie können herausfinden, ob ein Bild nicht beschädigt ist, indem Sie beispielsweise versuchen, es zu laden.

Erfordert die PHP-Erweiterung fileinfo.

getImageSize(): ?array

Gibt ein Paar von [width, height] mit den Abmessungen des hochgeladenen Bildes zurück. Wenn der Upload nicht erfolgreich war oder kein gültiges Bild ist, wird null zurückgegeben.

toImage(): Nette\Utils\Image

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

  1. Dokumentation
  2. Nette HTTP
  3. HTTP-Anfrage
Version: 4.0