Bootstrap
*********

<div class=perex>

Bootstrap to kod startowy, który inicjalizuje środowisko, tworzy kontener wtrysku zależności (DI) i uruchamia aplikację. Powiedzmy:

- jak skonfigurować przy użyciu plików NEON
- jak odróżnić tryb produkcyjny od deweloperskiego
- jak stworzyć kontener DI

</div>


Aplikacje, niezależnie od tego, czy są to aplikacje internetowe, czy skrypty wiersza poleceń, rozpoczynają swój czas działania od pewnej formy inicjalizacji środowiska. W dawnych czasach robił to plik o nazwie na przykład `include.inc.php`, który inkubował początkowy plik.
W nowoczesnych aplikacjach Nette zostało to zastąpione klasą `Bootstrap`, która jako część aplikacji znajduje się w pliku `app/Bootstrap.php` Może to wyglądać tak:

```php
use Nette\Bootstrap\Configurator;

class Bootstrap
{
	public static function boot(): Configurator
	{
		$appDir = dirname(__DIR__);
		$configurator = new Configurator;
		//$configurator->setDebugMode('secret@23.75.345.200');
		$configurator->enableTracy($appDir . '/log');
		$configurator->setTempDirectory($appDir . '/temp');
		$configurator->createRobotLoader()
			->addDirectory(__DIR__)
			->register();
		$configurator->addConfig($appDir . '/config/common.neon');
		return $configurator;
	}
}
```


index.php .[#toc-index-php]
===========================

Podstawowym plikiem w przypadku aplikacji internetowych jest `index.php`, który znajduje się w katalogu publicznym `www/`. Spowoduje to, że klasa Bootstrap zainicjuje środowisko i zwróci `$configurator`, a następnie wyprodukuje kontener DI. Następnie pobiera z niego usługę `Application`, która uruchamia aplikację internetową:

```php
// inicjalizacja środowiska + uzyskanie obiektu Configurator
$configurator = App\Bootstrap::boot();
// tworzenie kontenera DI
$container = $configurator->createContainer();
// Kontener DI tworzy obiekt "Nette
$application = $container->getByType(Nette\Application\Application::class);
// uruchomienie aplikacji Nette
$application->run();
```

Jak widać, klasa [api:Nette\Bootstrap\Configurator] pomaga w konfiguracji środowiska i tworzeniu kontenera dependency injection (DI), któremu teraz przyjrzymy się bliżej.


Tryb deweloperski a produkcyjny .[#toc-development-vs-production-mode]
======================================================================

Nette rozróżnia dwa podstawowe tryby, w których realizowane jest żądanie: deweloperski i produkcyjny. Tryb deweloperski ma na celu maksymalną wygodę dla programisty, wyświetlana jest Tracy, pamięć podręczna jest automatycznie aktualizowana, gdy zmieniają się szablony lub konfiguracje kontenerów DI itp. Produkcja skupia się na wydajności i rześkim wdrożeniu, Tracy tylko loguje błędy, a zmiany w szablonach i innych plikach nie są testowane.

Wybór trybu odbywa się poprzez autodetekcję, więc zazwyczaj nie ma potrzeby konfigurowania czy ręcznego przełączania czegokolwiek. Trybem deweloperskim jest sytuacja, kiedy aplikacja jest uruchomiona na localhoście (czyli na adresie IP `127.0.0.1` lub `::1`) i nie ma proxy (czyli jego nagłówka HTTP). W przeciwnym razie działa w trybie produkcyjnym.

Jeśli chcemy włączyć tryb deweloperski w innych przypadkach, takich jak programiści uzyskujący dostęp z określonego adresu IP, używamy `setDebugMode()`:

```php
$configurator->setDebugMode('23.75.345.200'); // można również określić pole adresu IP
```

Zdecydowanie zalecamy połączenie adresu IP z plikiem cookie. W pliku cookie `nette-debug` przechowujemy tajny token, np. `secret1234`, i w ten sposób umożliwiamy tryb deweloperski dla programistów uzyskujących dostęp z określonego adresu IP i posiadających token w pliku cookie:

```php
$configurator->setDebugMode('secret1234@23.75.345.200');
```

Możemy również całkowicie wyłączyć tryb deweloperski, nawet dla localhost:

```php
$configurator->setDebugMode(false);
```

Uwaga, wartość `true` domyślnie włącza tryb deweloperski, co nigdy nie może mieć miejsca na serwerze produkcyjnym.


Narzędzie do debugowania Tracy .[#toc-debugging-tool-tracy]
===========================================================

Aby ułatwić debugowanie, włączmy wspaniałe narzędzie [Tracy |tracy:]. Wizualizuje błędy w trybie deweloperskim i loguje błędy w trybie produkcyjnym do podanego katalogu:

```php
$configurator->enableTracy($appDir . '/log');
```


Pliki tymczasowe .[#toc-temporary-files]
========================================

Nette używa buforowania dla kontenera DI, RobotLoader, szablonów itp. Dlatego musisz ustawić ścieżkę do katalogu, w którym będzie przechowywany cache:

```php
$configurator->setTempDirectory($appDir . '/temp');
```

W systemach Linux lub macOS ustaw katalogi `log/` i `temp/` na uprawnienia do [zapisu |nette:troubleshooting#Setting-Directory-Permissions].


RobotLoader .[#toc-robotloader]
===============================

Zazwyczaj będziemy chcieli automatycznie załadować klasy za pomocą [RobotLoader |robot-loader:], więc musimy go uruchomić i kazać mu załadować klasy z katalogu, w którym znajduje się `Bootstrap.php` (czyli `__DIR__`), oraz z wszelkich podkatalogów:

```php
$configurator->createRobotLoader()
	->addDirectory(__DIR__)
	->register();
```

Alternatywnym podejściem jest pozwolić mu załadować klasy tylko poprzez [Composer |best-practices:composer], jednocześnie podążając za PSR-4.


Strefa czasowa .[#toc-timezone]
===============================

Domyślną strefę czasową można ustawić za pośrednictwem konfiguratora.

```php
$configurator->setTimeZone('Europe/Prague');
```


Konfiguracja kontenera DI .[#toc-di-container-configuration]
============================================================

Częścią procesu uruchamiania jest stworzenie kontenera DI, czyli fabryki obiektów, która jest sercem aplikacji. Jest to właściwie klasa PHP, która jest generowana przez Nette i przechowywana w katalogu cache. Fabryka produkuje kluczowe obiekty aplikacji, a my za pomocą plików konfiguracyjnych instruujemy ją, jak ma je tworzyć i ustawiać, wpływając tym samym na zachowanie całej aplikacji.

Pliki konfiguracyjne są zazwyczaj zapisane w formacie [NEON |neon:format]. Zobacz osobny rozdział, aby dowiedzieć się, co [można skonfigurować |nette:configuring].

.[tip]
W trybie deweloperskim kontener jest automatycznie aktualizowany przy każdej zmianie kodu lub plików konfiguracyjnych. W trybie produkcyjnym jest on generowany tylko raz, a zmiany nie są sprawdzane w celu uzyskania maksymalnej wydajności.

Pliki konfiguracyjne są ładowane za pomocą `addConfig()`:

```php
$configurator->addConfig($appDir . '/config/common.neon');
```

Jeśli chcemy dodać więcej plików konfiguracyjnych, możemy wywołać funkcję `addConfig()` wielokrotnie.

```php
$configurator->addConfig($appDir . '/config/common.neon');
$configurator->addConfig($appDir . '/config/services.neon');
if (PHP_SAPI === 'cli') {
	$configurator->addConfig($appDir . '/config/cli.php');
}
```

Nazwa `cli.php` nie jest literówką, konfiguracja może być również zapisana w pliku PHP, który zwraca ją jako tablicę.

Możemy również dodać inne pliki konfiguracyjne w [sekcji `includes` |dependency-injection:configuration#including-files].

Jeśli w plikach konfiguracyjnych pojawią się elementy o takich samych kluczach, zostaną one nadpisane, lub [scalone |dependency-injection:configuration#merging] w przypadku pól. Plik dodany później ma wyższy priorytet niż poprzedni. Plik, w którym wymieniona jest sekcja `includes` ma wyższy priorytet niż pliki w niej zawarte.


Parametry statyczne .[#toc-static-parameters]
---------------------------------------------

Parametry wykorzystywane w plikach konfiguracyjnych można zdefiniować [w sekcji `parameters` |dependency-injection:configuration#parameters], a także przekazać (lub nadpisać) za pomocą metody `addStaticParameters()` (posiada ona alias `addParameters()`). Co ważne, różne wartości parametrów spowodują wygenerowanie dodatkowych kontenerów DI, czyli dodatkowych klas.

```php
$configurator->addStaticParameters([
	'projectId' => 23,
]);
```

W plikach konfiguracyjnych możemy zapisać zwykłą notację `%projectId%` aby uzyskać dostęp do parametru o nazwie `projectId`.


Parametry dynamiczne .[#toc-dynamic-parameters]
-----------------------------------------------

Do kontenera możemy również dodać parametry dynamiczne, których różne wartości, w przeciwieństwie do parametrów statycznych, nie będą powodowały generowania nowych kontenerów DI.

```php
$configurator->addDynamicParameters([
	'remoteIp' => $_SERVER['REMOTE_ADDR'],
]);
```

Możemy po prostu dodać np. zmienne środowiskowe, do których następnie możemy się odwołać w konfiguracji pisząc `%env.variable%`.

```php
$configurator->addDynamicParameters([
	'env' => getenv(),
]);
```


Parametry domyślne .[#toc-default-parameters]
---------------------------------------------

W plikach konfiguracyjnych można używać następujących parametrów statycznych:

- `%appDir%` jest bezwzględną ścieżką do katalogu zawierającego plik `Bootstrap.php`
- `%wwwDir%` jest bezwzględną ścieżką do katalogu zawierającego plik wejściowy `index.php`
- `%tempDir%` jest bezwzględną ścieżką do katalogu plików tymczasowych
- `%vendorDir%` to bezwzględna ścieżka do katalogu, w którym Composer instaluje biblioteki
- `%rootDir%` to bezwzględna ścieżka do katalogu głównego projektu
- `%debugMode%` wskazuje, czy aplikacja jest w trybie debugowania
- `%consoleMode%` wskazuje, czy żądanie przyszło z linii poleceń


Usługi importowane .[#toc-imported-services]
--------------------------------------------

Teraz wchodzimy głębiej. Chociaż punktem kontenera DI jest wytwarzanie obiektów, w rzadkich przypadkach może zaistnieć potrzeba wstawienia do kontenera istniejącego obiektu. Robimy to poprzez zdefiniowanie usługi z flagą `imported: true`.

```neon
services:
	myservice:
		type: App\Model\MyCustomService
		imported: true
```

A w bootstrapie wstawiamy obiekt do kontenera:

```php
$configurator->addServices([
	'myservice' => new App\Model\MyCustomService('foobar'),
]);
```


Różne środowiska .[#toc-different-environments]
===============================================

Zapraszamy do dostosowania klasy Bootstrap do swoich potrzeb. Możesz dodać parametry do metody `boot()`, aby odróżnić projekty internetowe, lub dodać inne metody, takie jak `bootForTests()`, która inicjalizuje środowisko dla testów jednostkowych, `bootForCli()` dla skryptów wywoływanych z linii poleceń itp.

```php
public static function bootForTests(): Configurator
{
	$configurator = self::boot();
	Tester\Environment::setup(); // inicializace Nette Testeru
	return $configurator;
}
```