Autowiring
**********

.[perex]
Autowiring to świetna funkcja, która automatycznie przekazuje do konstruktora i innych metod potrzebne usługi, dzięki czemu nie musimy ich jawnie podawać. Oszczędza mnóstwo czasu.

Dzięki temu przy pisaniu definicji usług możemy pominąć zdecydowaną większość argumentów. Zamiast:

```neon
services:
	articles: Model\ArticleRepository(@database, @cache.storage)
```

wystarczy napisać:

```neon
services:
	articles: Model\ArticleRepository
```

Autowiring kieruje się typami, więc aby zadziałał, klasa `ArticleRepository` musi być zdefiniowana mniej więcej tak:

```php
namespace Model;

class ArticleRepository
{
	public function __construct(\PDO $db, \Nette\Caching\Storage $storage)
	{}
}
```

Autowiring nigdy nie używa nazw usług. Kieruje się wyłącznie systemem typów PHP, więc wie też, że klasa spełnia interfejsy, które implementuje, i klasy, po których dziedziczy. Dzięki temu nazwa usługi jest tylko pomocniczym identyfikatorem, a zmiana jej nazwy niczego w aplikacji nie zepsuje.

Aby móc używać autowiringu, w kontenerze musi istnieć **dokładnie jedna usługa** każdego typu. Gdyby było ich więcej, autowiring nie wiedziałby, którą przekazać, i zgłosiłby wyjątek:

```neon
services:
	mainDb: PDO(%dsn%, %user%, %password%)
	tempDb: PDO('sqlite::memory:')
	articles: Model\ArticleRepository  # ZGŁASZA WYJĄTEK, pasują zarówno mainDb, jak i tempDb
```

Jednym z rozwiązań jest obejście autowiringu i jawne podanie nazwy usługi (np. `articles: Model\ArticleRepository(@mainDb)`). Wygodniejszym podejściem jest jednak albo [wyłączenie |#Wyłączenie autowiringu] autowiringu dla jednej z usług, albo [wskazanie |#Preferowanie w autowiringu] jednej usługi jako preferowanej.


Wyłączenie autowiringu
----------------------

Autowiring dla usługi możemy wyłączyć opcją `autowired: false`:

```neon
services:
	mainDb: PDO(%dsn%, %user%, %password%)

	tempDb:
		create: PDO('sqlite::memory:')
		autowired: false               # usługa tempDb jest wyłączona z autowiringu

	articles: Model\ArticleRepository  # dlatego do konstruktora trafia mainDb
```

Usługa `articles` nie zgłosi wyjątku o dwóch pasujących usługach `PDO` (`mainDb` i `tempDb`) dostępnych dla konstruktora, bo bierze pod uwagę tylko usługę `mainDb`.

Autowiring można też wyłączyć globalnie dla całych typów, opcją konfiguracyjną [`di › excluded` |configuration#DI], która wymienia typy (i ich potomków), które nigdy nie mają być autowirowane.

.[note]
Konfiguracja autowiringu w Nette różni się od Symfony. W Symfony `autowire: false` oznacza, że autowiring nie ma być używany dla argumentów konstruktora usługi. W Nette autowiring dotyczy argumentów konstruktora i wszelkich innych metod wywoływanych przez kontener (jak setter injection). Opcja `autowired: false` uniemożliwia kontenerowi automatyczne przekazywanie tej instancji usługi jako zależności do innych usług.


Preferowanie w autowiringu
--------------------------

Jeśli mamy kilka usług tego samego typu i dla jednej z nich podamy opcję `autowired`, usługa ta staje się preferowana:

```neon
services:
	mainDb:
		create: PDO(%dsn%, %user%, %password%)
		autowired: PDO    # staje się preferowana

	tempDb:
		create: PDO('sqlite::memory:')

	articles: Model\ArticleRepository
```

Usługa `articles` nie zgłosi wyjątku o kilku pasujących usługach `PDO` (`mainDb` i `tempDb`), lecz użyje preferowanej, czyli `mainDb`.


Kolekcja usług
--------------

Autowiring potrafi przekazywać również tablice usług określonego typu. Ponieważ PHP natywnie nie obsługuje podawania typu elementów tablicy w deklaracjach typów, musisz uzupełnić deklarację typu `array` komentarzem phpDoc podającym typ elementu, w rodzaju `ClassName[]`:

```php
namespace Model;

class ShipManager
{
	/**
	 * @param Shipper[] $shippers
	 */
	public function __construct(array $shippers)
	{}
}
```

Kontener DI przekazuje wtedy automatycznie tablicę usług odpowiadających podanemu typowi. Pomija usługi z [wyłączonym autowiringiem |#Wyłączenie autowiringu] i nigdy nie umieszcza aktualnie tworzonej usługi w jej własnej kolekcji. W odróżnieniu od przekazywania pojedynczej usługi [zawężenie |#Zawężanie autowiringu] autowiringu do konkretnego typu albo oznaczenie usługi jako [preferowanej |#Preferowanie w autowiringu] nie ma tu żadnego znaczenia - tablica zawiera zawsze wszystkie usługi danego typu.

Typ w komentarzu może mieć również postać `array<int, Class>` albo `list<Class>`. Jeśli nie masz kontroli nad postacią komentarza phpDoc, możesz przekazać tablicę usług bezpośrednio w konfiguracji za pomocą [`typed()` |services#Funkcje specjalne].


Argumenty skalarne
------------------

Autowiring działa tylko dla obiektów i tablic obiektów. Argumenty skalarne (np. stringi, liczby, wartości logiczne) trzeba [podać w konfiguracji |services#Argumenty]. Alternatywą jest utworzenie [obiektu ustawień|best-practices:passing-settings-to-presenters], który zamyka wartość skalarną (albo wiele wartości). Taki obiekt można potem przekazywać autowiringiem.

```php
class MySettings
{
	public function __construct(
		// readonly można używać od PHP 8.1
		public readonly bool $value,
	)
	{}
}
```

Rejestrujesz go jako usługę, dodając do konfiguracji:

```neon
services:
	- MySettings('any value')
```

Inne klasy mogą go potem otrzymać przez autowiring.


Zależności opcjonalne
---------------------

Jeśli parametr konstruktora albo metody ma wartość domyślną, a w kontenerze nie ma usługi wymaganego typu, autowiring nie zgłasza wyjątku - po prostu pomija argument, więc użyta zostaje wartość domyślna. Tak deklaruje się zależności opcjonalne:

```php
class Foo
{
	public function __construct(
		private ?Logger $logger = null,
	) {}
}
```

Odwrotnie, przy parametrze bez wartości domyślnej brak usługi zawsze powoduje wyjątek.


Zawężanie autowiringu
---------------------

Dla poszczególnych usług autowiring można zawęzić do konkretnych klas albo interfejsów.

Normalnie autowiring przekazuje usługę do każdego parametru metody, którego typowi usługa odpowiada. Zawężenie oznacza, że ustalamy warunki, jakie muszą spełniać typy podane dla parametrów metod, aby usługa została do nich przekazana.

Weźmy przykład:

```php
class ParentClass
{}

class ChildClass extends ParentClass
{}

class ParentDependent
{
	function __construct(ParentClass $obj)
	{}
}

class ChildDependent
{
	function __construct(ChildClass $obj)
	{}
}
```

Gdybyśmy zarejestrowali je wszystkie jako usługi, autowiring by zawiódł:

```neon
services:
	parent: ParentClass
	child: ChildClass
	parentDep: ParentDependent  # ZGŁASZA WYJĄTEK, pasują zarówno usługa parent, jak i child
	childDep: ChildDependent    # autowiring przekazuje do konstruktora usługę child
```

Usługa `parentDep` zgłasza wyjątek `Multiple services of type ParentClass found: child, parent`, bo do jej konstruktora pasują zarówno usługa `parent`, jak i `child`, a autowiring nie potrafi zdecydować, którą wybrać.

Dla usługi `child` możemy więc zawęzić jej autowiring do typu `ChildClass`:

```neon
services:
	parent: ParentClass
	child:
		create: ChildClass
		autowired: ChildClass   # można też zapisać jako 'autowired: self'

	parentDep: ParentDependent  # autowiring przekazuje do konstruktora usługę parent
	childDep: ChildDependent    # autowiring przekazuje do konstruktora usługę child
```

Teraz do konstruktora usługi `parentDep` przekazywana jest usługa `parent`, bo jest jedynym pasującym obiektem. Usługa `child` nie jest już tam przekazywana przez autowiring. Tak, usługa `child` nadal jest typu `ParentClass`, ale warunek zawężający `autowired: ChildClass` oznacza, że zostanie przekazana tylko do parametrów jawnie otypowanych jako `ChildClass` (albo jej podtypy). Ponieważ `ParentDependent` wymaga `ParentClass`, usługa `child` nie jest już tam brana pod uwagę jako kandydat do autowiringu.

Dla usługi `child` `autowired: ChildClass` można też zapisać jako `autowired: self`, bo `self` jest symbolem zastępczym klasy bieżącej usługi.

W kluczu `autowired` można też podać kilka klas albo interfejsów jako tablicę:

```neon
autowired: [ParentClass, FooInterface]
```

Spróbujmy dodać do przykładu interfejsy:

```php
interface FooInterface
{}

interface BarInterface
{}

class ParentClass implements FooInterface
{}

class ChildClass extends ParentClass implements BarInterface
{}

class FooDependent
{
	function __construct(FooInterface $obj)
	{}
}

class BarDependent
{
	function __construct(BarInterface $obj)
	{}
}

class ParentDependent
{
	function __construct(ParentClass $obj)
	{}
}

class ChildDependent
{
	function __construct(ChildClass $obj)
	{}
}
```

Jeśli w żaden sposób nie ograniczymy usługi `child`, będzie pasować do konstruktorów wszystkich klas `FooDependent`, `BarDependent`, `ParentDependent` i `ChildDependent`, a autowiring wszędzie ją przekaże.

Jeśli jednak zawęzimy jej autowiring do `ChildClass` przez `autowired: ChildClass` (albo `self`), autowiring przekaże ją tylko do konstruktora `ChildDependent`, bo wymaga on argumentu typu `ChildClass`, a zachodzi, że `ChildClass` *jest typu* `ChildClass`. Żaden z pozostałych wymaganych typów parametrów nie jest `ChildClass` ani jej podtypem, więc usługa nie jest do nich przekazywana.

Jeśli ograniczymy ją do `ParentClass` przez `autowired: ParentClass`, autowiring znów przekaże ją do konstruktora `ChildDependent` (bo wymagany `ChildClass` jest podtypem `ParentClass`), a teraz również do konstruktora `ParentDependent`, bo wymagany typ `ParentClass` również pasuje.

Jeśli ograniczymy ją do `FooInterface`, nadal będzie autowirowana do `ParentDependent` (wymagany `ParentClass` jest podtypem `FooInterface`) i `ChildDependent`, a dodatkowo do konstruktora `FooDependent`, ale nie do `BarDependent`, bo `BarInterface` nie jest podtypem `FooInterface`.

```neon
services:
	child:
		create: ChildClass
		autowired: FooInterface

	fooDep: FooDependent        # autowiring przekazuje do konstruktora usługę child
	barDep: BarDependent        # ZGŁASZA WYJĄTEK, żadna usługa nie pasuje
	parentDep: ParentDependent  # autowiring przekazuje do konstruktora usługę child
	childDep: ChildDependent    # autowiring przekazuje do konstruktora usługę child
```