RobotLoader: Class Autoloading

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, include it 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, RobotLoader traverses all PHP scripts and records which classes, interfaces, traits, and enums it found. It then stores these findings in a cache and uses them for subsequent requests. You just need to specify which directories it should scan 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, you 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 a class it doesn't know. We recommend disabling this 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 a Nette Application, where the $configurator object is used in the Bootstrap.php boot file, the setup can be simplified:

$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, anticipating that classes and files might be created, deleted, renamed, etc. And it doesn't rescan files that haven't changed.

On a production server, conversely, we recommend disabling cache updates using $loader->setAutoRefresh(false) (this happens automatically in a Nette Application), because files don't change. At the same time, it's necessary to clear the cache when uploading a new version to the hosting environment.

The initial scanning of files, 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 trigger RobotLoader, and since the cache doesn't exist yet, they would all start scanning files, potentially overloading the server. Fortunately, RobotLoader works such that with multiple concurrent requests, only the first thread indexes the files and creates the cache, while the others wait and then use the generated 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 the directory structure to exactly match the PHP namespaces, or when developing an application that historically doesn't use such conventions. It's also possible to use both loaders together.