Nette Documentation Preview

syntax 
Configuration HTTP
******************

.[perex]
Aperçu des options de configuration de Nette HTTP.

Si vous n'utilisez pas tout le framework, mais seulement cette bibliothèque, lisez [comment charger la configuration|bootstrap:].


En-têtes HTTP
=============

```neon
http:
	# en-têtes envoyés avec chaque réponse
	headers:
		X-Powered-By: MyCMS
		X-Content-Type-Options: nosniff
		X-XSS-Protection: '1; mode=block'

	# influence l'en-tête X-Frame-Options
	frames: ...      # (string|bool|null) 'SAMEORIGIN' par défaut
```

Pour des raisons de sécurité, le framework envoie l'en-tête `X-Frame-Options: SAMEORIGIN`, qui indique qu'une page ne peut être affichée à l'intérieur d'une autre page (dans un élément `<iframe>`) que si elle se trouve sur le même domaine. Cela peut être indésirable dans certaines situations (par exemple si vous développez une application Facebook) ; le comportement peut donc être modifié en définissant `frames: http://allowed-host.com` pour autoriser un hôte précis, `frames: true` pour autoriser l'inclusion depuis n'importe où (l'en-tête est omis), ou `frames: false` pour l'interdire complètement (`X-Frame-Options: DENY`).

Par défaut, Nette envoie aussi les en-têtes `X-Powered-By: Nette Framework 3` et `Content-Type: text/html; charset=utf-8`. Vous pouvez supprimer n'importe quel en-tête, y compris ceux par défaut, en fixant sa valeur à une chaîne vide.


Content Security Policy
-----------------------

Les en-têtes `Content-Security-Policy` (CSP) se configurent facilement ; leur description se trouve dans la [spécification CSP |https://content-security-policy.com]. Les directives CSP (comme `script-src`) peuvent s'écrire soit sous forme de chaînes conformes à la spécification, soit sous forme de tableaux de valeurs, plus lisibles. Il n'est alors pas nécessaire d'entourer de guillemets les mots-clés comme `'self'`. Nette générera aussi automatiquement une valeur `nonce`, si bien que quelque chose comme `'nonce-y4PopTLM=='` sera envoyé dans l'en-tête.

```neon
http:
	# Content Security Policy
	csp:
		# chaîne conforme à la spécification CSP
		default-src: "'self' https://example.com"

		# tableau de valeurs
		script-src:
			- nonce
			- strict-dynamic
			- self
			- https://example.com

		# bool dans le cas des interrupteurs
		upgrade-insecure-requests: true
		block-all-mixed-content: false
```

Utilisez `<script n:nonce>...</script>` dans les templates et la valeur du nonce sera renseignée automatiquement. Faire des sites web sûrs avec Nette est vraiment facile.

De la même façon, on peut configurer les en-têtes `Content-Security-Policy-Report-Only` (utilisables en parallèle de CSP) et la [Feature Policy|https://developers.google.com/web/updates/2018/06/feature-policy] :

```neon
http:
	# Content Security Policy Report-Only
	cspReportOnly:
		default-src: self
		report-uri: 'https://my-report-uri-endpoint'

	# Feature Policy
	featurePolicy:
		unsized-media: none
		geolocation:
			- self
			- https://example.com
```


Cookie HTTP
-----------

Vous pouvez changer les valeurs par défaut de certains paramètres de la méthode [Nette\Http\Response::setCookie() |response#setCookie()] et de la gestion des sessions.

```neon
http:
	# portée du cookie par chemin
	cookiePath: ...          # (string) '/' par défaut

	# domaines qui peuvent recevoir le cookie
	cookieDomain: 'example.com'  # (string|domain) non défini par défaut

	# n'envoyer les cookies que via HTTPS ?
	cookieSecure: ...        # (bool|auto) auto par défaut

	# désactive l'envoi du cookie que Nette utilise pour la protection CSRF
	disableNetteCookie: ...  # (bool) false par défaut
```

L'attribut `cookieDomain` détermine quels domaines (origines) peuvent accepter les cookies. S'il n'est pas indiqué, le cookie est accepté par le même (sous-)domaine que celui qui l'a défini, *à l'exclusion* de ses sous-domaines. Si `cookieDomain` est indiqué, les sous-domaines sont inclus eux aussi. Indiquer `cookieDomain` est donc moins restrictif que de l'omettre.

Par exemple, si `cookieDomain: nette.org` est défini, les cookies sont aussi disponibles sur tous les sous-domaines comme `doc.nette.org`. On peut aussi y parvenir avec la valeur spéciale `domain`, c'est-à-dire `cookieDomain: domain`.

La valeur par défaut `auto` de l'attribut `cookieSecure` signifie que si le site tourne en HTTPS, les cookies seront envoyés avec le drapeau `Secure` et ne seront donc disponibles que via HTTPS.


Proxy HTTP
----------

Si le site tourne derrière un proxy HTTP, indiquez l'adresse IP du proxy afin que la détection de la connexion HTTPS et l'adresse IP du client fonctionnent correctement. Autrement dit, pour que [Nette\Http\Request::getRemoteAddress() |request#getRemoteAddress()] et [isSecured() |request#isSecured()] renvoient les bonnes valeurs et que les liens soient générés avec le protocole `https:` dans les templates.

```neon
http:
	# adresse IP, plage (par exemple 127.0.0.1/8), ou tableau de ces valeurs
	proxy: 127.0.0.1       # (string|string[]) non défini par défaut
```


Forcer HTTPS .{data-version:3.3.4}
----------------------------------

Force sans condition le schéma de la requête en HTTPS. C'est utile pour les sites uniquement HTTPS qui tournent derrière un répartiteur de charge ou un reverse proxy terminant le TLS mais ne transmettant pas l'en-tête `X-Forwarded-Proto`, si bien que la détection HTTPS standard (même avec un [#Proxy HTTP] configuré) ne le remarquerait pas.

```neon
http:
	# force le schéma HTTPS pour toutes les requêtes
	forceHttps: true       # (bool) false par défaut
```


Session
=======

Réglages de base des [sessions] :

```neon
session:
	# afficher le panneau de session dans la Tracy Bar ?
	debugger: ...        # (bool) false par défaut

	# durée d'inactivité au bout de laquelle la session expire
	expiration: 14 days  # (string) '3 hours' par défaut

	# quand la session doit-elle démarrer ?
	autoStart: ...       # (smart|always|never) 'smart' par défaut

	# handler, un service implémentant SessionHandlerInterface
	handler: @handlerService
```

L'option `autoStart` détermine quand la session doit démarrer. La valeur `always` signifie que la session démarre dès que l'application démarre. La valeur `smart` signifie que la session ne démarre avec l'application que si elle existe déjà, ou au moment où nous voulons y lire ou y écrire. Enfin, la valeur `never` désactive le démarrage automatique de la session.

Vous pouvez en outre définir toutes les [directives de session |https://www.php.net/manual/en/session.configuration.php] de PHP (au format camelCase) ainsi que [readAndClose |https://www.php.net/manual/en/function.session-start.php#refsect1-function.session-start-parameters]. Exemple :

```neon
session:
	# 'session.name' s'écrit 'name'
	name: MYID

	# 'session.save_path' s'écrit 'savePath'
	savePath: "%tempDir%/sessions"
```


Cookie de session
-----------------

Le cookie de session est envoyé avec les mêmes paramètres que les [autres cookies |#Cookie HTTP], mais vous pouvez les changer spécialement pour lui :

```neon
session:
	# domaines qui peuvent recevoir le cookie
	cookieDomain: 'example.com'   # (string|domain)

	# restriction pour l'accès cross-origin
	cookieSamesite: None          # (Strict|Lax|None) Lax par défaut
```

L'attribut `cookieSamesite` détermine si le cookie est envoyé lors des [requêtes cross-origin |nette:glossary#Cookie SameSite], ce qui offre une certaine protection contre les attaques [Cross-Site Request Forgery |nette:glossary#Cross-Site Request Forgery (CSRF)] (CSRF).


Services DI
===========

Ces services sont ajoutés au conteneur DI :

| Nom             | Type                       | Description
|-----------------|----------------------------|---------------------------
| `http.request`  | [api:Nette\Http\Request]   | [requête HTTP| request]
| `http.response` | [api:Nette\Http\Response]  | [réponse HTTP| response]
| `session.session`| [api:Nette\Http\Session]   | [gestion des sessions| sessions]
| `http.requestFactory`| [api:Nette\Http\RequestFactory] | factory qui crée la requête HTTP

Configuration HTTP

Aperçu des options de configuration de Nette HTTP.

Si vous n'utilisez pas tout le framework, mais seulement cette bibliothèque, lisez comment charger la configuration.

En-têtes HTTP

http:
	# en-têtes envoyés avec chaque réponse
	headers:
		X-Powered-By: MyCMS
		X-Content-Type-Options: nosniff
		X-XSS-Protection: '1; mode=block'

	# influence l'en-tête X-Frame-Options
	frames: ...      # (string|bool|null) 'SAMEORIGIN' par défaut

Pour des raisons de sécurité, le framework envoie l'en-tête X-Frame-Options: SAMEORIGIN, qui indique qu'une page ne peut être affichée à l'intérieur d'une autre page (dans un élément <iframe>) que si elle se trouve sur le même domaine. Cela peut être indésirable dans certaines situations (par exemple si vous développez une application Facebook) ; le comportement peut donc être modifié en définissant frames: http://allowed-host.com pour autoriser un hôte précis, frames: true pour autoriser l'inclusion depuis n'importe où (l'en-tête est omis), ou frames: false pour l'interdire complètement (X-Frame-Options: DENY).

Par défaut, Nette envoie aussi les en-têtes X-Powered-By: Nette Framework 3 et Content-Type: text/html; charset=utf-8. Vous pouvez supprimer n'importe quel en-tête, y compris ceux par défaut, en fixant sa valeur à une chaîne vide.

Content Security Policy

Les en-têtes Content-Security-Policy (CSP) se configurent facilement ; leur description se trouve dans la spécification CSP. Les directives CSP (comme script-src) peuvent s'écrire soit sous forme de chaînes conformes à la spécification, soit sous forme de tableaux de valeurs, plus lisibles. Il n'est alors pas nécessaire d'entourer de guillemets les mots-clés comme 'self'. Nette générera aussi automatiquement une valeur nonce, si bien que quelque chose comme 'nonce-y4PopTLM==' sera envoyé dans l'en-tête.

http:
	# Content Security Policy
	csp:
		# chaîne conforme à la spécification CSP
		default-src: "'self' https://example.com"

		# tableau de valeurs
		script-src:
			- nonce
			- strict-dynamic
			- self
			- https://example.com

		# bool dans le cas des interrupteurs
		upgrade-insecure-requests: true
		block-all-mixed-content: false

Utilisez <script n:nonce>...</script> dans les templates et la valeur du nonce sera renseignée automatiquement. Faire des sites web sûrs avec Nette est vraiment facile.

De la même façon, on peut configurer les en-têtes Content-Security-Policy-Report-Only (utilisables en parallèle de CSP) et la Feature Policy :

http:
	# Content Security Policy Report-Only
	cspReportOnly:
		default-src: self
		report-uri: 'https://my-report-uri-endpoint'

	# Feature Policy
	featurePolicy:
		unsized-media: none
		geolocation:
			- self
			- https://example.com

Vous pouvez changer les valeurs par défaut de certains paramètres de la méthode Nette\Http\Response::setCookie() et de la gestion des sessions.

http:
	# portée du cookie par chemin
	cookiePath: ...          # (string) '/' par défaut

	# domaines qui peuvent recevoir le cookie
	cookieDomain: 'example.com'  # (string|domain) non défini par défaut

	# n'envoyer les cookies que via HTTPS ?
	cookieSecure: ...        # (bool|auto) auto par défaut

	# désactive l'envoi du cookie que Nette utilise pour la protection CSRF
	disableNetteCookie: ...  # (bool) false par défaut

L'attribut cookieDomain détermine quels domaines (origines) peuvent accepter les cookies. S'il n'est pas indiqué, le cookie est accepté par le même (sous-)domaine que celui qui l'a défini, à l'exclusion de ses sous-domaines. Si cookieDomain est indiqué, les sous-domaines sont inclus eux aussi. Indiquer cookieDomain est donc moins restrictif que de l'omettre.

Par exemple, si cookieDomain: nette.org est défini, les cookies sont aussi disponibles sur tous les sous-domaines comme doc.nette.org. On peut aussi y parvenir avec la valeur spéciale domain, c'est-à-dire cookieDomain: domain.

La valeur par défaut auto de l'attribut cookieSecure signifie que si le site tourne en HTTPS, les cookies seront envoyés avec le drapeau Secure et ne seront donc disponibles que via HTTPS.

Proxy HTTP

Si le site tourne derrière un proxy HTTP, indiquez l'adresse IP du proxy afin que la détection de la connexion HTTPS et l'adresse IP du client fonctionnent correctement. Autrement dit, pour que Nette\Http\Request::getRemoteAddress() et isSecured() renvoient les bonnes valeurs et que les liens soient générés avec le protocole https: dans les templates.

http:
	# adresse IP, plage (par exemple 127.0.0.1/8), ou tableau de ces valeurs
	proxy: 127.0.0.1       # (string|string[]) non défini par défaut

Forcer HTTPS

Force sans condition le schéma de la requête en HTTPS. C'est utile pour les sites uniquement HTTPS qui tournent derrière un répartiteur de charge ou un reverse proxy terminant le TLS mais ne transmettant pas l'en-tête X-Forwarded-Proto, si bien que la détection HTTPS standard (même avec un Proxy HTTP configuré) ne le remarquerait pas.

http:
	# force le schéma HTTPS pour toutes les requêtes
	forceHttps: true       # (bool) false par défaut

Session

Réglages de base des sessions :

session:
	# afficher le panneau de session dans la Tracy Bar ?
	debugger: ...        # (bool) false par défaut

	# durée d'inactivité au bout de laquelle la session expire
	expiration: 14 days  # (string) '3 hours' par défaut

	# quand la session doit-elle démarrer ?
	autoStart: ...       # (smart|always|never) 'smart' par défaut

	# handler, un service implémentant SessionHandlerInterface
	handler: @handlerService

L'option autoStart détermine quand la session doit démarrer. La valeur always signifie que la session démarre dès que l'application démarre. La valeur smart signifie que la session ne démarre avec l'application que si elle existe déjà, ou au moment où nous voulons y lire ou y écrire. Enfin, la valeur never désactive le démarrage automatique de la session.

Vous pouvez en outre définir toutes les directives de session de PHP (au format camelCase) ainsi que readAndClose. Exemple :

session:
	# 'session.name' s'écrit 'name'
	name: MYID

	# 'session.save_path' s'écrit 'savePath'
	savePath: "%tempDir%/sessions"

Le cookie de session est envoyé avec les mêmes paramètres que les autres cookies, mais vous pouvez les changer spécialement pour lui :

session:
	# domaines qui peuvent recevoir le cookie
	cookieDomain: 'example.com'   # (string|domain)

	# restriction pour l'accès cross-origin
	cookieSamesite: None          # (Strict|Lax|None) Lax par défaut

L'attribut cookieSamesite détermine si le cookie est envoyé lors des requêtes cross-origin, ce qui offre une certaine protection contre les attaques Cross-Site Request Forgery (CSRF).

Services DI

Ces services sont ajoutés au conteneur DI :

Nom Type Description
http.request Nette\Http\Request requête HTTP
http.response Nette\Http\Response réponse HTTP
session.session Nette\Http\Session gestion des sessions
http.requestFactory Nette\Http\RequestFactory factory qui crée la requête HTTP