Réponse HTTP
************

.[perex]
Nette encapsule la réponse HTTP dans des objets dotés d'une API claire.

La réponse HTTP est représentée par l'objet [api:Nette\Http\Response]. Si vous travaillez avec Nette, cet objet est créé automatiquement par le framework et vous pouvez vous le faire passer par [injection de dépendances |dependency-injection:passing-dependencies]. Dans les presenters, il suffit d'appeler la méthode `$this->getHttpResponse()`.

→ [Installation et prérequis |@home#Installation]


Nette\Http\Response
===================

Contrairement à [Nette\Http\Request |request], cet objet est modifiable : vous pouvez donc utiliser des setters pour changer son état, par exemple pour envoyer des en-têtes. Rappelez-vous que tous les setters **doivent être appelés avant qu'une quelconque sortie ne soit envoyée.** La méthode `isSent()` indique si la sortie a déjà été envoyée. Si elle renvoie `true`, toute tentative d'envoi d'un en-tête lèvera une `Nette\InvalidStateException`.


setCode(int $code, ?string $reason=null) .[method]
--------------------------------------------------
Change le [code de statut |https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10] de la réponse. Pour une meilleure lisibilité du code source, il est recommandé d'utiliser les [constantes prédéfinies |api:Nette\Http\IResponse] plutôt que les nombres eux-mêmes.

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


getCode(): int .[method]
------------------------
Renvoie le code de statut de la réponse.


isSent(): bool .[method]
------------------------
Indique si les en-têtes ont déjà été envoyés du serveur au navigateur, autrement dit s'il n'est plus possible d'envoyer des en-têtes ni de changer le code de statut.


setHeader(string $name, ?string $value) .[method]
-------------------------------------------------
Envoie un en-tête HTTP et **écrase** un en-tête du même nom envoyé précédemment. Si `$value` vaut `null`, l'en-tête sera supprimé.

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


addHeader(string $name, string $value) .[method]
------------------------------------------------
Envoie un en-tête HTTP et **n'écrase pas** un en-tête du même nom envoyé précédemment.

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


deleteHeader(string $name) .[method]
------------------------------------
Supprime un en-tête HTTP envoyé précédemment.


getHeader(string $header): ?string .[method]
--------------------------------------------
Renvoie l'en-tête HTTP envoyé, ou `null` s'il n'existe pas. Le paramètre est insensible à la casse.

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


getHeaders(): array<string, string> .[method]
---------------------------------------------
Renvoie tous les en-têtes HTTP envoyés sous forme de tableau associatif.

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


setContentType(string $type, ?string $charset=null) .[method]
-------------------------------------------------------------
Change l'en-tête `Content-Type`.

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


redirect(string $url, int $code=self::S302_Found): void .[method]
-----------------------------------------------------------------
Redirige vers une autre URL. Pensez à terminer le script ensuite.

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


setExpiration(?string $expire) .[method]
----------------------------------------
Définit l'expiration du document HTTP à l'aide des en-têtes `Cache-Control` et `Expires`. Le paramètre est soit un intervalle de temps (sous forme de texte), soit `null`, ce qui désactive la mise en cache.

```php
// le cache du navigateur expire dans une heure
$httpResponse->setExpiration('1 hour');
```


sendAsFile(string $fileName) .[method]
--------------------------------------
La réponse sera téléchargée via une boîte de dialogue *Enregistrer sous* portant le nom indiqué. Elle n'envoie pas le fichier lui-même.

```php
$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) .[method]
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Envoie un cookie. Valeurs par défaut des paramètres :

| `$path`        | `'/'`   | le cookie est disponible pour tous les chemins du (sous-)domaine *(configurable)*
| `$domain`      | `null`  | c'est-à-dire disponible pour le (sous-)domaine courant, mais pas pour ses sous-domaines *(configurable)*
| `$secure`      | `auto`  | `true` si le site tourne en HTTPS, sinon `false` (valeur par défaut du framework ; la classe seule vaut `false` par défaut) *(configurable)*
| `$httpOnly`    | `true`  | le cookie est inaccessible au JavaScript
| `$sameSite`    | `'Lax'` | le cookie peut ne pas être envoyé lors d'un [accès cross-origin |nette:glossary#Cookie SameSite]
| `$partitioned` | `false` | indique si le cookie est partitionné, voir plus bas *(depuis la v3.4)*

Vous pouvez changer les valeurs par défaut des paramètres `$path`, `$domain` et `$secure` dans la [configuration |configuration#Cookie HTTP].

L'expiration se passe sous forme de nombre de secondes, d'intervalle ou de date en texte, ou d'objet `DateTimeInterface`. La valeur `null` crée un cookie de session, que le navigateur jette à sa fermeture. Nette envoie l'expiration à la fois dans les attributs `Expires` et `Max-Age`.

```php
$httpResponse->setCookie('lang', 'en', '100 days');  // expire dans 100 jours
$httpResponse->setCookie('lang', 'en', null);        // cookie de session
```

Le paramètre `$domain` détermine quels domaines peuvent accepter le cookie. S'il n'est pas indiqué, le cookie est accepté par le même (sous-)domaine que celui qui l'a défini, mais pas par ses sous-domaines. Si `$domain` est indiqué, les sous-domaines sont inclus eux aussi. Indiquer `$domain` est donc moins restrictif que de l'omettre. Par exemple, avec `$domain = 'nette.org'`, les cookies sont aussi disponibles sur tous les sous-domaines comme `doc.nette.org`.

Vous pouvez passer la valeur `$sameSite` sous forme d'enum `Nette\Http\SameSite` - `SameSite::Lax`, `SameSite::Strict` ou `SameSite::None` (les valeurs chaîne `'Lax'`, `'Strict'`, `'None'` fonctionnent aussi). Si vous la fixez à `SameSite::None`, l'attribut `$secure` est activé automatiquement, car les navigateurs refusent un cookie `SameSite=None` qui n'est pas sécurisé.

.{data-version:3.4.0}
Les cookies partitionnés (CHIPS) donnent à un cookie son propre stockage distinct pour chaque site de premier niveau. Ainsi, lorsqu'un service tiers (par exemple un widget intégré) pose un cookie partitionné, le navigateur en conserve une copie distincte pour chaque site où le widget apparaît, et ces copies ne peuvent pas être reliées entre elles à des fins de pistage inter-sites. Activez-les en fixant `$partitioned` à `true` ; cela exige aussi l'attribut `$secure`, qui est donc activé automatiquement.

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


deleteCookie(string $name, ?string $path=null, ?string $domain=null, ?bool $secure=null): void .[method]
--------------------------------------------------------------------------------------------------------
Supprime un cookie. Les valeurs par défaut des paramètres sont :
- `$path` avec une portée sur tous les répertoires (`'/'`)
- `$domain` avec une portée sur le (sous-)domaine courant, mais pas sur ses sous-domaines
- `$secure` dépend des réglages de la [configuration |configuration#Cookie HTTP]

```php
$httpResponse->deleteCookie('lang');
```


Nette\Http\Context
==================

L'objet [api:Nette\Http\Context] réunit la requête et la réponse et aide à la mise en cache HTTP. Il n'est pas enregistré comme service, vous le créez donc vous-même. Dans les presenters, il est généralement plus simple d'utiliser la méthode [lastModified() |application:presenters#Cache HTTP] ; le contexte est utile quand vous envoyez vous-même la réponse, par exemple depuis votre propre classe de réponse.


isModified(string|int|\DateTimeInterface|null $lastModified=null, ?string $etag=null): bool .[method]
-----------------------------------------------------------------------------------------------------
Détermine si le contenu a changé depuis la dernière visite du client. Si vous passez la date de dernière modification, elle envoie l'en-tête `Last-Modified` ; si vous passez un validateur ETag (une courte chaîne identifiant la version actuelle du contenu, par exemple son hachage), elle envoie l'en-tête `ETag`. Elle compare ensuite les deux aux en-têtes `If-Modified-Since` et `If-None-Match` envoyés par le navigateur.

Si le navigateur détient déjà une version correspondante, la méthode fixe le code `304 Not Modified` et renvoie `false` : dans ce cas, n'envoyez pas du tout le corps de la réponse. Sinon, elle renvoie `true`.

```php
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);
	}
}
```

Les deux paramètres sont facultatifs. Si vous ne connaissez pas la date de modification du contenu, n'utilisez que l'ETag, et inversement.