Nette Configuration

An overview of all configuration options in the Nette Framework.

Nette application is easily configured using configuration files. They are usually written in NEON format. We recommend to use editors with support for this format for editing.

 application: 	Application
 constants: 	Defines PHP constants
 database: 	Database
 decorator: 	Decorator
 di: 			DI Container
 extensions: 	Install additional DI extensions
 forms: 		Forms
 http: 		HTTP Headers
 includes: 		Including files
 latte: 		Latte
 mail: 		Mailing
 parameters: 	Parameters
 php: 			PHP configuration options
 routing: 		Routing
 search: 		Automatic service registration
 security: 	Access Control
 services: 		Services
 session: 		Session
 tracy: 		Tracy Debugger 

If you use a string that starts with @ or has % anywhere in it, you need to escape it by adding another @ or %.

Application

Basic settings for Nette Application.

application:
	# shows "Nette Application" panel in Tracy BlueScreen?
	debugger: ...           # (bool) defaults to true

	# will error-presenter be called on error?
	catchExceptions: ...    # (bool) defaults to true in production mode

	# name of error-presenter
	errorPresenter: Error   # (string) defaults to 'Nette:Error'

	# do bad links generate warnings?
	# has effect only in developer mode
	silentLinks: ...        # (bool) defaults to false

Because error-presenters are not called by default in development mode and the errors are displayed by Tracy, changing the value catchExceptions to true helps to verify that error-presenters works correct during development.

Option silentLinks determines how Nette behaves in developer mode when link generation fails (for example, because there is no presenter, etc). The default value false means that Nette triggers E_USER_WARNING. Setting to true suppresses this error message. In a production environment, E_USER_WARNING is always invoked. We can also influence this behavior by setting the presenter variable $invalidLinkMode.

Mapping

Defines the rules according to which the name of the class (for example App\Presenters\HomepagePresenter) is derived from the name of the presenter (for example Homepage). This the mapping can be achieved with the following configuration:

application:
	mapping:
		*: App\Presenters\*Presenter

The presenter name is replaced with an asterisk and the result is the class name. Easy!

If we divide presenters into modules, we can have our own mapping for each module:

application:
	mapping:
		Front: App\Modules\Front\*Presenter
		Admin: App\Modules\Admin\*Presenter
		Api: App\Api\*Presenter

Now presenter Front:Homepage maps to class `App\Modules\Front\HomepagePresenter and presenter Admin:Dashboard to class App\AdminModule\DashboardPresenter.

It will be more handy to create a general (asterisk) rule that will replace the first two rules and add an extra asterisk just for the module:

application:
	mapping:
		*: App\Modules\*\*Presenter
		Api: App\Api\*Presenter

Again, the presenter Front:Homepage maps to the class `App\Modules\Front\HomepagePresenter.

But what if we use nested modules and have a presenter Admin:User:Edit? In this case, the segment with an asterisk representing the module for each level is simply repeated and the result is class App\Modules\Admin\User\EditPresenter.

An alternative notation is to use an array consisting of three segments instead of a string:

application:
	mapping:
		*: [App\Modules, *, *Presenter]

This entry is equivalent to the original App\Modules\*\*Presenter.

The default value is *: *Module\*Presenter.

Automatic Registration of Presenters

Nette automatically adds presenters as services to the DI container, which significantly speeds up their creation. How Nette finds out presenters can be configured:

application:
	# to look for presenters in Composer class map?
	scanComposer: ...      # (bool) defaults to true

	# a mask that must match the class and file name
	scanFilter: ...        # (string) defaults to '*Presenter'

	# in which directories to look for presenters?
	scanDirs:              # (string[]|false) defaults to '%appDir%'
		- %vendorDir%/mymodule

The directories listed in scanDirs do not override the default value %appDir%, but complement it, so scanDirs will contain both paths %appDir% and %vendorDir%/mymodule. If we want to overwrite the default directory, we use exclamation mark:

application:
	scanDirs!:
		- %vendorDir%/mymodule

Directory scanning can be turned off by setting false. We do not recommend completely suppressing the automatic addition of presenters, otherwise application performance will be reduced.

Constants

Creating PHP constants.

constants:
	FOOBAR: 'baz'

The FOOBAR constant will created after startup.

Database

The configuration for one or more database connections for Nette Database.

database:
	# DSN, only mandatory key
	dsn: "sqlite:%appDir%/Model/demo.db"
	user: ...
	password: ...

It creates services of type Nette\Database\Connection and also Nette\Database\Explorer for the Database Explorer layer. The database connection is usually passed by autowiring, if this is not possible, use the service names @database.default.connection resp. @database.default.context.

Other settings:

database:
	# shows database panel in Tracy Bar?
	debugger: ...     # (bool) defaults to true

	# shows query EXPLAIN in Tracy Bar?
	explain: ...      # (bool) defaults to true

	# to enable autowiring for this connection?
	autowired: ...    # (bool) defaults to true for first connection

	# table conventions: discovered, static, or class name
	conventions: discovered  # (string) defaults to 'discovered'

	options:
		# to connect to the database only when needed?
		lazy: ...     # (bool) defaults to false

		# PHP database driver class
		driverClass:  # (string)

		# you can list the options found in the PDO driver documentation
		PDO::MYSQL_ATTR_COMPRESS: true

		# only MySQL: sets sql_mode
		sqlmode:      # (string)

		# only MySQL: sets SET NAMES
		charset:      # (string) defaults to 'utf8mb4' ('utf8' before v5.5.3)

		# only Oracle and SQLite: date format
		formatDateTime: # (string) defaults to 'U'

In the configuration we can define more database connections by dividing them into named sections:

database:
	main:
		dsn: 'mysql:host=127.0.0.1;dbname=test'
		user: root
		password: password

	another:
		dsn: 'sqlite::memory:'

Each defined connection creates services that includes section name in their name, ie @database.main.connection & @database.main.context and further @database.another.connection & @database.another.context.

Autowiring is enabled only for services from the first section. This can be changed with autowired: false or autowired: true. Non-autowired services are passed by name:

services:
	- UserFacade(@database.another.connection)

Forms

You can change the default form error messages in the configuration.

forms:
	messages:
		EQUAL: 'Please enter %s.'
		NOT_EQUAL: 'This value should not be %s.'
		FILLED: 'This field is required.'
		BLANK: 'This field should be blank.'
		MIN_LENGTH: 'Please enter at least %d characters.'
		MAX_LENGTH: 'Please enter no more than %d characters.'
		LENGTH: 'Please enter a value between %d and %d characters long.'
		EMAIL: 'Please enter a valid email address.'
		URL: 'Please enter a valid URL.'
		INTEGER: 'Please enter a valid integer.'
		FLOAT: 'Please enter a valid number.'
		MIN: 'Please enter a value greater than or equal to %d.'
		MAX: 'Please enter a value less than or equal to %d.'
		RANGE: 'Please enter a value between %d and %d.'
		MAX_FILE_SIZE: 'The size of the uploaded file can be up to %d bytes.'
		MAX_POST_SIZE: 'The uploaded data exceeds the limit of %d bytes.'
		MIME_TYPE: 'The uploaded file is not in the expected format.'
		IMAGE: 'The uploaded file must be image in format JPEG, GIF, PNG or WebP.'
		Nette\Forms\Controls\SelectBox::VALID: 'Please select a valid option.'
		Nette\Forms\Controls\UploadControl::VALID: 'An error occurred during file upload.'
		Nette\Forms\Controls\CsrfProtection::PROTECTION: 'Your session has expired. Please return to the home page and try again.'

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.

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

HTTP cookie

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\Response::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

Latte

This setting globally affects the behavior of Latte in components and presenters.

latte:
	# shows Latte panel in the Tracy Bar for the main template (true) or for all components (all)?
	debugger: ...        # (true|false|'all') defaults to true

	# switches Latte to XHTML mode (deprecated)
	xhtml: ...           # (bool) defaults to false

	# generates templates with declare(strict_types=1)
	strictTypes: ...     # (bool) defaults to false

	# class of $this->template
	templateClass: App\MyTemplateClass # defaults to Nette\Bridges\ApplicationLatte\DefaultTemplate

It is also possible to register new tags either by entering the class name or by referring to the service. Method install() is called by default, but this can be changed by specifying the name of another method:

latte:
	# registration of user Latte tags
	macros:
		- App\MyLatteMacros::register         # static method, classname or callable
		- @App\MyLatteMacrosFactory           # service with install method
		- @App\MyLatteMacrosFactory::register # service with register method

services:
	- App\MyLatteMacrosFactory

Mail

By default, the mailer Nette\Mail\SendmailMailer is used to send emails, which is not further configured. However, we can switch it to Nette\Mail\SmtpMailer:

mail:
	# use SmtpMailer
	smtp: true       # (bool) defaults to false

	host: ...        # (string)
	port: ...        # (int)
	username: ...    # (string)
	password: ...    # (string)
	timeout: ...     # (int)
	secure: ...      # (ssl|tls|null) defaults to null
	clientHost: ...  # (string) defaults to $_SERVER['HTTP_HOST']
	persistent: ...  # (bool) defaults to false

	# context for connecting to the SMTP server, see stream_context_create()
	context:         # (array) defaults to stream_context_get_default()

To increase trustfulness, we can sign emails using DKIM technology:

mail:
	dkim:
		domain: myweb.com
		selector: lovenette
		privateKey: %appDir%/cert/dkim.priv
		passPhrase: ...

PHP

You can set PHP directives. An overview of all directives can be found at php.net.

php:
	date.timezone: Europe/Prague

Routing

Basic settings:

routing:
	# shows routing panel in Tracy Bar?
	debugger: ...   # (bool) defaults to true

	# to serialize router to DI container?
	cache: ...      # (bool) defaults to false

Router is usually defined in the RouterFactory class, a more limited alternative can be defined in the configuration using pairs mask: action:

routing:
	routes:
		'detail/<id>': Admin:Home:default
		'<presenter>/<action>': Front:Home:default

Access Control

You can define a list of users in the configuration to create a simple authenticator (Nette\Security\SimpleAuthenticator). Because passwords are readable in the configuration, this solution is for testing purposes only.

security:
	# shows user panel in Tracy Bar?
	debugger: ...  # (bool) defaults to true

	users:
		# name: password
		johndoe: secret123

		# name, password, role and other data available in the identity
		janedoe:
			password: secret123
			roles: [admin]
			data: ...

You can also define roles and resources to create a basis for authorizer (Nette\Security\Permission):

security:
	roles:
		guest:
		registered: [guest]  # registered inherits from guest
		admin: [registered]  # and admin inherits from registered

	resources:
		article:
		comment: [article]   # resource inherits from article
		poll:

User Storage

You can configure how to store information about the logged in user:

security:
	authentication:
		# after how long of inactivity the user will be logged out
		expiration: 30 minutes        # (string) default is not set

		# where to store information about the logged in user
		storage: session              # (session|cookie) default is session

If you choose cookie as your repository, you can also set the following options:

security:
	authentication:
		# jméno cookie
		cookieName: userId            # (string) výchozí je userid

		# 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

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"

Session Cookie

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.

Tracy Debugger

You can set the Tracy parameters in the configuration and also add new panels to the Tracy Bar. These settings are applied only after the DI container has been created, so errors that occurred earlier cannot reflect them.

Error logging configuration:

tracy:
	# if error has occurred the notification is sent to this email
	email: dev@example.com           # (string|string[]) defaults to unset

	# email sender
	fromEmail: robot@example.com     # (string) defaults to unset

	# period of postponement of emails sending (since Tracy 2.8.8)
	emailSnooze: ...                 # (string) defaults to '2 days'

	# to use a mailer defined in the configuration? (since Tracy 2.5)
	netteMailer: ...                 # (bool) defaults to true

	# for which error levels is BlueScreen also logged?
	logSeverity: [E_WARNING, E_NOTICE]  # defaults to []

Configuration for function dump():

tracy:
	# maximum string length
	maxLength: 150             # (int) default according to Tracy

	# how deep will list
	maxDepth: 10               # (int) default according to Tracy

	# hide values of these keys (since Tracy 2.8)
	keysToHide: [password, pass]  # (string[]) defaults to []

	# visual theme (since Tracy 2.8)
	dumpTheme: dark                # (light|dark) defaults to 'light'

	# displays the location where dump() was called?
	showLocation: ...          # (bool) default according to Tracy

To install the Tracy extension:

tracy:
	# appends bars to Tracy Bar
	bar:
		- Nette\Bridges\DITracy\ContainerPanel
		- IncludePanel
		- XDebugHelper('myIdeKey')
		- MyPanel(@MyService)

	# append panels to BlueScreen
	blueScreen:
		- DoctrinePanel::renderException

Other options:

tracy:
	# in Development mode, you will see notice or error warnings as BlueScreen
	strictMode: ...           # (bool) defaults to true

	# displays silent (@) error messages
	scream: ...               # (bool) defaults to false

	# link format to open in the editor
	editor: ...               # (string) defaults to 'editor://open/?file=%file&line=%line'

	# path to template with custom page for error 500
	errorTemplate: ...        # (string) defaults to unset

	# shows Tracy Bar?
	showBar: ...              # (bool) defaults to true

	editorMapping:
		# original: new
		/var/www/html: /data/web
		/home/web: /srv/html