Nette Documentation Preview

syntax
RobotLoader: Автоматично зареждане на класове
*********************************************

<div class=perex>

RobotLoader е инструмент, който ви дава възможност за автоматизирано зареждане на класове за цялото ви приложение, включително библиотеки на трети страни.

- Елиминирайте всички изявления `require`
- Ще бъдат заредени само необходимите скриптове
- Не изисква строги конвенции за именуване на директории или файлове
- Изключително бързо
- Няма ръчни актуализации на кеша, всичко се изпълнява автоматично
- Зряла, стабилна и широко използвана библиотека

</div>

Така можем да забравим за тези познати блокове код:

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


Инсталация .[#toc-installation]
-------------------------------

Можете да изтеглите RobotLoader като [един самостоятелен файл `RobotLoader.php` |https://github.com/nette/robot-loader/raw/standalone/src/RobotLoader/RobotLoader.php], който да включите с помощта на `require` в скрипта си, и веднага да се насладите на удобно автоматично зареждане за цялото приложение.

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

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

Ако изграждате приложение с помощта на [Composer |best-practices:composer], можете да го инсталирате чрез:

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


Употреба .[#toc-usage]
----------------------

Подобно на начина, по който роботът на Google обхожда и индексира уеб страници, [RobotLoader |api:Nette\Loaders\RobotLoader] преминава през всички PHP скриптове и отбелязва кои класове, интерфейси, черти и енуми е намерил. След това той съхранява резултатите в кеш за използване при следващи заявки. Необходимо е само да посочите кои директории трябва да прегледа и къде да се съхранява кешът:

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

// Директории, които RobotLoader да индексира (включително поддиректории)
$loader->addDirectory(__DIR__ . '/app');
$loader->addDirectory(__DIR__ . '/libs');

// Задаване на кеширане в директорията 'temp'
$loader->setTempDirectory(__DIR__ . '/temp');
$loader->register(); // Активиране на RobotLoader
```

И това е всичко, от този момент нататък не е необходимо да използваме `require`. Страхотно!

Ако RobotLoader срещне дублиращо се име на клас по време на индексирането, той ще хвърли изключение и ще ви уведоми. RobotLoader също така автоматично актуализира кеша, когато трябва да зареди непознат клас. Препоръчваме да изключите тази функция на производствени сървъри, вижте " [Кеширане" |#Caching].

Ако искате RobotLoader да прескача определени директории, използвайте `$loader->excludeDirectory('temp')` (може да се извика многократно или да се предадат няколко директории).

По подразбиране RobotLoader съобщава за грешки в PHP файлове, като хвърля изключение `ParseError`. Това може да се потисне с помощта на `$loader->reportParseErrors(false)`.


Нетно приложение .[#toc-nette-application]
------------------------------------------

Вътре в Nette Application, където `$configurator` се използва в `Bootstrap.php`, можете да настроите RobotLoader по този начин:

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


Анализатор на PHP файлове .[#toc-php-files-analyzer]
----------------------------------------------------

RobotLoader може да се използва и само за намиране на класове, интерфейси, черти и енуми в PHP файлове, без да се използва функцията за автоматично зареждане:

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

// Търсене на директории за класове/интерфейси/характеристики/енуми
$loader->rebuild();

// Връща масив от двойки клас => име на файл
$res = $loader->getIndexedClasses();
```

Дори при такава употреба можете да използвате кеширане. Това гарантира, че непроменените файлове няма да бъдат сканирани отново:

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

// Задаване на кеширане в директорията 'temp'
$loader->setTempDirectory(__DIR__ . '/temp');

// Претърсване на директориите с помощта на кеша
$loader->refresh();

// Връща масив от двойки клас => име на файл
$res = $loader->getIndexedClasses();
```


Кеширане .[#toc-caching]
------------------------

RobotLoader е много бърз, защото умело използва кеширане.

По време на разработката почти не забелязвате, че той работи във фонов режим. Той непрекъснато обновява кеша си, като се има предвид, че класовете и файловете могат да бъдат създавани, изтривани, преименувани и т.н. И не сканира отново непроменените файлове.

В производствен сървър, от друга страна, препоръчваме да изключите обновяването на кеша с помощта на `$loader->setAutoRefresh(false)` (в приложение на Nette това става автоматично), тъй като файловете не се променят. В същото време е необходимо **изчистване на кеша** при качване на нова версия на хостинг.

Първоначалното сканиране на файловете, когато кешът все още не съществува, естествено може да отнеме известно време за по-големи приложения. RobotLoader разполага с вградена превенция срещу "прецакване на кеша:https://en.wikipedia.org/wiki/Cache_stampede".
Това е ситуация, при която голям брой едновременни заявки на производствен сървър ще задействат RobotLoader и тъй като кешът все още не съществува, всички те ще започнат да сканират файлове, което ще претовари сървъра.
За щастие RobotLoader работи по такъв начин, че само първата нишка индексира файловете, създава кеша, а останалите изчакват и след това използват кеша.


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

В днешно време можете да използвате [Composer за автоматично зареждане |best-practices:composer#autoloading], като се придържате към PSR-4. Казано по-просто, това е система, при която пространствата от имена и имената на класовете съответстват на структурата на директориите и имената на файловете, например `App\Core\RouterFactory` ще бъде във файла `/path/to/App/Core/RouterFactory.php`.

RobotLoader не е обвързан с никаква фиксирана структура, така че е полезен в ситуации, в които не искате структурата на директорията да е проектирана точно като пространствата от имена на PHP, или когато разработвате приложение, което исторически не използва такива конвенции. Възможно е също така да се използват и двата зареждащи механизма заедно.


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

RobotLoader: Автоматично зареждане на класове

RobotLoader е инструмент, който ви дава възможност за автоматизирано зареждане на класове за цялото ви приложение, включително библиотеки на трети страни.

  • Елиминирайте всички изявления require
  • Ще бъдат заредени само необходимите скриптове
  • Не изисква строги конвенции за именуване на директории или файлове
  • Изключително бързо
  • Няма ръчни актуализации на кеша, всичко се изпълнява автоматично
  • Зряла, стабилна и широко използвана библиотека

Така можем да забравим за тези познати блокове код:

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

Инсталация

Можете да изтеглите RobotLoader като един самостоятелен файл RobotLoader.php, който да включите с помощта на require в скрипта си, и веднага да се насладите на удобно автоматично зареждане за цялото приложение.

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

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

Ако изграждате приложение с помощта на Composer, можете да го инсталирате чрез:

composer require nette/robot-loader

Употреба

Подобно на начина, по който роботът на Google обхожда и индексира уеб страници, RobotLoader преминава през всички PHP скриптове и отбелязва кои класове, интерфейси, черти и енуми е намерил. След това той съхранява резултатите в кеш за използване при следващи заявки. Необходимо е само да посочите кои директории трябва да прегледа и къде да се съхранява кешът:

$loader = new Nette\Loaders\RobotLoader;

// Директории, които RobotLoader да индексира (включително поддиректории)
$loader->addDirectory(__DIR__ . '/app');
$loader->addDirectory(__DIR__ . '/libs');

// Задаване на кеширане в директорията 'temp'
$loader->setTempDirectory(__DIR__ . '/temp');
$loader->register(); // Активиране на RobotLoader

И това е всичко, от този момент нататък не е необходимо да използваме require. Страхотно!

Ако RobotLoader срещне дублиращо се име на клас по време на индексирането, той ще хвърли изключение и ще ви уведоми. RobotLoader също така автоматично актуализира кеша, когато трябва да зареди непознат клас. Препоръчваме да изключите тази функция на производствени сървъри, вижте " Кеширане".

Ако искате RobotLoader да прескача определени директории, използвайте $loader->excludeDirectory('temp') (може да се извика многократно или да се предадат няколко директории).

По подразбиране RobotLoader съобщава за грешки в PHP файлове, като хвърля изключение ParseError. Това може да се потисне с помощта на $loader->reportParseErrors(false).

Нетно приложение

Вътре в Nette Application, където $configurator се използва в Bootstrap.php, можете да настроите RobotLoader по този начин:

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

Анализатор на PHP файлове

RobotLoader може да се използва и само за намиране на класове, интерфейси, черти и енуми в PHP файлове, без да се използва функцията за автоматично зареждане:

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

// Търсене на директории за класове/интерфейси/характеристики/енуми
$loader->rebuild();

// Връща масив от двойки клас => име на файл
$res = $loader->getIndexedClasses();

Дори при такава употреба можете да използвате кеширане. Това гарантира, че непроменените файлове няма да бъдат сканирани отново:

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

// Задаване на кеширане в директорията 'temp'
$loader->setTempDirectory(__DIR__ . '/temp');

// Претърсване на директориите с помощта на кеша
$loader->refresh();

// Връща масив от двойки клас => име на файл
$res = $loader->getIndexedClasses();

Кеширане

RobotLoader е много бърз, защото умело използва кеширане.

По време на разработката почти не забелязвате, че той работи във фонов режим. Той непрекъснато обновява кеша си, като се има предвид, че класовете и файловете могат да бъдат създавани, изтривани, преименувани и т.н. И не сканира отново непроменените файлове.

В производствен сървър, от друга страна, препоръчваме да изключите обновяването на кеша с помощта на $loader->setAutoRefresh(false) (в приложение на Nette това става автоматично), тъй като файловете не се променят. В същото време е необходимо изчистване на кеша при качване на нова версия на хостинг.

Първоначалното сканиране на файловете, когато кешът все още не съществува, естествено може да отнеме известно време за по-големи приложения. RobotLoader разполага с вградена превенция срещу „прецакване на кеша:https://en.wikipedia.org/…che_stampede“. Това е ситуация, при която голям брой едновременни заявки на производствен сървър ще задействат RobotLoader и тъй като кешът все още не съществува, всички те ще започнат да сканират файлове, което ще претовари сървъра. За щастие RobotLoader работи по такъв начин, че само първата нишка индексира файловете, създава кеша, а останалите изчакват и след това използват кеша.

PSR-4

В днешно време можете да използвате Composer за автоматично зареждане, като се придържате към PSR-4. Казано по-просто, това е система, при която пространствата от имена и имената на класовете съответстват на структурата на директориите и имената на файловете, например App\Core\RouterFactory ще бъде във файла /path/to/App/Core/RouterFactory.php.

RobotLoader не е обвързан с никаква фиксирана структура, така че е полезен в ситуации, в които не искате структурата на директорията да е проектирана точно като пространствата от имена на PHP, или когато разработвате приложение, което исторически не използва такива конвенции. Възможно е също така да се използват и двата зареждащи механизма заедно.