Dienst-Definitionen
*******************

.[perex]
Die Konfiguration ist der Ort, an dem wir den DI-Container anweisen, wie er die einzelnen Dienste zusammenstellen und mit anderen Abhängigkeiten verbinden soll. Nette bietet eine sehr klare und elegante Möglichkeit, dies zu erreichen.

Der Abschnitt `services` in der NEON-Konfigurationsdatei ist der Ort, an dem wir unsere benutzerdefinierten Dienste und deren Konfigurationen definieren. Schauen wir uns ein einfaches Beispiel für die Definition eines Dienstes namens `database` an, der eine Instanz der Klasse `PDO` darstellt:

```neon
services:
	database: PDO('sqlite::memory:')
```

Diese Konfiguration führt zu der folgenden Fabrikmethode im [DI-Container |container]:

```php
public function createServiceDatabase(): PDO
{
	return new PDO('sqlite::memory:');
}
```

Dienstnamen ermöglichen es uns, in anderen Teilen der Konfigurationsdatei auf sie zu verweisen, indem wir das Format `@serviceName` verwenden. Wenn es nicht notwendig ist, den Dienst zu benennen, können wir einfach einen Aufzählungspunkt verwenden:

```neon
services:
	- PDO('sqlite::memory:')
```

Um einen Dienst aus dem DI-Container abzurufen, können wir die Methode `getService()` mit dem Dienstnamen als Parameter oder die Methode `getByType()` mit dem Diensttyp verwenden:

```php
$database = $container->getService('database');
$database = $container->getByType(PDO::class);
```


Erstellung von Diensten .[#toc-service-creation]
================================================

In den meisten Fällen wird ein Dienst einfach durch die Instanziierung einer bestimmten Klasse erstellt. Zum Beispiel:

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

Wenn wir die Konfiguration um zusätzliche Schlüssel erweitern müssen, kann die Definition in mehrere Zeilen aufgeteilt werden:

```neon
services:
	database:
		create: PDO('sqlite::memory:')
		setup: ...
```

Der Schlüssel `create` hat einen Alias `factory`, beide Versionen sind in der Praxis üblich. Wir empfehlen jedoch die Verwendung von `create`.

Konstruktorargumente oder die Erstellungsmethode können alternativ in den Schlüssel `arguments` geschrieben werden:

```neon
services:
	database:
		create: PDO
		arguments: ['mysql:host=127.0.0.1;dbname=test', root, secret]
```

Dienste müssen nicht nur durch einfache Instanziierung einer Klasse erzeugt werden, sondern können auch durch den Aufruf statischer Methoden oder Methoden anderer Dienste entstehen:

```neon
services:
	database: DatabaseFactory::create()
	router: @routerFactory::create()
```

Beachten Sie, dass wir der Einfachheit halber anstelle von `->` `::` verwenden, siehe [Ausdrucksmittel |#expression means]. Diese Fabrikmethoden werden generiert:

```php
public function createServiceDatabase(): PDO
{
	return DatabaseFactory::create();
}

public function createServiceRouter(): RouteList
{
	return $this->getService('routerFactory')->create();
}
```

Der DI-Container muss den Typ des erzeugten Dienstes kennen. Wenn wir einen Dienst mit einer Methode erstellen, die keinen bestimmten Rückgabetyp hat, müssen wir diesen Typ in der Konfiguration explizit angeben:

```neon
services:
	database:
		create: DatabaseFactory::create()
		type: PDO
```


Argumente .[#toc-arguments]
===========================

Wir übergeben Argumente an Konstruktoren und Methoden auf eine Weise, die der von PHP sehr ähnlich ist:

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

Zur besseren Lesbarkeit können wir die Argumente in separaten Zeilen auflisten. In diesem Format ist die Verwendung von Kommas optional:

```neon
services:
	database: PDO(
		'mysql:host=127.0.0.1;dbname=test'
		root
		secret
	)
```

Sie können die Argumente auch benennen, dann brauchen Sie sich nicht um ihre Reihenfolge zu kümmern:

```neon
services:
	database: PDO(
		username: root
		password: secret
		dsn: 'mysql:host=127.0.0.1;dbname=test'
	)
```

Wenn Sie bestimmte Argumente auslassen und ihre Standardwerte verwenden oder einen Dienst über die [automatische Verdrahtung |autowiring] einfügen möchten, verwenden Sie einen Unterstrich:

```neon
services:
	foo: Foo(_, %appDir%)
```

Argumente können Dienste, Parameter und vieles mehr sein, siehe [Ausdrucksmittel |#expression means].


Einrichtung .[#toc-setup]
=========================

Im Abschnitt `setup` definieren wir die Methoden, die bei der Erstellung des Dienstes aufgerufen werden sollen.

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

In PHP würde dies wie folgt aussehen:

```php
public function createServiceDatabase(): PDO
{
	$service = new PDO('...', '...', '...');
	$service->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
	return $service;
}
```

Zusätzlich zu Methodenaufrufen können Sie auch Werte an Eigenschaften übergeben. Das Hinzufügen eines Elements zu einem Array wird ebenfalls unterstützt, aber Sie müssen es in Anführungszeichen setzen, um Kollisionen mit der NEON-Syntax zu vermeiden:

```neon
services:
	foo:
		create: Foo
		setup:
			- $value = 123
			- '$onClick[]' = [@bar, clickHandler]
```

In PHP würde dies bedeuten:

```php
public function createServiceFoo(): Foo
{
	$service = new Foo;
	$service->value = 123;
	$service->onClick[] = [$this->getService('bar'), 'clickHandler'];
	return $service;
}
```

Im Setup können Sie auch statische Methoden oder Methoden von anderen Diensten aufrufen. Wenn Sie den aktuellen Dienst als Argument übergeben müssen, verwenden Sie `@self`:

```neon
services:
	foo:
		create: Foo
		setup:
			- My\Helpers::initializeFoo(@self)
			- @anotherService::setFoo(@self)
```

Beachten Sie, dass wir der Einfachheit halber anstelle von `->` `::` verwenden, siehe [Ausdrucksmittel |#expression means]. Dies erzeugt die folgende Fabrikmethode:

```php
public function createServiceFoo(): Foo
{
	$service = new Foo;
	My\Helpers::initializeFoo($service);
	$this->getService('anotherService')->setFoo($service);
	return $service;
}
```


Ausdrucksmittel .[#toc-expression-means]
========================================

Nette DI bietet uns außergewöhnlich reichhaltige Ausdrucksmöglichkeiten, die es uns erlauben, fast alles zu artikulieren. In Konfigurationsdateien können wir [Parameter |configuration#parameters] verwenden:

```neon
# Parameter
%wwwDir%

# Wert unter einem Parameterschlüssel
%mailer.user%

# Parameter innerhalb einer Zeichenkette
'%wwwDir%/images'
```

Wir können auch Objekte erstellen, Methoden und Funktionen aufrufen:

```neon
# ein Objekt erstellen
DateTime()

# eine statische Methode aufrufen
Collator::create(%locale%)

# eine PHP-Funktion aufrufen
::getenv(DB_USER)
```

Beziehen Sie sich auf Dienste entweder durch ihren Namen oder durch ihren Typ:

```neon
# Dienst nach Name
@database

# Dienst nach Typ
@Nette\Database\Connection
```

Verwenden Sie die Syntax von First-Class Callables: .{data-version:3.2.0}

```neon
# creating a callback, equivalent to [@user, logout]
@user::logout(...)
```

Verwenden Sie Konstanten:

```neon
# Klassenkonstante
FilesystemIterator::SKIP_DOTS

# globale Konstante, die mit der PHP-Funktion constant() ermittelt wird
::constant(PHP_VERSION)
```

Methodenaufrufe können, genau wie in PHP, verkettet werden. Der Einfachheit halber verwenden wir anstelle von `->` `::` :

```neon
DateTime()::format('Y-m-d')
# PHP: (new DateTime())->format('Y-m-d')

@http.request::getUrl()::getHost()
# PHP: $this->getService('http.request')->getUrl()->getHost()
```

Diese Ausdrücke können bei der [Erstellung von Diensten |#Service Creation] überall verwendet werden, in [Argumenten |#Arguments], im [Setup-Abschnitt |#setup] oder in [Parametern |configuration#parameters]:

```neon
parameters:
	ipAddress: @http.request::getRemoteAddress()

services:
	database:
		create: DatabaseFactory::create( @anotherService::getDsn() )
		setup:
			- initialize( ::getenv('DB_USER') )
```


Besondere Funktionen .[#toc-special-functions]
----------------------------------------------

Innerhalb von Konfigurationsdateien können Sie diese speziellen Funktionen verwenden:

- `not()` für die Negation von Werten
- `bool()`, `int()`, `float()`, `string()` für verlustfreies Type Casting
- `typed()` um ein Array mit allen Diensten eines bestimmten Typs zu erzeugen
- `tagged()`, um ein Array aller Dienste mit einem bestimmten Tag zu erzeugen

```neon
services:
	- Foo(
		id: int(::getenv('ProjectId'))
		productionMode: not(%debugMode%)
	)
```

Im Vergleich zum konventionellen Typecasting in PHP, wie z.B. `(int)`, wird beim verlustfreien Typecasting eine Exception für nicht-numerische Werte geworfen.

Die Funktion `typed()` erstellt ein Array mit allen Diensten eines bestimmten Typs (Klasse oder Schnittstelle). Sie schließt Dienste mit ausgeschaltetem Autowiring aus. Es können mehrere Typen angegeben werden, getrennt durch Kommas.

```neon
services:
	- BarsDependent( typed(Bar) )
```

Sie können auch automatisch ein Array von Diensten eines bestimmten Typs als Argument übergeben, indem Sie [autowiring |autowiring#Collection of Services] verwenden.

Die Funktion `tagged()` erstellt ein Array mit allen Diensten mit einem bestimmten Tag. Es können mehrere Tags aufgelistet werden, getrennt durch Kommas.

```neon
services:
	- LoggersDependent( tagged(logger) )
```


Fahrzeugverkabelung .[#toc-autowiring]
======================================

Mit der Taste `autowired` können Sie das Autowiring-Verhalten für einen bestimmten Dienst ändern. Weitere Einzelheiten finden Sie im [Kapitel über die automatische Verdrahtung |autowiring].

```neon
services:
	foo:
		create: Foo
		autowired: false     # der Foo-Dienst ist vom Autowiring ausgeschlossen
```


Tags .[#toc-tags]
=================

Tags werden verwendet, um zusätzliche Informationen zu Diensten hinzuzufügen. Sie können einem Dienst ein oder mehrere Tags zuweisen:

```neon
services:
	foo:
		create: Foo
		tags:
			- cached
```

Tags können auch Werte enthalten:

```neon
services:
	foo:
		create: Foo
		tags:
			logger: monolog.logger.event
```

Um alle Dienste mit bestimmten Tags abzurufen, können Sie die Funktion `tagged()` verwenden:

```neon
services:
	- LoggersDependent( tagged(logger) )
```

Im DI-Container können Sie mit der Methode `findByTag()` die Namen aller Dienste mit einem bestimmten Tag abrufen:

```php
$names = $container->findByTag('logger');
// $names ist ein Array, das den Dienstnamen und den Tag-Wert enthält
// z.B. ['foo' => 'monolog.logger.event', ...]
```


Injektionsmodus .[#toc-inject-mode]
===================================

Mit dem Flag `inject: true` wird die Übergabe von Abhängigkeiten über öffentliche Variablen mit der [inject-Annotation |best-practices:inject-method-attribute#Inject Attributes] und den [inject*() |best-practices:inject-method-attribute#inject Methods] -Methoden aktiviert.

```neon
services:
	articles:
		create: App\Model\Articles
		inject: true
```

Standardmäßig ist `inject` nur für Präsentatoren aktiviert.


Änderungen am Dienst .[#toc-service-modifications]
==================================================

Der DI-Container enthält viele Dienste, die entweder durch eingebaute oder [durch Benutzererweiterungen |#extensions] hinzugefügt wurden. Sie können die Definitionen dieser Dienste direkt in der Konfiguration ändern. So können Sie beispielsweise die Klasse des Dienstes `application.application`, die üblicherweise `Nette\Application\Application` lautet, in eine andere ändern:

```neon
services:
	application.application:
		create: MyApplication
		alteration: true
```

Das Kennzeichen `alteration` ist informativ und zeigt an, dass es sich lediglich um eine Änderung eines bestehenden Dienstes handelt.

Wir können die Einrichtung auch ergänzen:

```neon
services:
	application.application:
		create: MyApplication
		alteration: true
		setup:
			- '$onStartup[]' = [@resource, init]
```

Wenn Sie einen Dienst überschreiben, möchten Sie vielleicht die ursprünglichen Argumente, Einrichtungselemente oder Tags entfernen, und hier kommt `reset` ins Spiel:

```neon
services:
	application.application:
		create: MyApplication
		alteration: true
		reset:
			- arguments
			- setup
			- tags
```

Wenn Sie einen Dienst, der von einer Erweiterung hinzugefügt wurde, entfernen möchten, können Sie dies wie folgt tun:

```neon
services:
	cache.journal: false
```