Nette Documentation Preview

syntax
How to Load Configuration File
******************************

.[perex]
The individual components of Nette are configured using configuration files. We will show how to load these files.

.[tip]
If you are using the whole framework, there is no need to do anything else. In the project, you have a pre-prepared directory `config/` for the configuration files, and the [application loader|application:bootstrap#DI Container Configuration] is responsible for loading them.
This article is for users who use only one Nette library and want to take advantage of the configuration files.

Configuration files are usually written in [NEON|neon:format] and are best edited in [editors with support for it|best-practices:editors-and-tools#ide-editor]. They can be thought of as instructions on how to **create and configure** objects. Thus, the result of loading a configuration will be a so-called factory, which is an object that will on demand create other objects you want to use. For example, a database connection, etc.

This factory is also called a *dependency injection container* (DI container) and if you are interested in the details, read the chapter on [dependency injection |dependency-injection:].

Loading the configuration and creating the container is handled by the [api:Nette\Bootstrap\Configurator] class, so we'll install its `nette/bootstrap` package first:

```shell
composer require nette/bootstrap
```

And create an instance of the `Configurator` class. Since the generated DI container will be cached to disk, you need to set the path to the directory where it will be saved:

```php
$configurator = new Nette\Bootstrap\Configurator;
$configurator->setTempDirectory(__DIR__ . '/temp');
```

On Linux or macOS, set the [write permissions |nette:troubleshooting#Setting directory permissions] for directory `temp/`.

And we come to the configuration files themselves. These are loaded using `addConfig()`:

```php
$configurator->addConfig(__DIR__ . '/database.neon');
```

If you want to add more configuration files, you can call the `addConfig()` function multiple times. If elements with the same keys appear in the files, they will be overwritten (or [merged |dependency-injection:configuration#Merging] in the case of arrays). A later inserted file has a higher priority than the previous one.

The last step is to create a DI container:

```php
$container = $configurator->createContainer();
```

And it will already create the desired objects for us. For example, if you are using the configuration for [Nette Database|database:configuration], you can ask it to create database connections:

```php
$db = $container->getByType(Nette\Database\Connection::class);
// or
$explorer = $container->getByType(Nette\Database\Explorer::class);
// or when creating multiple connections
$db = $container->getByName('database.main.connection');
```

And now you can work with the database!


Development vs Production Mode
------------------------------

In development mode, the container is automatically updated whenever the configuration files are changed. In production mode, it is generated only once and changes are not checked.
So developer mode is aimed at maximum programmer convenience, production mode is aimed at performance.

Mode selection is done by autodetection, so there is usually no need to configure or manually switch anything. The mode is development when the application is running on a localhost (i.e., IP address `127.0.0.1` or `::1`) and no proxy (i.e., its HTTP header) is present. Otherwise it runs in production mode.

If you want to enable development mode in other cases, such as programmers accessing from a specific IP address, use `setDebugMode()`:

```php
$configurator->setDebugMode('23.75.345.200');
// an array of IP addresses can also be specified
```

We definitely recommend combining the IP address with a cookie. Store a secret token, e.g. `secret1234`, in the `nette-debug` cookie, and this way you enable development mode for programmers accessing from a specific IP address and also having the token mentioned in the cookie:

```php
$configurator->setDebugMode('secret1234@23.75.345.200');
```

You can also disable developer mode altogether, even for localhost:

```php
$configurator->setDebugMode(false);
```


Parameters
----------

You can also use parameters in configuration files, which are defined [in the `parameters` section|dependency-injection:configuration#parameters`].

They can also be inserted from outside using the `addDynamicParameters()` method:

```php
$configurator->addDynamicParameters([
	'remoteIp' => $_SERVER['REMOTE_ADDR'],
]);
```

The `projectId` parameter can be referenced in the configuration with the `%projectId%` notation.


{{leftbar: nette:@menu-topics}}

How to Load Configuration File

The individual components of Nette are configured using configuration files. We will show how to load these files.

If you are using the whole framework, there is no need to do anything else. In the project, you have a pre-prepared directory config/ for the configuration files, and the application loader is responsible for loading them. This article is for users who use only one Nette library and want to take advantage of the configuration files.

Configuration files are usually written in NEON and are best edited in editors with support for it. They can be thought of as instructions on how to create and configure objects. Thus, the result of loading a configuration will be a so-called factory, which is an object that will on demand create other objects you want to use. For example, a database connection, etc.

This factory is also called a dependency injection container (DI container) and if you are interested in the details, read the chapter on dependency injection.

Loading the configuration and creating the container is handled by the Nette\Bootstrap\Configurator class, so we'll install its nette/bootstrap package first:

composer require nette/bootstrap

And create an instance of the Configurator class. Since the generated DI container will be cached to disk, you need to set the path to the directory where it will be saved:

$configurator = new Nette\Bootstrap\Configurator;
$configurator->setTempDirectory(__DIR__ . '/temp');

On Linux or macOS, set the write permissions for directory temp/.

And we come to the configuration files themselves. These are loaded using addConfig():

$configurator->addConfig(__DIR__ . '/database.neon');

If you want to add more configuration files, you can call the addConfig() function multiple times. If elements with the same keys appear in the files, they will be overwritten (or merged in the case of arrays). A later inserted file has a higher priority than the previous one.

The last step is to create a DI container:

$container = $configurator->createContainer();

And it will already create the desired objects for us. For example, if you are using the configuration for Nette Database, you can ask it to create database connections:

$db = $container->getByType(Nette\Database\Connection::class);
// or
$explorer = $container->getByType(Nette\Database\Explorer::class);
// or when creating multiple connections
$db = $container->getByName('database.main.connection');

And now you can work with the database!

Development vs Production Mode

In development mode, the container is automatically updated whenever the configuration files are changed. In production mode, it is generated only once and changes are not checked. So developer mode is aimed at maximum programmer convenience, production mode is aimed at performance.

Mode selection is done by autodetection, so there is usually no need to configure or manually switch anything. The mode is development when the application is running on a localhost (i.e., IP address 127.0.0.1 or ::1) and no proxy (i.e., its HTTP header) is present. Otherwise it runs in production mode.

If you want to enable development mode in other cases, such as programmers accessing from a specific IP address, use setDebugMode():

$configurator->setDebugMode('23.75.345.200');
// an array of IP addresses can also be specified

We definitely recommend combining the IP address with a cookie. Store a secret token, e.g. secret1234, in the nette-debug cookie, and this way you enable development mode for programmers accessing from a specific IP address and also having the token mentioned in the cookie:

$configurator->setDebugMode('secret1234@23.75.345.200');

You can also disable developer mode altogether, even for localhost:

$configurator->setDebugMode(false);

Parameters

You can also use parameters in configuration files, which are defined in the parameters section.

They can also be inserted from outside using the addDynamicParameters() method:

$configurator->addDynamicParameters([
	'remoteIp' => $_SERVER['REMOTE_ADDR'],
]);

The projectId parameter can be referenced in the configuration with the %projectId% notation.