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


Додаток Nette .[#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 Application це відбувається автоматично), оскільки файли не змінюються. У той же час, необхідно **очищати кеш** при завантаженні нової версії на хостинг.

Початкове сканування файлів, коли кеш ще не існує, може зайняти деякий час для великих додатків. RobotLoader має вбудований захист від "переповнення кешу":https://en.wikipedia.org/wiki/Cache_stampede.
Це ситуація, коли велика кількість одночасних запитів на робочому сервері запускає RobotLoader, і оскільки кеш ще не існує, всі вони починають сканувати файли, що призводить до перевантаження сервера.
На щастя, RobotLoader працює таким чином, що тільки перший потік індексує файли, створює кеш, а решта чекають і потім використовують кеш.


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

Сьогодні ви можете використовувати [Composer для автозавантаження |best-practices:composer#autoloading], дотримуючись PSR-4. Простіше кажучи, це система, де простори імен та імена класів відповідають структурі каталогів та іменам файлів, наприклад, `App\Router\RouterFactory` буде у файлі `/path/to/App/Router/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

Усередині 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 Application це відбувається автоматично), оскільки файли не змінюються. У той же час, необхідно очищати кеш при завантаженні нової версії на хостинг.

Початкове сканування файлів, коли кеш ще не існує, може зайняти деякий час для великих додатків. RobotLoader має вбудований захист від переповнення кешу. Це ситуація, коли велика кількість одночасних запитів на робочому сервері запускає RobotLoader, і оскільки кеш ще не існує, всі вони починають сканувати файли, що призводить до перевантаження сервера. На щастя, RobotLoader працює таким чином, що тільки перший потік індексує файли, створює кеш, а решта чекають і потім використовують кеш.

PSR-4

Сьогодні ви можете використовувати Composer для автозавантаження, дотримуючись PSR-4. Простіше кажучи, це система, де простори імен та імена класів відповідають структурі каталогів та іменам файлів, наприклад, App\Router\RouterFactory буде у файлі /path/to/App/Router/RouterFactory.php.

RobotLoader не прив'язаний до будь-якої фіксованої структури, тому він корисний у ситуаціях, коли ви не хочете, щоб структура каталогів була розроблена точно так само, як простори імен PHP, або коли ви розробляєте програму, яка історично не використовує такі домовленості. Також можна використовувати обидва завантажувачі разом.