Nette Documentation Preview

syntax
RobotLoader: Osztály automatikus betöltése
******************************************

<div class=perex>

A RobotLoader egy olyan eszköz, amely kényelmet biztosít az automatikus osztálybetöltés számára a teljes alkalmazásod számára, beleértve a harmadik féltől származó könyvtárakat is.

- Megszünteti az összes `require` utasítást
- Csak a szükséges szkriptek töltődnek be
- Nem igényel szigorú elnevezési konvenciókat a könyvtárak vagy fájlok számára
- Rendkívül gyors
- Nincs manuális gyorsítótár frissítés, minden automatikusan fut
- Kiforrott, stabil és széles körben használt könyvtár

</div>

Így elfelejthetjük ezeket az ismerős kódblokkokat:

```php
require_once 'Utils/Page.php';
require_once 'Utils/Style.php';
require_once 'Utils/Paginator.php';
//...
```


Telepítés .[#toc-installation]
------------------------------

A RobotLoader egyetlen önálló fájlként [letölthető `RobotLoader.php` |https://github.com/nette/robot-loader/raw/standalone/src/RobotLoader/RobotLoader.php], amelyet a `require` segítségével a szkriptjébe illeszthet, és azonnal élvezheti az egész alkalmazás kényelmes automatikus betöltését.

```php
require '/path/to/RobotLoader.php';

$loader = new Nette\Loaders\RobotLoader;
//...
```

Ha [Composer |best-practices:composer] segítségével építesz alkalmazást, akkor telepítheted a:

```shell
composer require nette/robot-loader
```


Használat .[#toc-usage]
-----------------------

Hasonlóan ahhoz, ahogyan a Google robot feltérképezi és indexeli a weboldalakat, a [RobotLoader |api:Nette\Loaders\RobotLoader] végigmegy az összes PHP szkripten, és megjegyzi, hogy milyen osztályokat, interfészeket, tulajdonságokat és enumokat talált. Ezután az eredményeket a gyorsítótárban tárolja, hogy a későbbi lekérdezések során felhasználhassa. Csak azt kell megadni, hogy mely könyvtárakon menjen keresztül, és hol tárolja a gyorsítótárat:

```php
$loader = new Nette\Loaders\RobotLoader;

// A RobotLoader által indexelendő könyvtárak (beleértve az alkönyvtárakat is)
$loader->addDirectory(__DIR__ . '/app');
$loader->addDirectory(__DIR__ . '/libs');

// A gyorsítótárazást a 'temp' könyvtárra állítsa be
$loader->setTempDirectory(__DIR__ . '/temp');
$loader->register(); // RobotLoader aktiválása
```

És ennyi, innentől kezdve nem kell használnunk a `require` címet. Félelmetes!

Ha a RobotLoader az indexelés során duplikált osztálynévvel találkozik, akkor kivételt dob és értesítést küld. A RobotLoader automatikusan frissíti a gyorsítótárat is, ha egy ismeretlen osztályt kell betöltenie. Javasoljuk, hogy ezt kapcsolja ki a termelő szervereken, lásd [Cache |#Caching].

Ha azt szeretné, hogy a RobotLoader kihagyjon bizonyos könyvtárakat, használja a `$loader->excludeDirectory('temp')` címet (többször is hívható, vagy több könyvtárat is átadhat).

Alapértelmezés szerint a RobotLoader a PHP-fájlok hibáit a `ParseError` kivétel dobásával jelzi. Ez a `$loader->reportParseErrors(false)` használatával elnyomható.


Nette alkalmazás .[#toc-nette-application]
------------------------------------------

A Nette alkalmazáson belül, ahol a `$configurator` a `Bootstrap.php` oldalon található, a RobotLoader-t így állíthatja be:

```php
$configurator = new Nette\Bootstrap\Configurator;
//...
$configurator->setTempDirectory(__DIR__ . '/../temp');
$configurator->createRobotLoader()
	->addDirectory(__DIR__)
	->addDirectory(__DIR__ . '/../libs')
	->register();
```


PHP fájlok elemzője .[#toc-php-files-analyzer]
----------------------------------------------

A RobotLoader használható pusztán osztályok, interfészek, tulajdonságok és enumok keresésére PHP fájlokban **az automatikus betöltés funkció használata nélkül** is:

```php
$loader = new Nette\Loaders\RobotLoader;
$loader->addDirectory(__DIR__ . '/app');

// Átvizsgálja a könyvtárakat osztályok/interfészek/traits/enumok után.
$loader->rebuild();

// Visszaadja az osztály => fájlnév párok tömbjét.
$res = $loader->getIndexedClasses();
```

Még ilyen használat esetén is kihasználhatja a gyorsítótárazást. Ez biztosítja, hogy a változatlan fájlok nem lesznek újra beolvasva:

```php
$loader = new Nette\Loaders\RobotLoader;
$loader->addDirectory(__DIR__ . '/app');

// A gyorsítótár beállítása a 'temp' könyvtárba
$loader->setTempDirectory(__DIR__ . '/temp');

// Könyvtárak keresése a gyorsítótár segítségével
$loader->refresh();

// Visszaadja az osztály => fájlnév párok tömbjét.
$res = $loader->getIndexedClasses();
```


Caching .[#toc-caching]
-----------------------

A RobotLoader nagyon gyors, mert okosan használja a gyorsítótárazást.

A fejlesztés során alig észrevehető, hogy a háttérben fut. Folyamatosan frissíti a gyorsítótárát, figyelembe véve, hogy osztályok és fájlok hozhatók létre, törölhetők, átnevezhetők stb. És nem vizsgálja újra a változatlan fájlokat.

Egy termelő szerveren viszont ajánlott kikapcsolni a gyorsítótár frissítését a `$loader->setAutoRefresh(false)` segítségével (egy Nette alkalmazásban ez automatikusan megtörténik), mivel a fájlok nem változnak. Ugyanakkor egy új verzió tárhelyre történő feltöltésekor **tisztítani kell a gyorsítótárat**.

A kezdeti fájlszkennelés, amikor a gyorsítótár még nem létezik, nagyobb alkalmazásoknál természetesen eltarthat egy pillanatig. A RobotLoader beépített megelőzéssel rendelkezik a "cache stampede":https://en.wikipedia.org/wiki/Cache_stampede ellen.
Ez az a helyzet, amikor egy termelő szerveren nagyszámú egyidejű kérés indítaná el a RobotLoader-t, és mivel a gyorsítótár még nem létezik, mindegyik elkezdené a fájlok beolvasását, ami túlterhelné a szervert.
Szerencsére a RobotLoader úgy működik, hogy csak az első szál indexeli a fájlokat, létrehozza a gyorsítótárat, a többi pedig vár, majd használja a gyorsítótárat.


PSR-4 .[#toc-psr-4]
-------------------

Manapság a [Composert |best-practices:composer#autoloading] használhatja [automatikus betöltésre |best-practices:composer#autoloading], miközben betartja a PSR-4-et. Egyszerűen fogalmazva, ez egy olyan rendszer, ahol a névterek és az osztályok nevei megfelelnek a könyvtárszerkezetnek és a fájlneveknek, pl. a `App\Core\RouterFactory` a `/path/to/App/Core/RouterFactory.php` fájlban lesz.

A RobotLoader nem kötődik semmilyen rögzített struktúrához, így hasznos olyan helyzetekben, amikor nem akarjuk, hogy a könyvtárstruktúra pontosan úgy legyen kialakítva, mint a PHP névterek, vagy amikor olyan alkalmazást fejlesztünk, amely történetileg nem használ ilyen konvenciókat. Az is lehetséges, hogy mindkét betöltőt együtt használjuk.


{{leftbar: nette:@menu-topics}}

RobotLoader: Osztály automatikus betöltése

A RobotLoader egy olyan eszköz, amely kényelmet biztosít az automatikus osztálybetöltés számára a teljes alkalmazásod számára, beleértve a harmadik féltől származó könyvtárakat is.

  • Megszünteti az összes require utasítást
  • Csak a szükséges szkriptek töltődnek be
  • Nem igényel szigorú elnevezési konvenciókat a könyvtárak vagy fájlok számára
  • Rendkívül gyors
  • Nincs manuális gyorsítótár frissítés, minden automatikusan fut
  • Kiforrott, stabil és széles körben használt könyvtár

Így elfelejthetjük ezeket az ismerős kódblokkokat:

require_once 'Utils/Page.php';
require_once 'Utils/Style.php';
require_once 'Utils/Paginator.php';
//...

Telepítés

A RobotLoader egyetlen önálló fájlként letölthető RobotLoader.php, amelyet a require segítségével a szkriptjébe illeszthet, és azonnal élvezheti az egész alkalmazás kényelmes automatikus betöltését.

require '/path/to/RobotLoader.php';

$loader = new Nette\Loaders\RobotLoader;
//...

Ha Composer segítségével építesz alkalmazást, akkor telepítheted a:

composer require nette/robot-loader

Használat

Hasonlóan ahhoz, ahogyan a Google robot feltérképezi és indexeli a weboldalakat, a RobotLoader végigmegy az összes PHP szkripten, és megjegyzi, hogy milyen osztályokat, interfészeket, tulajdonságokat és enumokat talált. Ezután az eredményeket a gyorsítótárban tárolja, hogy a későbbi lekérdezések során felhasználhassa. Csak azt kell megadni, hogy mely könyvtárakon menjen keresztül, és hol tárolja a gyorsítótárat:

$loader = new Nette\Loaders\RobotLoader;

// A RobotLoader által indexelendő könyvtárak (beleértve az alkönyvtárakat is)
$loader->addDirectory(__DIR__ . '/app');
$loader->addDirectory(__DIR__ . '/libs');

// A gyorsítótárazást a 'temp' könyvtárra állítsa be
$loader->setTempDirectory(__DIR__ . '/temp');
$loader->register(); // RobotLoader aktiválása

És ennyi, innentől kezdve nem kell használnunk a require címet. Félelmetes!

Ha a RobotLoader az indexelés során duplikált osztálynévvel találkozik, akkor kivételt dob és értesítést küld. A RobotLoader automatikusan frissíti a gyorsítótárat is, ha egy ismeretlen osztályt kell betöltenie. Javasoljuk, hogy ezt kapcsolja ki a termelő szervereken, lásd Cache.

Ha azt szeretné, hogy a RobotLoader kihagyjon bizonyos könyvtárakat, használja a $loader->excludeDirectory('temp') címet (többször is hívható, vagy több könyvtárat is átadhat).

Alapértelmezés szerint a RobotLoader a PHP-fájlok hibáit a ParseError kivétel dobásával jelzi. Ez a $loader->reportParseErrors(false) használatával elnyomható.

Nette alkalmazás

A Nette alkalmazáson belül, ahol a $configurator a Bootstrap.php oldalon található, a RobotLoader-t így állíthatja be:

$configurator = new Nette\Bootstrap\Configurator;
//...
$configurator->setTempDirectory(__DIR__ . '/../temp');
$configurator->createRobotLoader()
	->addDirectory(__DIR__)
	->addDirectory(__DIR__ . '/../libs')
	->register();

PHP fájlok elemzője

A RobotLoader használható pusztán osztályok, interfészek, tulajdonságok és enumok keresésére PHP fájlokban az automatikus betöltés funkció használata nélkül is:

$loader = new Nette\Loaders\RobotLoader;
$loader->addDirectory(__DIR__ . '/app');

// Átvizsgálja a könyvtárakat osztályok/interfészek/traits/enumok után.
$loader->rebuild();

// Visszaadja az osztály => fájlnév párok tömbjét.
$res = $loader->getIndexedClasses();

Még ilyen használat esetén is kihasználhatja a gyorsítótárazást. Ez biztosítja, hogy a változatlan fájlok nem lesznek újra beolvasva:

$loader = new Nette\Loaders\RobotLoader;
$loader->addDirectory(__DIR__ . '/app');

// A gyorsítótár beállítása a 'temp' könyvtárba
$loader->setTempDirectory(__DIR__ . '/temp');

// Könyvtárak keresése a gyorsítótár segítségével
$loader->refresh();

// Visszaadja az osztály => fájlnév párok tömbjét.
$res = $loader->getIndexedClasses();

Caching

A RobotLoader nagyon gyors, mert okosan használja a gyorsítótárazást.

A fejlesztés során alig észrevehető, hogy a háttérben fut. Folyamatosan frissíti a gyorsítótárát, figyelembe véve, hogy osztályok és fájlok hozhatók létre, törölhetők, átnevezhetők stb. És nem vizsgálja újra a változatlan fájlokat.

Egy termelő szerveren viszont ajánlott kikapcsolni a gyorsítótár frissítését a $loader->setAutoRefresh(false) segítségével (egy Nette alkalmazásban ez automatikusan megtörténik), mivel a fájlok nem változnak. Ugyanakkor egy új verzió tárhelyre történő feltöltésekor tisztítani kell a gyorsítótárat.

A kezdeti fájlszkennelés, amikor a gyorsítótár még nem létezik, nagyobb alkalmazásoknál természetesen eltarthat egy pillanatig. A RobotLoader beépített megelőzéssel rendelkezik a cache stampede ellen. Ez az a helyzet, amikor egy termelő szerveren nagyszámú egyidejű kérés indítaná el a RobotLoader-t, és mivel a gyorsítótár még nem létezik, mindegyik elkezdené a fájlok beolvasását, ami túlterhelné a szervert. Szerencsére a RobotLoader úgy működik, hogy csak az első szál indexeli a fájlokat, létrehozza a gyorsítótárat, a többi pedig vár, majd használja a gyorsítótárat.

PSR-4

Manapság a Composert használhatja automatikus betöltésre, miközben betartja a PSR-4-et. Egyszerűen fogalmazva, ez egy olyan rendszer, ahol a névterek és az osztályok nevei megfelelnek a könyvtárszerkezetnek és a fájlneveknek, pl. a App\Core\RouterFactory a /path/to/App/Core/RouterFactory.php fájlban lesz.

A RobotLoader nem kötődik semmilyen rögzített struktúrához, így hasznos olyan helyzetekben, amikor nem akarjuk, hogy a könyvtárstruktúra pontosan úgy legyen kialakítva, mint a PHP névterek, vagy amikor olyan alkalmazást fejlesztünk, amely történetileg nem használ ilyen konvenciókat. Az is lehetséges, hogy mindkét betöltőt együtt használjuk.