| 1 |
RobotLoader: comfortable autoloading |
| 2 |
==================================== |
| 3 |
|
| 4 |
[](https://packagist.org/packages/nette/robot-loader](https://packagist.org/packages/nette/robot-loader](https://packagist.org/packages/nette/robot-loader) |
| 5 |
[](https://github.com/nette/robot-loader/actions](https://github.com/nette/robot-loader/actions](https://github.com/nette/robot-loader/actions) |
| 6 |
[](https://coveralls.io/github/nette/robot-loader?branch=master](https://coveralls.io/github/nette/robot-loader?branch=master](https://coveralls.io/github/nette/robot-loader?branch=master) |
| 7 |
[](https://github.com/nette/robot-loader/releases](https://github.com/nette/robot-loader/releases](https://github.com/nette/robot-loader/releases) |
| 8 |
[](https://github.com/nette/robot-loader/blob/master/license.md](https://github.com/nette/robot-loader/blob/master/license.md](https://github.com/nette/robot-loader/blob/master/license.md) |
| 9 |
|
| 10 |
|
| 11 |
Introduction |
| 12 |
------------ |
| 13 |
|
| 14 |
RobotLoader is a tool that gives you comfort of automated class loading for your entire application including third-party libraries. |
| 15 |
|
| 16 |
- get rid of all `require` |
| 17 |
- does not require strict directory or file naming conventions |
| 18 |
- extremely fast |
| 19 |
- no manual cache updates, everything runs automatically |
| 20 |
- highly mature, stable and widely used library |
| 21 |
|
| 22 |
So we can forget about those famous code blocks: |
| 23 |
|
| 24 |
```php |
| 25 |
require_once 'Utils/Page.php'; |
| 26 |
require_once 'Utils/Style.php'; |
| 27 |
require_once 'Utils/Paginator.php'; |
| 28 |
... |
| 29 |
``` |
| 30 |
|
| 31 |
[](https://github.com/sponsors/dgSupport Me](https://github.com/sponsors/dg](https://github.com/sponsors/dg) |
| 32 |
-------------------------------------------- |
| 33 |
|
| 34 |
Do you like RobotLoader? Are you looking forward to the new features? |
| 35 |
|
| 36 |
[](https://github.com/sponsors/dg](https://github.com/sponsors/dg](https://github.com/sponsors/dg) |
| 37 |
|
| 38 |
Thank you! |
| 39 |
|
| 40 |
|
| 41 |
Installation |
| 42 |
------------ |
| 43 |
|
| 44 |
The recommended way to install is via Composer: |
| 45 |
|
| 46 |
```shell |
| 47 |
composer require nette/robot-loader |
| 48 |
``` |
| 49 |
|
| 50 |
It requires PHP version 7.1 and supports PHP up to 8.0. |
| 51 |
|
| 52 |
|
| 53 |
Usage |
| 54 |
----- |
| 55 |
|
| 56 |
Like the Google robot crawls and indexes websites, [](https://api.nette.org/3.0/Nette/Loaders/RobotLoader.htmlRobotLoader](https://api.nette.org/3.0/Nette/Loaders/RobotLoader.html](https://api.nette.org/3.0/Nette/Loaders/RobotLoader.html) crawls all PHP scripts and records what classes and interfaces were found in them. These records are then saved in cache and used during all subsequent requests. You just need to specify what directories to index and where to save the cache: |
| 57 |
|
| 58 |
```php |
| 59 |
$loader = new \Packetery\Nette\Loaders\RobotLoader; |
| 60 |
|
| 61 |
// directories to be indexed by RobotLoader (including subdirectories) |
| 62 |
$loader->addDirectory(__DIR__ . '/app'); |
| 63 |
$loader->addDirectory(__DIR__ . '/libs'); |
| 64 |
|
| 65 |
// use 'temp' directory for cache |
| 66 |
$loader->setTempDirectory(__DIR__ . '/temp'); |
| 67 |
$loader->register(); // Run the RobotLoader |
| 68 |
``` |
| 69 |
|
| 70 |
And that's all. From now on, you don't need to use `require`. Great, isn't it? |
| 71 |
|
| 72 |
When RobotLoader encounters duplicate class name during indexing, it throws an exception and informs you about it. RobotLoader also automatically updates the cache when it has to load a class it doesn't know. We recommend disabling this on production servers, see [Caching](#Caching). |
| 73 |
|
| 74 |
If you want RobotLoader to skip some directories, use `$loader->excludeDirectory('temp')` (it can be called multiple times or you can pass multiple directories). |
| 75 |
|
| 76 |
By default, RobotLoader reports errors in PHP files by throwing exception `ParseError`. It can be disabled via `$loader->reportParseErrors(false)`. |
| 77 |
|
| 78 |
|
| 79 |
PHP Files Analyzer |
| 80 |
------------------ |
| 81 |
|
| 82 |
RobotLoader can also be used purely to find classes, interfaces, and trait in PHP files **without** using the autoloading feature: |
| 83 |
|
| 84 |
```php |
| 85 |
$loader = new \Packetery\Nette\Loaders\RobotLoader; |
| 86 |
$loader->addDirectory(__DIR__ . '/app'); |
| 87 |
|
| 88 |
// Scans directories for classes / intefaces / traits |
| 89 |
$loader->rebuild(); |
| 90 |
|
| 91 |
// Returns array of class => filename pairs |
| 92 |
$res = $loader->getIndexedClasses(); |
| 93 |
``` |
| 94 |
|
| 95 |
Even with such use, you can use the cache. As a result, unmodified files will not be repeatedly analyzed when rescanning: |
| 96 |
|
| 97 |
```php |
| 98 |
$loader = new \Packetery\Nette\Loaders\RobotLoader; |
| 99 |
$loader->addDirectory(__DIR__ . '/app'); |
| 100 |
$loader->setTempDirectory(__DIR__ . '/temp'); |
| 101 |
|
| 102 |
// Scans directories using a cache |
| 103 |
$loader->refresh(); |
| 104 |
|
| 105 |
// Returns array of class => filename pairs |
| 106 |
$res = $loader->getIndexedClasses(); |
| 107 |
``` |
| 108 |
|
| 109 |
Caching |
| 110 |
------- |
| 111 |
|
| 112 |
RobotLoader is very fast because it cleverly uses the cache. |
| 113 |
|
| 114 |
When developing with it, you have practically no idea that it runs on the background. It continuously updates the cache because it knows that classes and files can be created, deleted, renamed, etc. And it doesn't repeatedly scan unmodified files. |
| 115 |
|
| 116 |
When used on a production server, on the other hand, we recommend disabling the cache update using `$loader->setAutoRefresh(false)`, because the files are not changing. At the same time, it is necessary to **clear the cache** when uploading a new version on the hosting. |
| 117 |
|
| 118 |
Of course, the initial scanning of files, when the cache does not already exist, may take a few seconds for larger applications. RobotLoader has built-in prevention against [](https://en.wikipedia.org/wiki/Cache_stampedecache stampede](https://en.wikipedia.org/wiki/Cache_stampede](https://en.wikipedia.org/wiki/Cache_stampede). |
| 119 |
This is a situation where production server receives a large number of concurrent requests and because RobotLoader's cache does not yet exist, they would all start scanning the files. Which spikes CPU and filesystem usage. |
| 120 |
Fortunately, RobotLoader works in such a way that for multiple concurrent requests, only the first thread indexes the files, creates a cache, the others wait, and then use the cache. |
| 121 |
|
| 122 |
|
| 123 |
PSR-4 |
| 124 |
----- |
| 125 |
|
| 126 |
Today, Composer can be used for autoloading in compliance with PSR-4. Simply saying, it is a system where the namespaces and class names correspond to the directory structure and file names, ie `App\Router\RouterFactory` is located in the file `/path/to/App/Router/RouterFactory.php`. |
| 127 |
|
| 128 |
RobotLoader is not tied to any fixed structure, therefore, it is useful in situations where it does not suit you to have the directory structure designed as namespaces in PHP, or when you are developing an application that has historically not used such conventions. It is also possible to use both loaders together. |
| 129 |
|
| 130 |
|
| 131 |
If you like RobotLoader, **[](https://nette.org/donateplease make a donation now](https://nette.org/donate](https://nette.org/donate)**. Thank you! |
| 132 |
|
