Nette Documentation Preview

syntax
Konfigurace HTTP
****************

.[perex]
Přehled konfiguračních voleb pro Nette HTTP.

Pokud nepoužívate celý framework, ale jen tuto knihovnu, přečtěte si, [jak konfiguraci načíst|bootstrap:].


HTTP hlavičky
=============

```neon
http:
	# hlavičky, které se s každým požadavkem odešlou
	headers:
		X-Powered-By: MyCMS
		X-Content-Type-Options: nosniff
		X-XSS-Protection: '1; mode=block'

	# ovlivňuje hlavičku X-Frame-Options
	frames: ...      # (string|bool) výchozí je 'SAMEORIGIN'
```

Framework z bezpečnostních důvodů odesílá hlavičku `X-Frame-Options: SAMEORIGIN`, která říká, že stránku lze zobrazit uvnitř jiné stránky (v elementu `<iframe>`) pouze pokud se nachází na stejné doméně. To může být v některých situacích nežádoucí (například pokud vyvíjíte aplikaci pro Facebook), chování lze proto změnit nastavením `frames: http://allowed-host.com` nebo `frames: true`.


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

Snadno lze sestavovat hlavičky `Content-Security-Policy` (dále CSP), jejich popis najdete v [popisu CSP |https://content-security-policy.com]. CSP direktivy (jako např. `script-src`) mohou být zapsány buď jako řetězce dle specifikace, nebo jako pole hodnot kvůli lepší čitelnosti. Pak není potřeba kolem klíčových slov, jako třeba `'self'`, psát uvozovky. Nette také automaticky vygeneruje hodnotu `nonce`, takže v hlavičce bude třeba `'nonce-y4PopTLM=='`.

```neon
http:
	# Content Security Policy
	csp:
		# řetězec ve tvaru dle specifikace CSP
		default-src: "'self' https://example.com"

		# pole hodnot
		script-src:
			- nonce
			- strict-dynamic
			- self
			- https://example.com

		# bool v případě přepínačů
		upgrade-insecure-requests: true
		block-all-mixed-content: false
```

V šablonách používejte `<script n:nonce>...</script>` a hodnota nonce se doplní automaticky. Dělat bezpečné weby v Nette je opravdu snadné.

Podobně lze sestavit i hlavičky `Content-Security-Policy-Report-Only` (které lze používat souběžně s CSP) a [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
```


HTTP cookie
-----------

Lze změnit vychozí hodnoty některých parametrů metody [Nette\Http\Response::setCookie()|response#setCookie] a session.

```neon
http:
	# dosah cookie podle cesty
	cookiePath: ...          # (string) výchozí je '/'

	# domény, které přijímají cookie
	cookieDomain: 'example.com'  # (string|domain) výchozí je nenastaveno

	# posílat cookie pouze přes HTTPS?
	cookieSecure: ...        # (bool|auto) výchozí je auto

	# vypne posílání cookie, kterou používá Nette jako ochranu před CSRF
	disableNetteCookie: ...  # (bool) výchozí je false
```

Atribut `cookieDomain` určuje, které domény mohou cookie přijímat. Není-li uveden, cookie přijímá stejná (sub)doména, jako ji nastavila, *ale nikoliv* její subdomény. Pokud je `cookieDomain` zadaný, jsou zahrnuty i subdomény. Proto je uvedení `cookieDomain` méně omezující než vynechání.

Například při `cookieDomain: nette.org` jsou cookies dostupné i na všech subdoménách jako `doc.nette.org`. Téhož lze dosáhnout také pomocí speciální hodnoty `domain`, tedy `cookieDomain: domain`.

Výchozí hodnota `auto` u atributu `cookieSecure` znamená, že pokud web běží na HTTPS, budou se cookies odesílat s příznakem `Secure` a tedy budou dostupné pouze přes HTTPS.


HTTP proxy
----------

Pokud web běží za HTTP proxy, zadejte její IP adresu, aby správně fungovala detekce spojení přes HTTPS a také IP adresy klienta. Tedy aby funkce [Nette\Http\Request::getRemoteAddress()|request#getRemoteAddress] a [isSecured()|request#isSecured] vracely správné hodnoty a v šablonách se generovaly odkazy s `https:` protokolem.

```neon
http:
	# IP adresa, rozsah (např. 127.0.0.1/8) nebo pole těchto hodnot
	proxy: 127.0.0.1       # (string|string[]) výchozí je nenastaveno
```


Session
=======

Základní nastavení [sessions]:

```neon
session:
	# zobrazit session panel v Tracy Bar?
	debugger: ...        # (bool) výchozí je false

	# doba neaktivity po které session vyexpiruje
	expiration: 14 days  # (string) výchozí je '3 hours'

	# kdy se má startovat session?
	autoStart: ...       # (smart|always|never) výchozí je 'smart'

	# handler, služba implementující rozhraní SessionHandlerInterface
	handler: @handlerService
```

Volba `autoStart` řídí, kdy se má startovat session. Hodnota `always` znamená, že se session spustí vždy se spuštěním aplikace. Hodnota `smart` znamená, že session se spustí při startu aplikace pouze tehdy, pokud již existuje, nebo ve chvíli, z ní chceme číst nebo do ní zapisovat. A nakonec hodnota `never` zakazuje automatický start session.

Dále lze nastavovat všechny PHP [session direktivy |https://www.php.net/manual/en/session.configuration.php] (ve formátu camelCase) a také [readAndClose |https://www.php.net/manual/en/function.session-start.php#refsect1-function.session-start-parameters]. Příklad:

```neon
session:
	# 'session.name' zapíšeme jako 'name'
	name: MYID

	# 'session.save_path' zapíšeme jako 'savePath'
	savePath: "%tempDir%/sessions"
```


Session cookie
--------------

Session cookie se odesílá se stejnými parametry jako [jiné cookie|#HTTP cookie], ale tyto můžete pro ni změnit:

```neon
session:
	# domény, které přijímají cookie
	cookieDomain: 'example.com'   # (string|domain)

	# omezení při přístupu z jiné domény
	cookieSamesite: None          # (Strict|Lax|None) výchozí je Lax
```

Atribut `cookieSamesite` ovlivňuje, zda bude cookie odeslaná při [přístupu z jiné domény|nette:glossary#SameSite cookie], což poskytuje určitou ochranu před útoky [Cross-Site Request Forgery |nette:glossary#cross-site-request-forgery-csrf] (CSRF).


Služby DI
=========

Tyto služby se přidávají do DI kontejneru:

| Název           | Typ                        | Popis
|-----------------------------------------------------
| `http.request`	  | [api:Nette\Http\Request]   | [HTTP request| request]
| `http.response`	  | [api:Nette\Http\Response]  | [HTTP response| response]
| `session.session`   | [api:Nette\Http\Session]   | [správa session| sessions]

Konfigurace HTTP

Přehled konfiguračních voleb pro Nette HTTP.

Pokud nepoužívate celý framework, ale jen tuto knihovnu, přečtěte si, jak konfiguraci načíst.

HTTP hlavičky

http:
	# hlavičky, které se s každým požadavkem odešlou
	headers:
		X-Powered-By: MyCMS
		X-Content-Type-Options: nosniff
		X-XSS-Protection: '1; mode=block'

	# ovlivňuje hlavičku X-Frame-Options
	frames: ...      # (string|bool) výchozí je 'SAMEORIGIN'

Framework z bezpečnostních důvodů odesílá hlavičku X-Frame-Options: SAMEORIGIN, která říká, že stránku lze zobrazit uvnitř jiné stránky (v elementu <iframe>) pouze pokud se nachází na stejné doméně. To může být v některých situacích nežádoucí (například pokud vyvíjíte aplikaci pro Facebook), chování lze proto změnit nastavením frames: http://allowed-host.com nebo frames: true.

Content Security Policy

Snadno lze sestavovat hlavičky Content-Security-Policy (dále CSP), jejich popis najdete v popisu CSP. CSP direktivy (jako např. script-src) mohou být zapsány buď jako řetězce dle specifikace, nebo jako pole hodnot kvůli lepší čitelnosti. Pak není potřeba kolem klíčových slov, jako třeba 'self', psát uvozovky. Nette také automaticky vygeneruje hodnotu nonce, takže v hlavičce bude třeba 'nonce-y4PopTLM=='.

http:
	# Content Security Policy
	csp:
		# řetězec ve tvaru dle specifikace CSP
		default-src: "'self' https://example.com"

		# pole hodnot
		script-src:
			- nonce
			- strict-dynamic
			- self
			- https://example.com

		# bool v případě přepínačů
		upgrade-insecure-requests: true
		block-all-mixed-content: false

V šablonách používejte <script n:nonce>...</script> a hodnota nonce se doplní automaticky. Dělat bezpečné weby v Nette je opravdu snadné.

Podobně lze sestavit i hlavičky Content-Security-Policy-Report-Only (které lze používat souběžně s CSP) a 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

Lze změnit vychozí hodnoty některých parametrů metody Nette\Http\Response::setCookie() a session.

http:
	# dosah cookie podle cesty
	cookiePath: ...          # (string) výchozí je '/'

	# domény, které přijímají cookie
	cookieDomain: 'example.com'  # (string|domain) výchozí je nenastaveno

	# posílat cookie pouze přes HTTPS?
	cookieSecure: ...        # (bool|auto) výchozí je auto

	# vypne posílání cookie, kterou používá Nette jako ochranu před CSRF
	disableNetteCookie: ...  # (bool) výchozí je false

Atribut cookieDomain určuje, které domény mohou cookie přijímat. Není-li uveden, cookie přijímá stejná (sub)doména, jako ji nastavila, ale nikoliv její subdomény. Pokud je cookieDomain zadaný, jsou zahrnuty i subdomény. Proto je uvedení cookieDomain méně omezující než vynechání.

Například při cookieDomain: nette.org jsou cookies dostupné i na všech subdoménách jako doc.nette.org. Téhož lze dosáhnout také pomocí speciální hodnoty domain, tedy cookieDomain: domain.

Výchozí hodnota auto u atributu cookieSecure znamená, že pokud web běží na HTTPS, budou se cookies odesílat s příznakem Secure a tedy budou dostupné pouze přes HTTPS.

HTTP proxy

Pokud web běží za HTTP proxy, zadejte její IP adresu, aby správně fungovala detekce spojení přes HTTPS a také IP adresy klienta. Tedy aby funkce Nette\Http\Request::getRemoteAddress() a isSecured() vracely správné hodnoty a v šablonách se generovaly odkazy s https: protokolem.

http:
	# IP adresa, rozsah (např. 127.0.0.1/8) nebo pole těchto hodnot
	proxy: 127.0.0.1       # (string|string[]) výchozí je nenastaveno

Session

Základní nastavení sessions:

session:
	# zobrazit session panel v Tracy Bar?
	debugger: ...        # (bool) výchozí je false

	# doba neaktivity po které session vyexpiruje
	expiration: 14 days  # (string) výchozí je '3 hours'

	# kdy se má startovat session?
	autoStart: ...       # (smart|always|never) výchozí je 'smart'

	# handler, služba implementující rozhraní SessionHandlerInterface
	handler: @handlerService

Volba autoStart řídí, kdy se má startovat session. Hodnota always znamená, že se session spustí vždy se spuštěním aplikace. Hodnota smart znamená, že session se spustí při startu aplikace pouze tehdy, pokud již existuje, nebo ve chvíli, z ní chceme číst nebo do ní zapisovat. A nakonec hodnota never zakazuje automatický start session.

Dále lze nastavovat všechny PHP session direktivy (ve formátu camelCase) a také readAndClose. Příklad:

session:
	# 'session.name' zapíšeme jako 'name'
	name: MYID

	# 'session.save_path' zapíšeme jako 'savePath'
	savePath: "%tempDir%/sessions"

Session cookie se odesílá se stejnými parametry jako jiné cookie, ale tyto můžete pro ni změnit:

session:
	# domény, které přijímají cookie
	cookieDomain: 'example.com'   # (string|domain)

	# omezení při přístupu z jiné domény
	cookieSamesite: None          # (Strict|Lax|None) výchozí je Lax

Atribut cookieSamesite ovlivňuje, zda bude cookie odeslaná při přístupu z jiné domény, což poskytuje určitou ochranu před útoky Cross-Site Request Forgery (CSRF).

Služby DI

Tyto služby se přidávají do DI kontejneru:

Název Typ Popis
http.request Nette\Http\Request HTTP request
http.response Nette\Http\Response HTTP response
session.session Nette\Http\Session správa session