nette-configuration

Nette DI & Services Guidelines

• Primary services: services.neon – all service definitions
• Framework config: common.neon – parameters, extensions, framework settings, includes
• Project scaling: Create additional files for larger projects (api.neon, tasks.neon)
• Environment-specific settings: env.local.neon for development, env.prod.neon for production

Config File Includes

common.neon includes other files. Later files override earlier ones, so environment-specific files go last:

includes:
	- services.neon
	- env.local.neon   # Gitignored, overrides for local dev

Extensions

Register DI extensions for third-party packages or custom container builders:

extensions:
	console: Contributte\Console\DI\ConsoleExtension
	translation: Contributte\Translation\DI\TranslationExtension

Service Definition Syntax

Use - for services that don't need references. Nette DI automatically resolves all constructor dependencies by type, so most services need just their class name:

services:
	- App\Model\BlogFacade
	- App\Model\CustomerService
	- App\Presentation\Accessory\TemplateFilters

Give names only when needed for @serviceName references elsewhere in NEON. Unnecessary names add clutter and create a maintenance burden when classes are renamed:

services:
	# Named because referenced as @pohoda
	pohoda:
		create: Nette\Database\Connection('odbc:Driver={...}')
		autowired: false

	# Using the reference
	- App\Model\PohodaImporter(pohoda: @pohoda)

When manually specifying parameters, use named parameters if not the first parameter:

services:
	# Good - first parameter, clear order
	- App\Model\ImageService(%rootDir%/storage)

	# Good - named parameter when mixing with autowiring
	- App\Model\CustomerService(ip: %ip%)
	- App\Model\BlogFacade(blogPath: %blog%)

Factory Method Services

services:
	- App\Core\RouterFactory::createRouter
	- Symfony\Component\HttpClient\HttpClient::create()

Complex Service Configuration

services:
	- App\Model\MailImporter(
		DG\Imap\Mailbox(
			mailbox: %imap.mailbox%
			username: %imap.username%
			password: %imap.password%
		)
		debugMode: %debugMode%
	)

Setup Methods

services:
	database:
		create: PDO(%dsn%, %user%, %password%)
		setup:
			- setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION)

Overriding Services by Type

When you need to alter an existing service (e.g. replace a framework service with your own implementation), you can refer to it by type using @ClassName: instead of guessing internal service names. The alteration: true is implicit:

services:
	# Override the framework's Application with a custom one
	@Nette\Application\Application:
		create: MyApplication

Disabled Autowiring

Use autowired: false when you have multiple services of the same type and need to prevent ambiguity (e.g. two database connections):

services:
	specialDb:
		create: Nette\Database\Connection(...)
		autowired: false  # Must reference explicitly via @specialDb

Automatic Service Registration

Use search section to avoid manually registering services that follow naming conventions. This keeps services.neon short and ensures new services are picked up automatically:

search:
	model:
		in: %appDir%
		classes:          # Classes ending with Factory, Facade, or Service
			- *Factory
			- *Facade
			- *Service

Generated Factories and Accessors

Instead of injecting the container or writing factory boilerplate, declare an interface and let DI generate the implementation. The interface must have exactly one method named create with a declared return type:

interface ArticleFactory
{
	function create(int $authorId): Article;
}

services:
	- ArticleFactory        # short form: implement: is inferred from the interface

Parameters of create() are matched to the constructor by name, so $authorId above lands in Article::__construct(int $authorId). The long form adds fixed arguments or setup:

services:
	articleFactory:
		implement: ArticleFactory
		arguments:
			authorId: 123        # create() does not take it, the constructor does
		setup:
			- setAuthorId($authorId)   # create() takes it, a setter consumes it

An accessor is the lazy variant – one get() method returning an existing service, so the service is only created on first get():

interface DatabaseAccessor
{
	function get(): Database;
}

This is the mechanism behind component factories in presenters, so use it instead of passing the container around.

Decorator Section

Apply configuration to all services of a specific type without listing them individually. Useful for injecting common dependencies or calling setup methods on multiple services:

decorator:
	App\Presentation\BasePresenter:
		setup:
			- setTranslator

Parameter Usage

Reference configuration parameters with %parameterName%. Parameters are defined in the parameters section of common.neon and can be overridden per environment:

services:
	- App\Model\TexyProcessor('', %wwwDir%, %tempDir%/texy)
	- App\Tasks\ImportTask(path: %rootDir%/../data/import)
	- App\Model\CustomerService(ip: %ip%)

Passing Settings to Services and Presenters

Via service arguments (recommended) – explicit, type-safe, visible in constructor:

# config/services.neon
services:
	- App\Presentation\Admin\Product\ProductPresenter(itemsPerPage: 20)

class ProductPresenter extends BasePresenter
{
	public function __construct(
		private int $itemsPerPage,
		private ProductFacade $facade,
	) {}
}

Via parameters – useful when the same value is used in multiple places:

# config/common.neon
parameters:
	pagination:
		itemsPerPage: 20
		maxItems: 1000

# config/services.neon
services:
	- App\Presentation\Admin\Product\ProductPresenter(
		itemsPerPage: %pagination.itemsPerPage%
	)

Core Framework Configuration

Add sections to common.neon only when you need specific functionality.

Application Layer

Add when: Setting up error handling or custom URL mapping

application:
	mapping: App\Presentation\*\**Presenter
	errorPresenter:
		4xx: Error:Error4xx     # When you have custom error pages
		5xx: Error:Error5xx
	aliases:                    # When you have frequently used links in n:href or $presenter->link()
		home: 'Front:Home:'
		admin: 'Admin:Dashboard:'

HTTP and Session

Add when: You need custom cookie settings, proxy support, or session configuration

http:
	proxy: 10.0.0.0/8      # When behind a reverse proxy

session:
	expiration: 14 days
	cookieSamesite: Lax

Authentication

Add when: You need simple file-based authentication for development or prototyping. For production, implement a custom authenticator class instead.

security:
	users:                     # Development only - NOT for production
		username: password

Anti-Patterns to Avoid

Don't name services unnecessarily – named services create coupling; when you rename the class, you must also update every @name reference. Only name when you need @serviceName references.

Don't register every class – only register classes that need injection or are injected elsewhere. Presenters are registered automatically (Nette scans them by IPresenter); components and their factory interfaces are not and must be registered explicitly.

Don't hardcode secrets – use parameters and load them from environment-specific config files (env.local.neon) that are gitignored.

Don't use positional parameters – use named parameters when mixing with autowiring. Positional arguments break when the constructor signature changes.

Don't bypass autowiring without reason – Nette DI handles dependencies automatically. Manual wiring is only needed for ambiguous types (multiple implementations of the same interface).

Online Documentation

For detailed information, use WebFetch on these URLs:

• DI Services – service registration and autowiring
• DI Configuration – config file format
• Application Configuration – application, http, session settings