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.

HTTP Proxy

If the site is running behind an HTTP proxy, enter its IP address in order to correctly detect the IP address of the client Nette\Http\Request::getRemoteAddress() and encrypted connection isSecured().

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.3.

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

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