Konfigurace

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.

Služby a parametry

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)

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 vykřičník, 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:
		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.'
		Nette\Forms\Controls\SelectBox::VALID: 'Please select a valid option.'
		Nette\Forms\Controls\UploadControl::VALID: 'An error occurred during file upload.'
		Nette\Forms\Controls\CsrfProtection::PROTECTION: 'Your session has expired. Please return to the home page and try again.'

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

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.