Konfigurace
Nette umožňuje nastavovat aplikaci pomocí konfiguračního souboru. Řekneme si:
- jak se konfiguruje pomocí NEON souborů
- jak na produkční a vývojářský režim
- jak vytvořit systémový kontejner
- jak používat a vytvářet rozšíření pro kontejner
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
Nejzákladnějším nastavením je to, které říká, zda aplikace běží v produkčním nebo vývojářském režimu. To
například ovlivňuje Tracy a říká ji, zda chyby zobrazovat nebo logovat. To je potřeba
nastavit ihned při startu, tedy dřív, než se zpracovávají konfigurační soubory, protože musí být jasné i to, zda se
má případná chyba v konfiguračním souboru zobrazit nebo zalogovat. Prostředí nastavíme pomocí
setDebugMode()
a zapneme Tracy enableDebugger()
.
// aktivuje laděnku pouze pro dané ip adresy
$configurator->setDebugMode(array('90.180.45.360', '90.180.45.361'));
// nebo nikomu
$configurator->setDebugMode(FALSE);
$configurator->enableDebugger(__DIR__ . '/../log'); // Do adresáře log/ se bodou ukládat výstupy Laděnky
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();
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.
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\Connection
, 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\Connection
),
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:
latte:
xhtml: no # výchozí je false
DI
di:
debugger: true # aktivuje panel v Debugger baru
Tracy debugger
Lze konfigurovat některé parametry Tracy 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. Takto například nahradíme standardní třídy za své:
services:
mail.mailer:
factory: MySmtpMailer
application.presenterFactory:
factory: MyPresenterFactory
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.
Dědičnost služeb
services:
dev_database < database
setup:
- Diagnostics\ConnectionPanel::initialize
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:
argument!: [1, 2, 3]