HTTP-Response

Nette kapselt die HTTP-Response in Objekte mit einer klaren API.

Die HTTP-Response wird durch das Objekt Nette\Http\Response repräsentiert. Wenn Sie mit Nette arbeiten, wird dieses Objekt automatisch vom Framework erzeugt, und Sie können es sich per Dependency Injection übergeben lassen. In Presentern genügt der Aufruf der Methode $this->getHttpResponse().

→ Installation und Anforderungen

Nette\Http\Response

Anders als Nette\Http\Request ist dieses Objekt veränderlich, Sie können den Zustand also mit Settern ändern, etwa um Header zu senden. Denken Sie daran, dass alle Setter aufgerufen werden müssen, bevor irgendeine tatsächliche Ausgabe gesendet wird. Die Methode isSent() sagt, ob die Ausgabe bereits gesendet wurde. Gibt sie true zurück, wirft jeder Versuch, einen Header zu senden, eine Nette\InvalidStateException.

setCode (int $code, ?string $reason=null)

Ändert den Statuscode der Response. Für die bessere Lesbarkeit des Quellcodes empfiehlt es sich, statt tatsächlicher Zahlen die vordefinierten Konstanten zu verwenden.

$httpResponse->setCode(Nette\Http\Response::S404_NotFound);

getCode(): int

Gibt den Statuscode der Response zurück.

isSent(): bool

Gibt zurück, ob die Header bereits vom Server an den Browser gesendet wurden, es also nicht mehr möglich ist, Header zu senden oder den Statuscode zu ändern.

setHeader (string $name, ?string $value)

Sendet einen HTTP-Header und überschreibt einen zuvor gesendeten Header desselben Namens. Ist $value gleich null, wird der Header entfernt.

$httpResponse->setHeader('Pragma', 'no-cache');

addHeader (string $name, string $value)

Sendet einen HTTP-Header und überschreibt keinen zuvor gesendeten Header desselben Namens.

$httpResponse->addHeader('Accept', 'application/json');
$httpResponse->addHeader('Accept', 'application/xml');

deleteHeader (string $name)

Löscht einen zuvor gesendeten HTTP-Header.

getHeader (string $header): ?string

Gibt den gesendeten HTTP-Header zurück oder null, wenn er nicht existiert. Beim Parameter wird die Groß- und Kleinschreibung nicht unterschieden.

$pragma = $httpResponse->getHeader('Pragma');

getHeaders(): array<string, string>

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

$headers = $httpResponse->getHeaders();
echo $headers['Pragma'];

setContentType (string $type, ?string $charset=null)

Ändert den Header Content-Type.

$httpResponse->setContentType('text/plain', 'UTF-8');

redirect (string $url, int $code=self::S302_Found): void

Leitet auf eine andere URL weiter. Denken Sie daran, das Skript danach zu beenden.

$httpResponse->redirect('http://example.com');
exit;

setExpiration (?string $expire)

Setzt die Ablaufzeit des HTTP-Dokuments über die Header Cache-Control und Expires. Der Parameter ist entweder ein Zeitintervall (als Text) oder null, was das Caching abschaltet.

// der Browser-Cache läuft in einer Stunde ab
$httpResponse->setExpiration('1 hour');

sendAsFile (string $fileName)

Die Response wird über einen Speichern unter-Dialog mit dem angegebenen Namen heruntergeladen. Die Datei selbst wird nicht gesendet.

$httpResponse->sendAsFile('invoice.pdf');

setCookie (string $name, string $value, $expire, ?string $path=null, ?string $domain=null, ?bool $secure=null, ?bool $httpOnly=null, SameSite|string $sameSite='Lax', bool $partitioned=false)

Sendet ein Cookie. Standardwerte der Parameter:

Die Standardwerte der Parameter $path, $domain und $secure können Sie in der Konfiguration ändern.

Die Ablaufzeit wird als Anzahl von Sekunden, als Textintervall oder Datum oder als Objekt vom Typ DateTimeInterface übergeben. Der Wert null erzeugt ein Session-Cookie, das der Browser beim Schließen verwirft. Nette sendet die Ablaufzeit sowohl im Attribut Expires als auch in Max-Age.

$httpResponse->setCookie('lang', 'en', '100 days');  // läuft in 100 Tagen ab
$httpResponse->setCookie('lang', 'en', null);        // Session-Cookie

Der Parameter $domain bestimmt, welche Domains das Cookie annehmen dürfen. Wird er nicht angegeben, nimmt es dieselbe (Sub-)Domain an, die es gesetzt hat, aber nicht deren Subdomains. Ist $domain angegeben, sind auch die Subdomains eingeschlossen. Die Angabe von $domain ist also weniger einschränkend als ihr Weglassen. Mit $domain = 'nette.org' sind die Cookies zum Beispiel auch auf allen Subdomains wie doc.nette.org verfügbar.

Den Wert $sameSite können Sie als Enum Nette\Http\SameSite übergeben – SameSite::Lax, SameSite::Strict oder SameSite::None (die String-Werte 'Lax', 'Strict', 'None' funktionieren ebenfalls). Setzen Sie ihn auf SameSite::None, wird das Attribut $secure automatisch aktiviert, denn Browser weisen ein Cookie mit SameSite=None ab, das nicht secure ist.

Partitionierte Cookies (CHIPS) geben einem Cookie für jede Top-Level-Site einen eigenen, getrennten Speicher. Setzt also ein Drittanbieterdienst (etwa ein eingebettetes Widget) ein partitioniertes Cookie, hält der Browser für jede Site, auf der das Widget erscheint, eine eigene Kopie, und diese Kopien lassen sich nicht zum seitenübergreifenden Tracking verknüpfen. Sie schalten es ein, indem Sie $partitioned auf true setzen; das erfordert außerdem das Attribut $secure, das deshalb automatisch aktiviert wird.

$httpResponse->setCookie('theme', 'dark', '1 year', sameSite: SameSite::None, partitioned: true);

deleteCookie (string $name, ?string $path=null, ?string $domain=null, ?bool $secure=null): void

Löscht ein Cookie. Die Standardwerte der Parameter sind:

• $path mit Geltung für alle Verzeichnisse ('/')
• $domain mit Geltung für die aktuelle (Sub-)Domain, aber nicht deren Subdomains
• $secure hängt von den Einstellungen in der Konfiguration ab

$httpResponse->deleteCookie('lang');

Nette\Http\Context

Das Objekt Nette\Http\Context verbindet Request und Response miteinander und hilft beim HTTP-Caching. Es ist nicht als Service registriert, Sie erzeugen es also selbst. In Presentern ist es meist einfacher, die Methode lastModified() zu verwenden; der Context ist nützlich, wenn Sie die Response selbst senden, zum Beispiel aus einer eigenen Response-Klasse.

isModified (string|int|\DateTimeInterface|null $lastModified=null, ?string $etag=null): bool

Stellt fest, ob sich der Inhalt seit dem letzten Besuch des Clients geändert hat. Übergeben Sie die Zeit der letzten Änderung, sendet sie den Header Last-Modified; übergeben Sie einen ETag-Validator (einen kurzen String, der die aktuelle Version des Inhalts kennzeichnet, z. B. dessen Hash), sendet sie den Header ETag. Anschließend vergleicht sie beides mit den vom Browser gesendeten Headern If-Modified-Since und If-None-Match.

Hat der Browser bereits eine passende Version, setzt die Methode den Code 304 Not Modified und gibt false zurück – senden Sie den Body der Response in diesem Fall gar nicht erst. Andernfalls gibt sie true zurück.

public function send(Nette\Http\IRequest $request, Nette\Http\IResponse $response): void
{
	$context = new Nette\Http\Context($request, $response);
	if ($context->isModified(filemtime($this->file), md5_file($this->file))) {
		readfile($this->file);
	}
}

Beide Parameter sind optional. Wenn Sie die Änderungszeit des Inhalts nicht kennen, verwenden Sie nur den ETag und umgekehrt.