Framework Configuration

An overview of all configuration options in Nette Framework.

Nette application is easily configured using configuration files. They are usually written in NEON format. Have fun trying out the syntax.

Access Control

By filling in users option you create SimpleAuthenticator, by defining roles or resources you create Nette\Security\Permission authorizator. More in User Authorization and Privileges.

security:
    debugger: true  # debugger bar panel

    users:
        johndoe: secretpassword

    roles:
        guest:
        member:
        admin: [member]  # admin extends member

    resources:
        file:

Application

Errors

The errorPresenter specifies the presenter which is invoked when an error occurs. We can find an example in the sandbox.

Parameter catchExceptions decides if the error presenter will be invoked. By changing this value to true in the debug mode we can test functionality of the error presenter.

application:
    debugger: true # shows panel in Tracy bar
    errorPresenter:  ...  # default: Nette:Error
    catchExceptions: ...  # default: enabled in production mode
    silentLinks: ...      # default: false

Option silentLinks specifies Nette behaviour in the debug mode when a link generation fails. With false value Nette will trigger E_USER_WARNING. Changing this configuration option to true will suppress this error. In production environment, E_USER_WARNING will be always triggered. We can also adjust this behaviour using class property Presenter::$invalidLinkMode.

Mapping

Default value: *: *Module\*Presenter (in the Sandbox change to *: App\*Module\Presenters\*Presenter)

This parameter contains an array with rules for converting presenter name to the class name. In the key we define a module name or * as a fallback for other modules. The value contains the rule mask:

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

The presenter Front:Blog:Article is contained inside the Front module. Since this module has no explicit mapping, the mapping with asterisk will be used and the class will be called App\FrontModule\BlogModule\Presenters\ArticlePresenter. The presenter Admin:User:Edit is part of the Admin module which has separate mapping so the name of the presenter class will be App\Admin\UserModule\EditPresenter (note that since the Admin is already in the mapping definition, it will be stripped from the resulting class name).

Automatic registration of presenters

Nette automatically registers presenters as services. This step improves presenter creation speed. There are few configuration options that adjust where and how Nette looks for them.

The scanComposer specifies if Nette should look for presenters in the Composer classmap. The scanFilter specifies the string which must be included in the file and class name.

Value scanDir contains an array with directories where Nette looks for the presenters. If we specify another value in the configuration, it will be merged with the default one %appDir%:

application:
    scanComposer: false  # default: true
    scanFilter: Page  # default: Presenter
    scanDirs:
        - foo

In this case scanDirs will contain values %appDir% and foo. If we want to disable or overwrite this configuration option, we need to use ! modifier:

application:
    scanDirs!:
        - foo

Now scanDirs will contain only foo.

Database

Mandatory item is only dsn:

database:
        dsn: "sqlite2:%appDir%/models/demo.db"

The Framework creates not only the Nette\Database\Connection object, but also sets the auxiliary objects as a reflection & cache and adds a panel to the Tracy bar in the developer mode.

Other settings are as follows:

database:
    dsn: 'mysql:host=127.0.0.1;dbname=test'
    user: root
    password: password
    options:
        PDO::MYSQL_ATTR_COMPRESS: true
        lazy: true  # establish a connection when it is needed for the first time
        driverClass:  .... # class database driver
    debugger: true         # show panel in Tracy baru
    explain:  true         # show query explains in Tracy bar
    autowired: true # enabled for first defined connection
    conventions: discovered # or 'static' or class name, the default is 'discovered'

In the options option, you can specify additional values ​​found in the PDO drivers documentation.

In the configuration file, we can define more than one database connection:

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

    anotherDb:
        dsn: 'sqlite::memory:'

Each connection defined in this way creates two services – the Nette\Database\Connection object named as database.[NAME].connection (in our case, database.main.connection and database.anotherDb.connection) and the Nette\Database\Context object named as database.[NAME].context that is used when working with the Database Explorer layer.

First connection services are passed through autowiring, however we can turn it off by autowired: false, and turn on for another connection via autowired: true.

Other non-autowired connections can be passed explicitly in the configuration:

services:
    - UserManager(@database.anotherDb.connection) # or @database.anotherDb.context

DI Container

di:
    debugger: false  # disables DI panel

Forms

You can change default validation error messages.

forms:
    messages:
        PROTECTION: 'Your session has expired. Please return to the home page and try again.'
        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 or PNG.'

HTTP Headers

http:
    frames: ...                   # header X-Frame-Options

    headers:
        X-Powered-By: MyCMS       # sends custom HTTP header

    csp:                          # Content Security Policy
        script-src: [
            nonce                 # for browsers that support CSP2
            self, unsafe-inline   # for browsers that support CSP1
        ]

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

For security reasons Nette Framework sends HTTP header X-Frame-Options: SAMEORIGIN by default, so that the page can be embedded in iframe only from pages on the same domain. This behavior may be unwanted in certain situations (for example if you are developing a facebook application). You can override this setting by frames: true, frames: http://allowed-host.com or frames: false.

In example, we set Content-Security-Policy & Content-Security-Policy-Report-Only headers. For more informations see CSP documentation.

HTTP Proxies

You can define your HTTP proxy, so that HTTP request's remote address and remote host will be correct.

http:
    proxy: 127.0.0.1  # IP address, range, hostname or array of these values

Latte

You can turn on and off XHTML rendering mode and register custom Latte macros. Custom macros may be passed either as a class name or as a service reference. The default called method is install, you may change it by appending a double colon and a custom method name.

latte:
    xhtml: true  # default is no
    macros:
        - App\MyLatteMacros::register         # static method, classname or callable
        - @App\MyLatteMacrosFactory           # service with install method
        - @App\MyLatteMacrosFactory::register # service with register method

    templateClass: App\MyTemplateClass        # default is Nette\Bridges\ApplicationLatte\Template

services:
    - App\MyLatteMacrosFactory

Mailing

Default mailer is SendmailMailer. By setting smtp you activate SmtpMailer.

mail:
    smtp: true  # use SmtpMailer instead of SendmailMailer
    # optional settings
    host: ...
    port: ...
    username: ...
    password: ...
    secure: # possible values are ssl, tls or null
    timeout: ...

Routing

Routes are typically defined in RouterFactory, such class can be found in a sandbox. However, we can also define them in the configuration file:

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

Other settings:

routing:
    debugger: false  # turns off the panel in the Debugger bar
    cache: true  # serializes the router into the DI container

Session

By default session will expire in a moment when a browser window is closed. Change the expiration time as follows:

session:
    expiration: 14 days

Automatic session start:

session:
    autoStart: true # výchozí hodnota je 'smart'

Default autoStart: smart is recommended. It automatically starts the session only if it already exists.

If you're using a shared hosting, it's suitable to use a custom directory for storing files with session relations:

session:
    savePath: "%tempDir%/sessions"

In this case, %tempDir% will be replaced by value you set in $configurator->setTempDirectory() in bootstrap.php.

If you want to extend the validity of a session (or authentication) for subdomains, let's set just another cookie parameters:

session:
    cookieDomain: 'example.com'

If you want to show session data in Debug bar:

session:
    debugger: true

You can set all PHP directives (in camelCase format).

Tracy Debugger

You can configure some Tracy parameters and set up panels in the Debugger bar.

tracy:
    # if error has occurred the notification is send to this email
    email: dev@example.com
    fromEmail: robot@example.com

    # for sending emails, it uses a mailer defined in the configuration. Since Tracy version 2.5.
    netteMailer: true

    # In Development mode, you will see notice or error warnings as BlueScreen
    strictMode: true

    # displays silent (@) error messages
    scream: true

    # link format to open in the editor
    editor: editor: // open /? file =% file & line =% line

    # path to a browser that will automatically open the logged BlueScreen in CLI mode
    browser: ...

    # for which error levels (E_WARNING, E_ALL, ...) BlueScreen is logged
    logSeverity:

    # path to template with custom page for error 500
    errorTemplate: ...

    # displays the Debugger Bar at the bottom of the page
    showBar: true

    # maximum string length of dump()
    maxLength: 150

    # how deep will list the dump()
    maxDepth: 3

    # displays the location where dump () was called
    showLocation: false

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

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

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

Low-level Modifications

All these settings affect the contents of the DI container and the system services it creates. All these services can still be changed to a low-level. For instance, we can change class of service application.application, which is by default Nette\Application\Application:

services:
    application.application:
        factory: MyApplication
        alteration: true

The alteration flag is informative and says we only modify an existing service.

We can also add setup:

services:
    application.application:
        factory: MyApplication
        alteration: true
        setup:
            - $onStartup = [@resource::init]

You can also remove the service from the container:

services:
    cache.journal: false

Services

The configuration file is place where we add definitions of our own services in section services. See the DI: Services Configuration chapter for a detailed description.

For example, this is definition of service named database which is PDO instance:

services:
    database: PDO('mysql:host=127.0.0.1;dbname=test', root, password)

More extensions

Using extensions, the configuration file can be enhanced by additional sections through which we can configure additional components or modify the DI container.

extensions:
    dibi: Dibi\Bridges\Nette\DibiExtension22

dibi:
    host: localhost

Nette has a several extensions, e.g. PhpExtension, DecoratorExtension, InjectExtension, you can learn more about them in DI: Built-in Container Extensions.