Konfigurace

Nastavení aplikace má v Nette na starosti třída Configurator. Ovlivňujeme ho zejména pomocí jednoho nebo více konfiguračních NEON soborů.

Konfigurátor

K nastavení aplikace nám poslouží třída Configurator, kterou použijeme v zaváděcím souboru bootstrap.php umístěném ve složce app/.

Vývojářský režim

Vývojářský režim je automaticky aktivní, pokud vyvíjíme na localhostu. Chceme-li ho povolit i mimo něj, 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 adres

Ještě bezpečnější je kombinace IP adresy a cookie. Do cookie tracy-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é zcela vypnout:

$configurator->setDebugMode(FALSE);

Zapnutí Tracy

Pro snadné debugování ještě zapneme Tracy a chyby necháme logovat do uvedeného adresáře:

$configurator->enableTracy(__DIR__ . '/../log');

Cachování konfigurace

Konfigurace se načte a zpracuje jen jednou a výsledek se uloží do cache, což zásadním způsobem aplikaci zrychluje. Proto nejprve nastavíme cestu setTempDirectory(), kam se bude cache ukládat.

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

RobotLoader

Zpravidla budeme chtít automaticky načítat zdrojové soubory aplikace pomocí RobotLoaderu, musíme ho tedy nastartovat.

$configurator->createRobotLoader()
    ->addDirectory(__DIR__)
    ->register();

Alternativní přístup je, nechat vše načítat přes Composer.

Přidání konfiguračního souboru

Nyní už stačí jen uvést cestu ke konfiguračnímu souboru, který se nachází ve složce app/config, pomocí `addConfig():

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

Pokud chceme přidat více nezávislých souborů, můžeme funkci addConfig() zavolat vícekrát.

Přidání parametrů

Parametry do naší aplikace můžeme dostat i přes metodu addParameters().

$configurator->addParameters([
    'foo' => 'bar',
    'baz' => '%tempDir%',
]);

To se velmi hodí, pokud potřebujeme předat environmentální parametry.

$configurator->addParameters([
    'env' => $_ENV,
]);

Konfigurační soubor

Samotná konfigurace se obykle zapisuje v NEON souboru. Se syntaxí se můžete seznámit na stránce http://ne-on.org. V souboru můžeme nastavit

• sessions
• aplikaci
• databázi
• debugger
• routování
• security
• maily
• formuláře
• šablony
• vlastní služby
• Dependency Injection
• vlastní parametry

Sessions

Lze nastavovat všechny PHP direktivy (ve formátu camelCase).

session:
    autoStart: true  # výchozí je smart
    expiration: 10 days
    name: ...
    ...

Doporučuje se používat autoStart: smart, protože pak automaticky startuje session, pouze pokud je již vytvořena.

Více o konfiguraci sessions.

Application

application:
    debugger: true # panel do Laděnky
    catchExceptions: ...
    errorPresenter: ...

Routování

routing:
    debugger: true  # panel v Debugger baru
    routes:
            index.php: Dashboard:default
            '<presenter>/<action>[/<id>]': Dashboard:default

Konfigurace rout je zatím experimentální.

HTTP hlavičky

http:
    frames: ... # ovlivňuje hlavičku X-Frame-Options
    headers:
        Content-Security-Policy: default-src 'self' https://maxcdn.bootstrapcdn.com

Framework z bezpečnostních důvodů odesílá hlavičku X-Frame-Options: SAMEORIGIN, která říká, že stránku lze zobrazit uvnitř jiné stránky (v elementu IFRAME) pouze pokud se nachází na stejné doméně. To může být v některých situacích nežádoucí (například pokud vyvíjíte aplikaci pro Facebook), chování lze proto vypnout nastavením položky frames: yes. Můžete ovlivňovat i další odesílané hlavičky nastavením http.headers. V tomto příkladě nastavujeme hlavičku Content-Security-Policy která nám dovolí stahovat externí soubory (img, script apod.) pouze z naší domény, nebo z https://maxcdn.bootstrapcdn.com. Více o hlavičce Content-Security-Policy.

Security

Uvedením pole users vytvoříme SimpleAuthenticator, uvedením polí roles nebo resources vytvoříme autorizátor Nette\Security\Permission.

security:
    debugger: true  # panel v Debugger baru

    users:
        frantisek: tajneheslo

    roles:
        guest:
        member:
        admin: [member]  # admin dědí od membera

    resources:
        file:

Maily

Standardní mailer je SendmailMailer, uvedením smtp aktivujeme SmtpMailer.

mail:
    smtp: true # zapne SmtpMailer místo SendmailMailer
    # nepovinné nastavení
    host: ...
    port: ...
    username: ...
    password: ...
    secure: # povolené hodnoty jsou ssl, tls nebo null
    timeout: ...

Databáze

Můžeme vytvořit více připojení, které uvedeme pod klíčem database. Takto vytvoříme spojení nazvané default.

database:
    default:
        dsn: "sqlite2:%appDir%/models/demo.db"
        user: ...
        password: ...
        options: [PDO::MYSQL_ATTR_COMPRESS = true]
        debugger: false # panel v Debugger baru
        explain: false  # explain dotazů v Debugger baru
        reflection: discovered # nebo static nebo název třídy

Framework tak vytvoří nejen objekt Nette\Database\Context, ale nastavují mu i pomocné objekty jako reflection & cache a ve vývojářském režimu přidá panel do Debugger baru.

V rámci konfiguračního souboru se můžeme ke službě dostat přes autowiring (@Nette\Database\Context), přes název služby (@nette.database.default) nebo si vytvořit alias a ten používat:

services:
    database: @nette.database.default

    authorizator: Auth(@database)

Formuláře

V konfiguračním souboru lze změnit výchozí chybové hlášky.

forms:
    messages:
        EQUAL: 'Please enter %s.'
        FILLED: 'Please complete mandatory field.'
        MIN_LENGTH: 'Please enter a value of at least %d characters.'
        EMAIL: '%label must be valid e-mail'

Šablony Latte

Lze přepínat HTML a XHTML režim šablon a registrovat vlastní Latte makra. Vlastní makra mohou být zaregistrována buď pomocí jména třídy nebo pomocí reference na službu. Jako výchozí je zavolána metoda install, ale to můžete změnit tím, že přidáte dvojtečku a jméno vaší metody.

latte:
    xhtml: yes  # výchozí je no
    macros:
        - App\MyLatteMacros::register  # statická metoda, classname nebo callable
        - @App\MyLatteMacrosFactory    # služba s metodou install
        - @App\MyLatteMacrosFactory::register # služba s metodou register

services:
    - App\MyLatteMacrosFactory

DI

di:
    debugger: true  # aktivuje panel v Debugger baru

Tracy debugger

Lze konfigurovat některé parametry Tracy (dříve Nette\Diagnostics\Debugger) a nastavovat panely do Debugger baru.

tracy:
    email: %webmasterEmail%
    strictMode: TRUE
    editor: ...
    browser: ...
    bar: # panely do Debugger baru
        - Nette\Bridges\DITracy\ContainerPanel # alias DI Container baru
        - IncludePanel
        - XDebugHelper('myIdeKey')
        - MyPanel(@MyService)
    blueScreen: # panely do Laděnky
        - DoctrinePanel::renderException

Low-level úpravy

Máte možnost si jednotlivé služby ještě „doladit“ na nižší úrovni. Příznak alteration je informativní a říká, že jen modifikujeme existující službu. Takto například nahradíme standardní třídy za své:

services:
    mail.mailer:
        factory: MySmtpMailer
        alteration: yes

    application.presenterFactory:
        factory: MyPresenterFactory
        alteration: yes

Vlastní služby

Konfigurační soubor je místem, kam umísťujeme definice vlastních služeb. Slouží k tomu sekce services. Například tato definice služby:

services:
    database: Nette\Database\Connection(%dsn%, %user%, %password%)

# nebo ve dvou řádcích:
    database:
        factory: Nette\Database\Connection(%dsn%, %user%, %password%)

# nebo ve třech řádcích :-)
    database:
        class: Nette\Database\Connection
        arguments: [%dsn%, %user%, %password%]

Setup

services:
    database:
        factory: Nette\Database\Connection(%dsn%, %user%, %password%)
        setup:
            - setCacheStorage(@cacheStorage)

Autowiring umí odkazy na jiné služby doplnit automaticky, takže lze parametry úplně vynechat:

setup:
    - setCacheStorage

Pokud služba cacheStorage neexistuje, můžeme jako parametr uvést výsledek volání funkce:

setup:
    - setCacheStorage( Factory::createStorage() )

# nebo metody jiné služby:
    - setCacheStorage( @factory::createStorage() )

Případně nově vytvořenou třídu:

setup:
    - setCacheStorage( Nette\Caching\Storages\FileStorage(%tempDir%) )

Lze nastavovat i hodnoty proměnných:

substitutions

setup:
    - $substitutions( [db: test] )

Kompletní příklad:

parameters:
    database:
        driver: mysql
        host: localhost
        dbname: test
        user: jim
        password: beam
        substitutions:
            db: test

services:
    database:
        factory: Nette\Database\Connection(
            '%database.driver%:host=%database.host%;dbname=%database.dbname%',
            %database.user%, %database.password%, null,
            Nette\Database\Reflection\DiscoveredReflection()
        )
        setup:
            - setCacheStorage
            - $substitutions( %database.substitutions% )

Anonymní služby

Pojmenování služeb je vhodné hlavně ve chvíli, kdy na ně chceme odkazovat z jiných částí konfiguračního souboru. Pokud na službu již není odkazováno, není ji potřeba pojmenovávat. Pro anonymní služby použijte následující syntax:

services:
    - Simple\Service

    -
        factory: Complex\Service
        setup:
            - setLang(%lang%)

Pokud však budete chtít později odkázat na anonymní službu, budete muset uvést úplný název třídy (rozhraní).

services:
    router: @App\RouterFactory::createRouter

Také je potřeba mít na paměti, že z povahy anonymních služeb nelze mít registrovaných více instancí stejného typu, protože by nebylo možné je rozlišit.

Auto-wiring

Auto-wiring umí automaticky předávat do konstruktoru a dalších metod požadované služby. Řídí se podle type hintů a anotací @return. Služba odpovídající hledané třídě musí být v kontejneru právě jedna, jinak se vyhodí výjimka.

Pokud potřebujeme definovat více služeb stejného typu, můžeme je z auto-wiringu vyřadit:

services:
    cacheStorage:
        factory: Nette\Caching\Storages\FileStorage(%tempDir%)

    tempCacheStorage:
        factory: Nette\Caching\Storages\DevNullStorage
        autowired: no

Pokud upravujeme základní služby Nette Frameworku, nesmíme se zapomenout ujistit, že kontejner zná třídy naší implementace. Pokud tedy nastavujeme vlastní factory pro službu, tak to znamená mít správně absolutní název třídy v annotaci @return, nebo nastavovat vždy i třídu do class.

Více konfiguračních souborů

V případě, že chceme pro nastavení používat více propojených konfiguračních souborů, můžeme je uvést v sekci includes.

includes:
    - parameters.php
    - services.neon
    - presenters.neon

Konfigurace se slučují tak, že nejvyšší prioritu má soubor obsahující sekci includes a nejnižší první vkládaný soubor. Slučování polí lze zabránit uvedením vykřičníku za název pole:

Sloučením nasledujících dvou polí items vznikne pole s hodnotami 1, 2 a 3.

# config1.neon
items:
    - 1
    - 2

# config2.neon
items:
    - 3

S použítím vykřičníku bude v poli items pouze hodnota 5.

items!:
    - 5