Bootstrap

Bootstrap je zagonska koda, ki inicializira okolje, ustvari vsebnik za vbrizgavanje odvisnosti (DI) in zažene aplikacijo. Obravnavali bomo:

  • kako konfigurirati aplikacijo z datotekami NEON
  • kako ravnati s produkcijskim in razvojnim načinom
  • kako ustvariti vsebnik DI

Aplikacije, ne glede na to, ali temeljijo na spletu ali skripti ukazne vrstice, se začnejo z določeno obliko inicializacije okolja. V starih časih je bila za to lahko odgovorna datoteka z imenom npr. include.inc.php, ki je bila vključena v začetno datoteko. V sodobnih aplikacijah Nette jo je nadomestil razred Bootstrap, ki se kot del aplikacije nahaja v datoteki app/Bootstrap.php. Izgleda lahko na primer takole:

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

Pri spletnih aplikacijah je začetna datoteka index.php, ki se nahaja v javnem imeniku www/. Omogoča, da razred Bootstrap inicializira okolje in vrne $configurator, ki ustvari vsebnik DI. Nato pridobi storitev Application, ki izvaja spletno aplikacijo:

// inicializacija okolja + pridobitev predmeta Configurator
$configurator = App\Bootstrap::boot();
// ustvarite vsebnik DI
$container = $configurator->createContainer();
// vsebnik DI ustvari objekt Nette\Application\Application
$application = $container->getByType(Nette\Application\Application::class);
// zaženite aplikacijo Nette
$application->run();

Kot vidite, razred Nette\Bootstrap\Configurator, ki ga bomo zdaj podrobneje predstavili, pomaga pri vzpostavljanju okolja in ustvarjanju vsebnika za vbrizgavanje odvisnosti (DI).

Razvojni in produkcijski način

Nette razlikuje med dvema osnovnima načinoma izvajanja zahtevka: razvojnim in produkcijskim. Razvojni način je osredotočen na čim večje udobje programerja, prikazan je Tracy, predpomnilnik se samodejno posodablja ob spreminjanju predlog ali konfiguracije vsebnika DI itd. Produkcijski način je osredotočen na zmogljivost, Tracy beleži le napake, spremembe predlog in drugih datotek pa se ne preverjajo.

Izbira načina poteka s samodejnim zaznavanjem, zato običajno ni treba ničesar ročno konfigurirati ali preklapljati. Način je razvojni, če aplikacija teče na lokalnem gostitelju (tj. naslov IP 127.0.0.1 ali ::1) in ni prisoten posrednik (tj. njegova glavička HTTP). V nasprotnem primeru deluje v produkcijskem načinu.

Če želite omogočiti razvojni način v drugih primerih, na primer za programerje, ki dostopajo z določenega naslova IP, lahko uporabite setDebugMode():

$configurator->setDebugMode('23.75.345.200'); // enega ali več naslovov IP.

Vsekakor priporočamo kombinacijo naslova IP s piškotkom. V piškotek nette-debug bomo shranili tajni žeton, npr. secret1234, razvojni način pa bo aktiviran za programerje s to kombinacijo IP in piškotka.

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

Razvojni način lahko tudi popolnoma izklopimo, tudi za lokalni gostitelj:

$configurator->setDebugMode(false);

Vrednost true vklopi način za razvijalce, kar se na produkcijskem strežniku ne bi smelo zgoditi.

Orodje za razhroščevanje Tracy

Za lažje razhroščevanje bomo vklopili odlično orodje Tracy. V načinu za razvijalce vizualizira napake, v produkcijskem načinu pa napake beleži v določen imenik:

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

Začasne datoteke

Nette uporablja predpomnilnik za vsebnik DI, RobotLoader, predloge itd. Zato je treba nastaviti pot do imenika, v katerem bo shranjen predpomnilnik:

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

V operacijskem sistemu Linux ali macOS nastavite dovoljenja za pisanje za imenike log/ in temp/.

RobotLoader

Običajno bomo želeli samodejno naložiti razrede z RobotLoaderjem, zato ga moramo zagnati in mu omogočiti, da naloži razrede iz imenika, kjer se nahaja Bootstrap.php (tj. __DIR__), in vseh njegovih podimenikov:

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

Druga možnost je, da uporabimo samo samodejno nalaganje Composer PSR-4.

Časovni pas

Configurator vam omogoča, da določite časovni pas za svojo aplikacijo.

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

Konfiguracija zabojnika DI

Del zagonskega postopka je ustvarjanje vsebnika DI, tj. tovarne za predmete, ki je srce celotne aplikacije. To je pravzaprav razred PHP, ki ga ustvari Nette in je shranjen v imeniku predpomnilnika. Tovarna izdeluje ključne objekte aplikacije, konfiguracijske datoteke pa ji dajejo navodila, kako naj jih ustvari in konfigurira, s čimer vplivamo na obnašanje celotne aplikacije.

Konfiguracijske datoteke so običajno zapisane v formatu NEON. Kaj vse je mogoče konfigurirati, si lahko preberete tukaj.

V razvojnem načinu se vsebnik samodejno posodobi vsakič, ko spremenite kodo ali konfiguracijske datoteke. V produkcijskem načinu se ustvari samo enkrat, spremembe datotek pa se ne preverjajo, da bi povečali zmogljivost.

Konfiguracijske datoteke se naložijo z uporabo addConfig():

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

Metodo addConfig() lahko za dodajanje več datotek pokličete večkrat.

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

Ime cli.php ni tiskarska napaka, konfiguracijo lahko zapišete tudi v datoteko PHP, ki jo vrne kot polje.

Druga možnost je, da z razdelkomincludes naložimo več konfiguracijskih datotek.

Če se v konfiguracijskih datotekah pojavijo elementi z enakimi ključi, se bodo prepisali ali združili v primeru polj. Kasneje vključena datoteka ima višjo prioriteto kot prejšnja. Datoteka, v kateri je naveden razdelek includes, ima višjo prednost kot datoteke, ki so vanjo vključene.

Statični parametri

Parametre, ki se uporabljajo v konfiguracijskih datotekah, je mogoče opredeliti v razdelku parameters in jih tudi posredovati (ali prepisati) z metodo addStaticParameters() (ima vzdevek addParameters()). Pomembno je, da različne vrednosti parametrov povzročijo generiranje dodatnih vsebnikov DI, tj. dodatnih razredov.

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

V konfiguracijskih datotekah lahko zapišemo običajni zapis %projectId% za dostop do parametra z imenom projectId.

Dinamični parametri

Kontejnerju lahko dodamo tudi dinamične parametre, katerih različne vrednosti za razliko od statičnih parametrov ne bodo povzročile generiranja novih DI kontejnerjev.

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

Spremenljivke okolja bi lahko preprosto dali na voljo z dinamičnimi parametri. Do njih lahko dostopamo prek spletne strani %env.variable% v konfiguracijskih datotekah.

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

Privzete parametre

V konfiguracijskih datotekah lahko uporabite naslednje statične parametre:

  • %appDir% je absolutna pot do imenika datoteke Bootstrap.php.
  • %wwwDir% je absolutna pot do imenika, ki vsebuje vstopno datoteko index.php
  • %tempDir% je absolutna pot do imenika za začasne datoteke
  • %vendorDir% je absolutna pot do imenika, v katerega Composer namesti knjižnice
  • %debugMode% označuje, ali je aplikacija v načinu odpravljanja napak
  • %consoleMode% označuje, ali je bila zahteva poslana prek ukazne vrstice

Uvožene storitve

Zdaj se bomo poglobili. Čeprav je namen vsebnika DI ustvarjanje objektov, se lahko izjemoma pojavi potreba po vstavitvi obstoječega objekta v vsebnik. To storimo tako, da definiramo storitev z atributom imported: true.

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

Ustvarite nov primerek in ga vstavite v bootstrap:

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

Različna okolja

Razred Bootstrap lahko prilagodite svojim potrebam. Metodi boot() lahko dodate parametre za razlikovanje med spletnimi projekti ali dodate druge metode, kot so bootForTests(), ki inicializira okolje za teste enote, bootForCli() za skripte, ki se kličejo iz ukazne vrstice, in tako naprej.

public static function bootForTests(): Configurator
{
	$configurator = self::boot();
	Tester\Environment::setup(); // Inicializacija Nette Testerja
	return $configurator;
}
različica: 4.0