Konfigurace frameworku

Přehled všech konfiguračních voleb v Nette Frameworku.

Nette umožňuje nastavovat aplikaci pomocí konfiguračních souborů. Ty se obykle zapisují ve formátu NEON. Vyzkoušejte si si jeho syntaxi.

Přístupová oprávnění

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:

Application

Chyby

errorPresenter říká, jaký presenter se má zavolat, dojde-li v naší aplikaci k chybě. Jak takový presenter může vypadat, najdeme v sandboxu.

Parametr catchExceptions ovlivňuje, zda dojde k zavolání error presenteru. Změnou hodnoty na true můžeme v debug módu ověřit správnou funkčnost error presenteru.

application:
    debugger: true # panel do Tracy
    errorPresenter:  ...  # default: Nette:Error
    catchExceptions: ...  # default: zapnuto v produkčním režimu
    silentLinks: ...      # default: false

Volba silentLinks určuje, jak se Nette zachová v debug módu při tom, když se nepodaří vygenerovat odkaz. Defautlní hodnota false znamená, že Nette vyhodí E_USER_WARNING chybu. Nastavením na true dojde k potlačení této chybové hlášky. V produkčním prostředí se E_USER_WARNING vyvolá vždy. Toto chování můžeme také ovlivnit nastavením třídní proměnné Presenteru::$invalidLinkMode.

Mapování

Defaultní hodnota: *: *Module\*Presenter (v Sandboxu je pak upravená na *: App\*Module\Presenters\*Presenter)

Tento parametr obsahuje pole s pravidly pro přepis názvu presenteru na název třídy. Klíč v poli obsahuje název modulu, pro který se má toto pravidlo uplatnit, nebo * jako fallback pro ostatní moduly. Hodnota pak obsahuje masku pravidla:

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

Presenter Front:Blog:Article je obsažen v modulu Front, pro ten nemáme žádný vlastní mapping, použije se tedy obecný s hvezdičkou a výsledná třída bude App\FrontModule\BlogModule\Presenters\ArticlePresenter. Presenter Admin:User:Edit se nachází v modulu Admin, pro které zde máme oddělený mapping. Výsledný název třídy bude App\Admin\UserModule\EditPresenter (všimněte si, že jelikož je modul Admin již uveden v pravidlech mappingu, ve výsledném názvu třídy bude zahozen).

Automatická registrace presenterů

Nette automaticky registruje presentery jako služby, což poté zrychlí jejich vytváření. Je zde několik konfiguračních možností, které určují, kde a jak bude Nette tyto presentery hledat.

Parametr scanComposer určuje, zde má Nette hledat presentery v Composer classmap. scanFilter říká, jaký řetězec musí obsahovat třída a název souboru, který bude automaticky registrován.

Hodnota scanDirs udává, v jakých adresářích má Nette hledat presentery pomocí RobotLoaderu. Pokud zapíšeme do konfigurace nějakou hodnotu, bude spojená s tou defaultní, což je %appDir%:

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

scanDirs pak bude obsahovat hodnoty %appDir% a foo, pokud bychom chtěli skenování adresářů vypnout nebo zcela přepsat, musíme použít modifkátor !, který hodnotu přepíše:

application:
    scanDirs!:
        - foo

scanDirs bude nyní obsahovat pouze hodnotu foo.

Databáze

Povinný prvek je pouze dsn:

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

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

Další nastavení jsou tyto:

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

    options:
        PDO::MYSQL_ATTR_COMPRESS: true
        lazy: true  # navázání připojení až když je poprvé potřeba
        driverClass: .... # třída ovladače databáze

    debugger: true        # zobrazí panel v Tracy baru
    explain:  true        # explain dotazů v Tracy bar
    autowired: true       # povoleno u prvního spojení
    conventions:  discovered # nebo 'static' nebo jméno třídy, výchozí je 'discovered'

V položce options můžete uvádět další hodnoty, které najdete v dokumentaci ovladačů PDO.

V konfiguračním souboru můžeme definovat i více než jedno databázové spojení:

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

    anotherDb:
        dsn: 'sqlite::memory:'

Každé takto definované spojení vytvoří dvě služby – objekt Nette\Database\Connection pod názvem database.[NAME].connection (tedy v našem případě database.main.connection a database.anotherDb.connection) a objekt Nette\Database\Context pod názvem database.[NAME].context, který se používá při práci s vrstvou Database Explorer.

Služby prvního spojení se předávají přes autowiring, nicméně můžeme to vypnout skrze autowired: false a naopak u jiného spojení zapnout přes autowired: true.

Služby ostatních spojení, která nejsou autowirovaná, lze předat explicitně v konfiguraci:

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

DI kontejner

di:
    debugger: false  # vypne DI panel v Debugger baru

Formuláře

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

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 hlavičky

http:
    frames: ... # ovlivňuje hlavičku X-Frame-Options

    headers:
        X-Powered-By: MyCMS       # odešle vlastní HTTP hlavičku

    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 (od nette/http 2.4.10)
        default-src: self
        report-uri: 'https://my-report-uri-endpoint'

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: true.

V příkladě nastavujeme hlavičky Content-Security-Policy & Content-Security-Policy-Report-Only. Více informací najdete v dokumentaci CSP.

HTTP proxy

Můžete zadat HTTP proxy, aby detekce IP adresy klienta fungovala správně.

http:
    proxy: 127.0.0.1  # IP adresa, rozsah, název hostitele nebo pole těchto hodnot

Šablony Latte

Lze přepínat HTML a XHTML režim šablon a registrovat vlastní Latte značky. Vlastní značky mohou být zaregistrovány 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: true  # 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

    templateClass: App\MyTemplateClass        # výchozí je Nette\Bridges\ApplicationLatte\Template

services:
    - App\MyLatteMacrosFactory

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: ...

Routování

Routování obvykle definujeme v RouterFactory, takovou třídu najdeme v sandboxu. Můžeme je však definovat i v konfiguračním souboru:

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

Další nastavení:

routing:
    debugger: false  # vypne panel v Debugger baru
    cache: true  # serializuje router do DI kontejneru

Session

Session standardně vyexpiruje při zavření okna prohlížeče. Dobu expirace nastavíme takto:

session:
    expiration: 14 days

Automatické startování session:

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

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

Na sdílených hostinzích je vhodné zvolit vlastní adresář, kam se mají ukládat soubory s relacemi:

session:
    savePath: "%tempDir%/sessions"

V tomto příkladě se %tempDir% nahradí hodnotou, kterou jste nastavili v $configurator->setTempDirectory() v bootstrap.php.

Pokud chceme platnost session (nebo autentizace) rozšířit na subdomémy, nastavíme ještě parametry cookie:

session:
    cookieDomain: 'example.com'

Pokud chceme zobrazit obsah session v Debugger baru:

session:
    debugger: true

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

Tracy debugger

Lze konfigurovat některé parametry Tracy a nastavovat panely do Debugger baru.

tracy:
    # email, na který se posílají notifikace, že došlo k chybě
    email: dev@example.com
    fromEmail: robot@example.com

    # pro odesílání emailů použije v konfiguraci definovaný mailer. Od verze Tracy 2.5.
    netteMailer: true

    # ve vývojovém režimu zobrazí chyby typu notice nebo warning jako BlueScreen
    strictMode: true

    # zobrazí umlčené (@) chybové hlášky
    scream: true

    # formát odkazu pro otevření v editoru
    editor: editor://open/?file=%file&line=%line

    # cesta k prohlížeči, který bude automaticky otevírat zalogované BlueScreen v CLI režimu
    browser: ...

    # pro jaké úrovně chyb (E_WARNING, E_ALL, ...) se loguje i BlueScreen
    logSeverity:

    # cesta k šabloně s vlastní stránkou pro chybu 500
    errorTemplate: ...

    # zobrazí Debugger Bar na spodu stránky
    showBar: true

    # maximální délka řetězce vypisovaná funkcí dump()
    maxLength: 150

    # do kolika úrovní zanoření má vypisovat funkce dump()
    maxDepth: 3

    # zobrazí místo, kde byla volána funkce dump()
    showLocation: false

    editorMapping:
        # originál: nová
        /var/www/html: /data/web
        /home/web: /srv/html

    # přidá panely do Debugger Baru
    bar:
        - Nette\Bridges\DITracy\ContainerPanel
        - IncludePanel
        - XDebugHelper('myIdeKey')
        - MyPanel(@MyService)

    # přidá panely do BlueScreen
    blueScreen:
        - DoctrinePanel::renderException

Low-level úpravy

Všechny uvedené nastavení ovlivňují podobu DI kontejneru a systémových služeb, které vytváří. Všechny tyto služby lze ještě pozměnit na nižší úrovni. Třeba u služby application.application, což je standardně objekt Nette\Application\Application, můžeme změnit třídu:

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

Příznak alteration je informativní a říká, že jen modifikujeme existující službu.

Můžeme také doplnit setup:

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

Také lze službu z kontejneru odstranit:

services:
    cache.journal: false

Služby

Konfigurační soubor je místem, kam umísťujeme definice vlastních služeb. Slouží k tomu sekce services, podrobný popis najdete v kapitole DI: konfigurace služeb.

Například takto může vypadat definice služby pojmenované database, což bude instance PDO:

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

Další rozšíření

Přes rozšíření lze konfigurační soubor doplňovat o další sekce, přes které můžeme konfigurovat další komponenty nebo upravovat podobu DI kontejneru.

extensions:
    dibi: Dibi\Bridges\Nette\DibiExtension22

dibi:
    host: localhost

Nette obsahuje několik dalších rozšíření, např. PhpExtension, DecoratorExtension, InjectExtension, o kterých se dočtete více v kapitole DI: Základní rozšíření pro kontejner.