RobotLoader: Class Autoloading
RobotLoader is a tool that gives you comfort of automated class loading for your entire application including third-party libraries.
- Eliminate all
require
statements - Only necessary scripts will be loaded
- Doesn't require strict naming conventions for directories or files
- Extremely fast
- No manual cache updates, everything runs automatically
- Mature, stable and widely used library
Thus, we can forget about these familiar code blocks:
require_once 'Utils/Page.php';
require_once 'Utils/Style.php';
require_once 'Utils/Paginator.php';
// ...
Installation
You can download RobotLoader as a single standalone file
RobotLoader.php
, which you include using require
in your script, and instantly enjoy comfortable
autoloading for the entire application.
require '/path/to/RobotLoader.php';
$loader = new Nette\Loaders\RobotLoader;
// ...
If you're building an application using Composer, you can install it via:
composer require nette/robot-loader
Usage
Similar to how the Google robot crawls and indexes web pages, the RobotLoader goes through all PHP scripts and notes which classes, interfaces, traits and enums it found. It then stores the results in cache for use in subsequent requests. You just need to specify which directories it should go through and where to store the cache:
$loader = new Nette\Loaders\RobotLoader;
// Directories for RobotLoader to index (including subdirectories)
$loader->addDirectory(__DIR__ . '/app');
$loader->addDirectory(__DIR__ . '/libs');
// Set caching to the 'temp' directory
$loader->setTempDirectory(__DIR__ . '/temp');
$loader->register(); // Activate RobotLoader
And that's it, from this point on, we don't need to use require
. Awesome!
If RobotLoader encounters a duplicate class name during indexing, it will throw an exception and notify you. RobotLoader also automatically updates the cache when it needs to load an unknown class. We recommend turning this off on production servers, see Caching.
If you want RobotLoader to skip certain directories, use $loader->excludeDirectory('temp')
(can be called
multiple times or pass multiple directories).
By default, RobotLoader reports errors in PHP files by throwing a ParseError
exception. This can be suppressed
using $loader->reportParseErrors(false)
.
Nette Application
Inside Nette Application, where $configurator
is used in Bootstrap.php
, you can setup RobotLoader
this way:
$configurator = new Nette\Bootstrap\Configurator;
// ...
$configurator->setTempDirectory(__DIR__ . '/../temp');
$configurator->createRobotLoader()
->addDirectory(__DIR__)
->addDirectory(__DIR__ . '/../libs')
->register();
PHP Files Analyzer
RobotLoader can also be used purely for finding classes, interfaces, traits and enums in PHP files without using the autoloading function:
$loader = new Nette\Loaders\RobotLoader;
$loader->addDirectory(__DIR__ . '/app');
// Scans directories for classes/interfaces/traits/enums
$loader->rebuild();
// Returns an array of class => filename pairs
$res = $loader->getIndexedClasses();
Even with such usage, you can utilize caching. This ensures that unchanged files won't be rescanned:
$loader = new Nette\Loaders\RobotLoader;
$loader->addDirectory(__DIR__ . '/app');
// Set caching to the 'temp' directory
$loader->setTempDirectory(__DIR__ . '/temp');
// Scans directories using cache
$loader->refresh();
// Returns an array of class => filename pairs
$res = $loader->getIndexedClasses();
Caching
RobotLoader is very fast because it cleverly uses caching.
During development, you hardly notice it running in the background. It continuously updates its cache, considering that classes and files can be created, deleted, renamed, etc. And it doesn't rescan unchanged files.
On a production server, on the other hand, we recommend turning off cache updates using
$loader->setAutoRefresh(false)
(in a Nette Application, this happens automatically), because files don't change.
At the same time, it's necessary to clear the cache when uploading a new version to hosting.
The initial file scanning, when the cache doesn't exist yet, can naturally take a moment for larger applications. RobotLoader has built-in prevention against cache stampede. This is a situation where a large number of concurrent requests on a production server would trigger RobotLoader, and since the cache doesn't exist yet, they would all start scanning files, which would overload the server. Fortunately, RobotLoader works in such a way that only the first thread indexes the files, creates the cache, and the rest wait and then use the cache.
PSR-4
Nowadays, you can use Composer for autoloading while adhering to
PSR-4. Simply put, it's a system where namespaces and class names correspond to the directory structure and file names, e.g.,
App\Core\RouterFactory
will be in the file /path/to/App/Core/RouterFactory.php
.
RobotLoader isn't tied to any fixed structure, so it's useful in situations where you don't want to have the directory structure designed exactly like the PHP namespaces, or when developing an application that historically doesn't use such conventions. It's also possible to use both loaders together.