Nette RobotLoader
*****************

<div class=perex>

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

- Избавляет от всех выражений `require`
- Загружаются только нужные скрипты
- Не требует строгих соглашений об именовании каталогов и файлов
- Чрезвычайно быстрый
- Никакого ручного обновления кеша, всё происходит автоматически
- Зрелая, стабильная и широко используемая библиотека

</div>

Так что мы можем забыть об этих знакомых блоках кода:

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


Установка
---------

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
```


Использование
-------------

Подобно тому как робот 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 также автоматически обновляет кеш, когда ему нужно загрузить класс, о котором он не знает. На боевых серверах мы рекомендуем это отключать, см. [#Кеширование].

Если вы хотите, чтобы RobotLoader пропускал определённые каталоги, используйте `$loader->excludeDirectory('temp')` (можно вызывать несколько раз или передать несколько каталогов).

По умолчанию RobotLoader просматривает только файлы с расширением `.php`. Чтобы индексировать и другие типы файлов, поправьте свойство `$acceptFiles`, содержащее массив масок:

```php
$loader->acceptFiles = ['*.php', '*.inc'];
```

Свойство `$ignoreDirs` точно так же содержит маски каталогов, которые при просмотре всегда пропускаются (по умолчанию `.*`, `*.old`, `*.bak`, `*.tmp`, `temp`).

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

Под капотом `register()` встраивает метод `tryLoad()` в цепочку автозагрузки PHP. Всякий раз, когда PHP нужен неизвестный класс, интерфейс, трейт или перечисление, он передаёт имя в `$loader->tryLoad($type)`, который находит подходящий файл и подключает его.


Nette Application
-----------------

Внутри Nette Application, где в загрузочном файле `Bootstrap.php` используется объект `$configurator`, настройку можно упростить:

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


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

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();
```


Кеширование
-----------

RobotLoader очень быстрый, потому что умно использует кеш.

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

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

Первоначальный просмотр файлов, когда кеша ещё нет, для более крупных приложений, естественно, может занять некоторое время. У RobotLoader есть встроенная защита от [cache stampede|https://en.wikipedia.org/wiki/Cache_stampede]. Это ситуация, когда большое количество одновременных запросов на боевом сервере запускает RobotLoader, и поскольку кеша ещё нет, все они начали бы просматривать файлы и могли бы перегрузить сервер. К счастью, RobotLoader работает так, что при нескольких одновременных запросах файлы индексирует и создаёт кеш только первый поток, а остальные ждут и затем используют порождённый кеш.


PSR-4
-----

Сегодня для автозагрузки можно использовать [Composer |best-practices:composer#Автозагрузка], придерживаясь PSR-4. Проще говоря, это система, в которой пространства имён и имена классов соответствуют структуре каталогов и именам файлов: например, `App\Core\RouterFactory` будет в файле `/path/to/App/Core/RouterFactory.php`.

RobotLoader не привязан к какой-либо жёсткой структуре, поэтому он полезен в ситуациях, когда вы не хотите, чтобы структура каталогов точно соответствовала пространствам имён PHP, или когда вы разрабатываете приложение, которое исторически таких соглашений не придерживается. Оба загрузчика можно использовать и вместе.


Если вы переходите на более новую версию, посмотрите страницу [обновления |upgrading].


{{sitename: Документация Nette}}