HTTP-Anfrage

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

Eine HTTP-Anfrage ist ein Nette\Http\Request -Objekt, das Sie erhalten, indem Sie es mit Hilfe von Dependency Injection übergeben. In Moderatoren rufen Sie einfach $httpRequest = $this->getHttpRequest() auf.

Wichtig ist, dass Nette bei der Erstellung dieses Objekts alle GET-, POST- und COOKIE-Eingabeparameter sowie URLs von Steuerzeichen und ungültigen UTF-8-Sequenzen befreit. Sie können also gefahrlos mit den Daten weiterarbeiten. Die bereinigten Daten werden dann 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

Das Objekt der aktuellen HTTP-Anfrage wird von Nette\Http\RequestFactory erstellt. Wenn Sie eine Anwendung schreiben, die keinen DI-Container verwendet, erstellen Sie einen Request wie folgt:

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

Die RequestFactory kann vor dem Aufruf von fromGlobals() konfiguriert werden. Wir können alle Sanitization von Eingabeparametern aus ungültigen UTF-8-Sequenzen mit $factory->setBinary() deaktivieren. Und auch einen Proxy-Server einrichten, der für die korrekte Erkennung der IP-Adresse des Benutzers mit $factory->setProxy(...) wichtig ist.

Mit Hilfe von Filtern können URLs von Zeichen bereinigt werden, die aufgrund schlecht implementierter Kommentarsysteme auf verschiedenen anderen Websites in sie gelangen können:

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

// Punkt, Komma oder rechte Klammer am Ende des URLs entfernen
$requestFactory->urlFilters['url']['[.,)]$'] = '';

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

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.