Nette Documentation Preview

syntax
Configuring HTTP
****************

.[perex]
Overview of configuration options for the Nette HTTP.

If you are not using the whole framework, but only this library, read [how to load the configuration|bootstrap:].


HTTP Headers
============

```neon
http:
	# headers that are sent with each request
	headers:
		X-Powered-By: MyCMS
		X-Content-Type-Options: nosniff
		X-XSS-Protection: '1; mode=block'

	# affects header X-Frame-Options
	frames: ...      # (string|bool) defaults to 'SAMEORIGIN'
```

For security reasons, the framework sends a header `X-Frame-Options: SAMEORIGIN`, which says that a page can be displayed inside another page (in element `<iframe>`) only if it is on the same domain. This can be unwanted in certain situations (for example, if you are developing a Facebook application), so the behavior can be changed by setting `frames: http://allowed-host.com` or `frames: true`.


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

Headers `Content-Security-Policy` (hereinafter referred to as CSP) can be easily assembled, their description can be found in [CSP description |https://content-security-policy.com]. CSP directives (such as `script-src`) can be written either as strings according to specification or as arrays of values ​​for better readability. Then there is no need to write quotation marks around keywords such as `'self'`. Nette will also automatically generate a value of `nonce`, so `'nonce-y4PopTLM=='` will be send in the header.

```neon
http:
	# Content Security Policy
	csp:
		# string according to CSP specification
		default-src: "'self' https://example.com"

		# array of values
		script-src:
			- nonce
			- strict-dynamic
			- self
			- https://example.com

		# bool in the case of switches
		upgrade-insecure-requests: true
		block-all-mixed-content: false
```

Use `<script n:nonce>...</script>` in the templates and the nonce value will be filled in automatically. Making secure websites in Nette is really easy.

Similarly, headers `Content-Security-Policy-Report-Only` (which can be used in parallel with CSP) and [Feature Policy |https://developers.google.com/web/updates/2018/06/feature-policy] can be added:

```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
-----------

You can change the default values of some parameters of the [Nette\Http\Response::setCookie() |response#setCookie] and session methods.

```neon
http:
	# cookie scope by path
	cookiePath: ...          # (string) defaults to '/'

	# which hosts are allowed to receive the cookie
	cookieDomain: 'example.com'  # (string|domain) defaults to unset

	# to send cookies only via HTTPS?
	cookieSecure: ...        # (bool|auto) defaults to auto

	# disables the sending of the cookie that Nette uses as protection against CSRF
	disableNetteCookie: ...  # (bool) defaults to false
```

The `cookieDomain` option determines which domains (origins) can accept cookies. If not specified, the cookie is accepted by the same (sub)domain as is set by it, *excluding* their subdomains. If `cookieDomain` is specified, then subdomains are also included. Therefore, specifying `cookieDomain` is less restrictive than omitting.

For example, if `cookieDomain: nette.org` is set, cookie is also available on all subdomains like `doc.nette.org`. This can also be achieved with the special value `domain`, ie `cookieDomain: domain`.

The default value of `cookieSecure` is `auto` which means that if the website is running on HTTPS, cookies will be sent with the `Secure` flag and will therefore only be available via HTTPS.

.[warning]
For version 3.0, only the `cookieSecure` parameter can be configured and its default value is `false`.


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

If the site is running behind an HTTP proxy, enter the IP address of the proxy so that detection of HTTPS connections works correctly, as well as the client IP address. That is, so that [Nette\Http\Request::getRemoteAddress()|request#getRemoteAddress] and [isSecured()|request#isSecured] return the correct values and links are generated with the `https:` protocol in the templates.

```neon
http:
	# IP address, range (ie. 127.0.0.1/8) or array of these values
	proxy: 127.0.0.1       # (string|string[]) defaults to none
```


Session
=======

Basic [sessions] settings:

```neon
session:
	# shows session panel in Tracy Bar?
	debugger: ...        # (bool) defaults to false

	# inactivity time after which the session expires
	expiration: 14 days  # (string) defaults to '3 hours'

	# when to start the session?
	autoStart: ...       # (smart|always|never) defaults to 'smart'

	# handler, service that implements the SessionHandlerInterface interface
	handler: @handlerService
```

The `autoStart` option controls when to start the session. The value `always` means that the session is always started when the application starts. The `smart` value means that the session will be started when the application starts only if it already exists, or at the moment we want to read from or write to it. Finally, the value `never` disables the automatic start of the session. This has been in use since "nette/http 3.1.5":[https://github.com/nette/http/releases/tag/v3.1.5].

You can also set all PHP [session directives |https://www.php.net/manual/en/session.configuration.php] (in camelCase format) and also [readAndClose |https://www.php.net/manual/en/function.session-start.php#refsect1-function.session-start-parameters]. Example:

```neon
session:
	# 'session.name' written as 'name'
	name: MYID

	# 'session.save_path' written as 'savePath'
	savePath: "%tempDir%/sessions"
```


Session Cookie
--------------

The session cookie is sent with the same parameters as [other cookie|#HTTP cookie], but you can change these for it:

```neon
session:
	# which hosts are allowed to receive the cookie
	cookieDomain: 'example.com'   # (string|domain)

	# restrictions when accessing cross-origin request
	cookieSamesite: None          # (Strict|Lax|None) defaults to Lax (not set in version 3.0)
```

The `cookieSamesite` option affects whether the cookie is sent with [cross-origin requests |nette:glossary#SameSite cookie], which provides some protection against [Cross-Site Request Forgery|nette:glossary#cross-site-request-forgery-csrf] attecks.


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

These services are added to the DI container:

| Name            | Type                       | Description
|-----------------------------------------------------
| `http.request`	  | [api:Nette\Http\Request]   | [HTTP request| request]
| `http.response`	  | [api:Nette\Http\Response]  | [HTTP response| response]
| `session.session` |	[api:Nette\Http\Session]   | [session management| sessions]

Configuring HTTP

Overview of configuration options for the Nette HTTP.

If you are not using the whole framework, but only this library, read how to load the configuration.

HTTP Headers

http:
	# headers that are sent with each request
	headers:
		X-Powered-By: MyCMS
		X-Content-Type-Options: nosniff
		X-XSS-Protection: '1; mode=block'

	# affects header X-Frame-Options
	frames: ...      # (string|bool) defaults to 'SAMEORIGIN'

For security reasons, the framework sends a header X-Frame-Options: SAMEORIGIN, which says that a page can be displayed inside another page (in element <iframe>) only if it is on the same domain. This can be unwanted in certain situations (for example, if you are developing a Facebook application), so the behavior can be changed by setting frames: http://allowed-host.com or frames: true.

Content Security Policy

Headers Content-Security-Policy (hereinafter referred to as CSP) can be easily assembled, their description can be found in CSP description. CSP directives (such as script-src) can be written either as strings according to specification or as arrays of values ​​for better readability. Then there is no need to write quotation marks around keywords such as 'self'. Nette will also automatically generate a value of nonce, so 'nonce-y4PopTLM==' will be send in the header.

http:
	# Content Security Policy
	csp:
		# string according to CSP specification
		default-src: "'self' https://example.com"

		# array of values
		script-src:
			- nonce
			- strict-dynamic
			- self
			- https://example.com

		# bool in the case of switches
		upgrade-insecure-requests: true
		block-all-mixed-content: false

Use <script n:nonce>...</script> in the templates and the nonce value will be filled in automatically. Making secure websites in Nette is really easy.

Similarly, headers Content-Security-Policy-Report-Only (which can be used in parallel with CSP) and Feature Policy can be added:

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

You can change the default values of some parameters of the Nette\Http\Response::setCookie() and session methods.

http:
	# cookie scope by path
	cookiePath: ...          # (string) defaults to '/'

	# which hosts are allowed to receive the cookie
	cookieDomain: 'example.com'  # (string|domain) defaults to unset

	# to send cookies only via HTTPS?
	cookieSecure: ...        # (bool|auto) defaults to auto

	# disables the sending of the cookie that Nette uses as protection against CSRF
	disableNetteCookie: ...  # (bool) defaults to false

The cookieDomain option determines which domains (origins) can accept cookies. If not specified, the cookie is accepted by the same (sub)domain as is set by it, excluding their subdomains. If cookieDomain is specified, then subdomains are also included. Therefore, specifying cookieDomain is less restrictive than omitting.

For example, if cookieDomain: nette.org is set, cookie is also available on all subdomains like doc.nette.org. This can also be achieved with the special value domain, ie cookieDomain: domain.

The default value of cookieSecure is auto which means that if the website is running on HTTPS, cookies will be sent with the Secure flag and will therefore only be available via HTTPS.

For version 3.0, only the cookieSecure parameter can be configured and its default value is false.

HTTP Proxy

If the site is running behind an HTTP proxy, enter the IP address of the proxy so that detection of HTTPS connections works correctly, as well as the client IP address. That is, so that Nette\Http\Request::getRemoteAddress() and isSecured() return the correct values and links are generated with the https: protocol in the templates.

http:
	# IP address, range (ie. 127.0.0.1/8) or array of these values
	proxy: 127.0.0.1       # (string|string[]) defaults to none

Session

Basic sessions settings:

session:
	# shows session panel in Tracy Bar?
	debugger: ...        # (bool) defaults to false

	# inactivity time after which the session expires
	expiration: 14 days  # (string) defaults to '3 hours'

	# when to start the session?
	autoStart: ...       # (smart|always|never) defaults to 'smart'

	# handler, service that implements the SessionHandlerInterface interface
	handler: @handlerService

The autoStart option controls when to start the session. The value always means that the session is always started when the application starts. The smart value means that the session will be started when the application starts only if it already exists, or at the moment we want to read from or write to it. Finally, the value never disables the automatic start of the session. This has been in use since nette/http 3.1.5.

You can also set all PHP session directives (in camelCase format) and also readAndClose. Example:

session:
	# 'session.name' written as 'name'
	name: MYID

	# 'session.save_path' written as 'savePath'
	savePath: "%tempDir%/sessions"

The session cookie is sent with the same parameters as other cookie, but you can change these for it:

session:
	# which hosts are allowed to receive the cookie
	cookieDomain: 'example.com'   # (string|domain)

	# restrictions when accessing cross-origin request
	cookieSamesite: None          # (Strict|Lax|None) defaults to Lax (not set in version 3.0)

The cookieSamesite option affects whether the cookie is sent with cross-origin requests, which provides some protection against Cross-Site Request Forgery attecks.

DI Services

These services are added to the DI container:

Name Type Description
http.request Nette\Http\Request HTTP request
http.response Nette\Http\Response HTTP response
session.session Nette\Http\Session session management