Nette Documentation Preview

syntax
Jak načíst konfigurační soubor
******************************

.[perex]
Jednotlivé součásti Nette nastavujeme pomocí konfiguračních souborů. Ukážeme si, jak tyto soubory načítat.

.[tip]
Pokud používate celý framework, není potřeba nic dalšího dělat. V projektu máte pro konfigurační soubory předpřipravený adresář `config/` a jejich načítání má na starosti [zavaděč aplikace|/application/bootstrap#konfigurace-di-kontejneru].
Tento článek je pro uživatele, kteří používají jen jednu knihovnu Nette a chtějí využít možnosti konfiguračních souborů.

Konfigurační soubory se obvykle zapisují ve [formátu NEON|/neon/format] a nejlépe se upravují v [editorech s jeho podporou|editors-and-tools#ide-editor]. Lze je chápat jako návody, jak **vytvářet a konfigurovat** objekty. Tedy výsledkem načtení konfigurace bude tzv. továrna, což je objekt, který nám na požádání vytvoří další objekty, které chceme používat. Například databázové spojení apod.

Této továrně se také říká *dependency injection kontejner* (DI container) a pokud by vás zajímaly podrobnosti, přečtěte si kapitolu o [dependency injection |/dependency-injection/@home].

Načtení konfigurace a vytvoření kontejneru obstará třída [api:Nette\Bootstrap\Configurator], takže si nejprve nainstalujeme její balíček `nette/bootstrap`:

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

A vytvoříme instanci třídy `Configurator`. Protože vygenerovaný DI kontejner se bude kešovat na disk, je nutné nastavit cestu k adresáři, kam se bude ukládat:

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

Na Linuxu nebo macOS nastavte adresáři `temp/` [práva pro zápis |/troubleshooting#Nastavení práv adresářů].

A dostáváme se k samotným konfiguračním souborům. Ty načteme pomocí `addConfig()`:

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

Pokud chceme přidat více konfiguračních souborů, můžeme funkci `addConfig()` zavolat vícekrát. Pokud se v souborech objeví prvky se stejnými klíči, budou přepsány (nebo v případě polí [sloučeny |/dependency-injection/configuration#Slučování]). Později vkládaný soubor má vyšší prioritu než předchozí.

Posledním krokem je vytvoření DI kontejneru:

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

A ten nám už vytvoří požadované objekty. Pokud například používáte konfiguraci pro [Nette Database|/database/configuration], můžete jej požádat o vytvoření databázových spojení:

```php
$db = $container->getByType(Nette\Database\Connection::class);
// nebo
$explorer = $container->getByType(Nette\Database\Connection::class);
// nebo při vytváření více spojení
$db = $container->getByName('database.main.connection');
```

A nyní už můžete s databází pracovat!


Vývojářský vs produkční režim
-----------------------------

Ve vývojářském režimu se kontejner automaticky aktualizuje při každé změně konfiguračních souborů. V produkčním režimu se vygeneruje jen jednou a změny se nekontrolují.
Vývojářský je tedy zaměřen na maximální pohodlí programátora, produkční na výkon a ostré nasazení.

Volba režimu se provádí autodetekcí, takže obvykle není potřeba nic konfigurovat nebo ručně přepínat. Režim je vývojářský tehdy, pokud je aplikace spuštěna na localhostu (tj. IP adresa `127.0.0.1` nebo `::1`) a není přitomna proxy (tj. její HTTP hlavička). Jinak běží v produkčním režimu.

Pokud chceme vývojářský režim povolit i v dalších případech, například programátorům přistupujícím z konkrétní IP adresy, použijeme `setDebugMode()`:

```php
$configurator->setDebugMode('23.75.345.200'); // lze uvést i pole IP adres
```

Rozhodně doporučujeme kombinovat IP adresu s cookie. Do cookie `nette-debug` uložíme tajný token, např. `secret1234`, a tímto způsobem aktivujeme vývojářský režim pro programátory přistupující z konkrétní IP adresy a zároveň mající v cookie zmíněný token:

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

Vývojářský režim můžeme také vypnout úplně, i pro localhost:

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


Parametry
---------

V konfiguračním souborech můžete používat také parametry, které se definují [v sekci `parameters`|/dependency-injection/configuration#parametry].

Lze je také vkládat zvenčí pomocí metody `addDynamicParameters()`:

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

Na parametr `projectId` se lze v konfiguraci odkázat zápisem `%projectId%`.


{{sitename: Best Practices}}

Jak načíst konfigurační soubor

Jednotlivé součásti Nette nastavujeme pomocí konfiguračních souborů. Ukážeme si, jak tyto soubory načítat.

Pokud používate celý framework, není potřeba nic dalšího dělat. V projektu máte pro konfigurační soubory předpřipravený adresář config/ a jejich načítání má na starosti zavaděč aplikace. Tento článek je pro uživatele, kteří používají jen jednu knihovnu Nette a chtějí využít možnosti konfiguračních souborů.

Konfigurační soubory se obvykle zapisují ve formátu NEON a nejlépe se upravují v editorech s jeho podporou. Lze je chápat jako návody, jak vytvářet a konfigurovat objekty. Tedy výsledkem načtení konfigurace bude tzv. továrna, což je objekt, který nám na požádání vytvoří další objekty, které chceme používat. Například databázové spojení apod.

Této továrně se také říká dependency injection kontejner (DI container) a pokud by vás zajímaly podrobnosti, přečtěte si kapitolu o dependency injection.

Načtení konfigurace a vytvoření kontejneru obstará třída Nette\Bootstrap\Configurator, takže si nejprve nainstalujeme její balíček nette/bootstrap:

composer require nette/bootstrap

A vytvoříme instanci třídy Configurator. Protože vygenerovaný DI kontejner se bude kešovat na disk, je nutné nastavit cestu k adresáři, kam se bude ukládat:

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

Na Linuxu nebo macOS nastavte adresáři temp/ práva pro zápis.

A dostáváme se k samotným konfiguračním souborům. Ty načteme pomocí addConfig():

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

Pokud chceme přidat více konfiguračních souborů, můžeme funkci addConfig() zavolat vícekrát. Pokud se v souborech objeví prvky se stejnými klíči, budou přepsány (nebo v případě polí sloučeny). Později vkládaný soubor má vyšší prioritu než předchozí.

Posledním krokem je vytvoření DI kontejneru:

$container = $configurator->createContainer();

A ten nám už vytvoří požadované objekty. Pokud například používáte konfiguraci pro Nette Database, můžete jej požádat o vytvoření databázových spojení:

$db = $container->getByType(Nette\Database\Connection::class);
// nebo
$explorer = $container->getByType(Nette\Database\Connection::class);
// nebo při vytváření více spojení
$db = $container->getByName('database.main.connection');

A nyní už můžete s databází pracovat!

Vývojářský vs produkční režim

Ve vývojářském režimu se kontejner automaticky aktualizuje při každé změně konfiguračních souborů. V produkčním režimu se vygeneruje jen jednou a změny se nekontrolují. Vývojářský je tedy zaměřen na maximální pohodlí programátora, produkční na výkon a ostré nasazení.

Volba režimu se provádí autodetekcí, takže obvykle není potřeba nic konfigurovat nebo ručně přepínat. Režim je vývojářský tehdy, pokud je aplikace spuštěna na localhostu (tj. IP adresa 127.0.0.1 nebo ::1) a není přitomna proxy (tj. její HTTP hlavička). Jinak běží v produkčním režimu.

Pokud chceme vývojářský režim povolit i v dalších případech, například programátorům přistupujícím z konkrétní IP adresy, použijeme setDebugMode():

$configurator->setDebugMode('23.75.345.200'); // lze uvést i pole IP adres

Rozhodně doporučujeme kombinovat IP adresu s cookie. Do cookie nette-debug uložíme tajný token, např. secret1234, a tímto způsobem aktivujeme vývojářský režim pro programátory přistupující z konkrétní IP adresy a zároveň mající v cookie zmíněný token:

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

Vývojářský režim můžeme také vypnout úplně, i pro localhost:

$configurator->setDebugMode(false);

Parametry

V konfiguračním souborech můžete používat také parametry, které se definují v sekci parameters.

Lze je také vkládat zvenčí pomocí metody addDynamicParameters():

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

Na parametr projectId se lze v konfiguraci odkázat zápisem %projectId%.