RobotLoader: the autoloader that crawls your PHP files and caches the index

A crawler for your class files

The mechanism is best understood through the analogy the README uses. Just as the Google robot crawls and indexes web pages, RobotLoader goes through all PHP scripts and notes which classes, interfaces, traits and enums it found, then stores the results in cache for use in subsequent requests. What you get in exchange is a set of familiar code blocks you no longer need, the require_once lines for Utils/Page.php, Utils/Style.php and Utils/Paginator.php that every older PHP project accumulates. The listed benefits follow from the indexing model. You get rid of all require calls, and you do not require strict naming conventions for directories or files, because the index is built by reading the code rather than by translating a namespace into a path. There are no manual cache updates, everything runs automatically, and the README calls it a mature, stable and widely used library. The audience is PHP developers working on applications whose structure predates or ignores PSR-4, and it is part of the wider Nette ecosystem.

One file, or Composer

Installation comes in two forms, and the first one is unusual enough to be the reason to know about this library. RobotLoader can be downloaded as a single standalone file, RobotLoader.php, which you include using require in your script and you immediately have autoloading for the entire application:

require '/path/to/RobotLoader.php';

$loader = new Nette\Loaders\RobotLoader;
// ...

That means a project with no dependency manager at all can still use it, and the deployment story is a single copied file. If you are building with Composer, the install is the usual one line:

composer require nette/robot-loader

The version support is explicit, since the library requires PHP version 8.1 and supports PHP up to 8.5. The licence is a New BSD licence according to the badge in the README, and while GitHub records the licence field for this repository as a custom licence it cannot classify, the authoritative text is in the license.md file at the root. That is a good pattern to follow generally, since the badge and the repository metadata do not always agree, and the file is what you would read before shipping it in a product.

Three calls to configure it

The configuration is short enough to read in one go, and every part of it maps to a decision you have to make. You create the loader, you list the directories it should index including subdirectories, you choose where the cache lives, and you activate it:

$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->setCacheDirectory(__DIR__ . '/temp');
$loader->register(); // Activate RobotLoader

The addDirectory call can be made more than once, which is how you cover an application directory and a vendor or library directory in the same run. The cache directory has to be writable by the web process, and it is a directory you will need to think about during deployment, since it is generated state rather than source. Everything after register is automatic, as the README puts it, from that point on you do not need to use require.

Duplicates, parse errors and directories to skip

Three behaviours are worth knowing before you run it on a real codebase, because each of them turns a silent mistake into a visible one. If RobotLoader encounters a duplicate class name during indexing, it throws an exception and notifies you, which is the correct outcome since a duplicate class name is a bug in the project and the autoloader is simply the thing that noticed it first. By default, errors in PHP files are reported by throwing a ParseError exception, and that can be suppressed with $loader->reportParseErrors(false) if you would rather see only the class you asked for. Some directories should not be indexed at all, and the exclusion call takes a directory name and can be called several times or passed several directories, for example $loader->excludeDirectory('temp'). The behaviour of the cache is the third. RobotLoader automatically updates the cache when it needs to load an unknown class, which is convenient while you are writing code and a liability on a production server, so the README recommends turning it off there.

Caching is what makes it fast, and it is a deployment concern

The caching section explains where the speed comes from and where your operational responsibility lies. During development you hardly notice RobotLoader running in the background, because it continuously updates its cache to account for classes and files being created, deleted or renamed, and it does not rescan unchanged files. On a production server the recommendation is the opposite: turn off cache updates with $loader->setAutoRefresh(false), which in a Nette Application happens automatically, because files there do not change. The corollary is that you must clear the cache when you upload a new version to hosting, otherwise the index describes the previous release. Two other details are documented. The initial scan, when no cache exists yet, can naturally take a moment for larger applications, and RobotLoader has built-in prevention against cache stampede, which is the situation where many concurrent requests arrive before the cache exists and would all start scanning files. The mechanism is that only the first thread indexes the files and creates the cache while the rest wait and then use the cache.

The same engine without the autoloading

RobotLoader can be used purely as a class finder, with no autoloading at all, which is the part of the API that other tools can reuse. You add a directory, call rebuild to scan it, and then read the result, which is an array of class to filename pairs:

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

The same index can be produced through the cache, so unchanged files are not rescanned, by setting the cache directory and calling refresh instead of rebuild. Two uses follow from that. You can build a code analysis or documentation tool on top of the index, and you can use the index in a build step to detect dead files or to produce a dependency graph. This is also the mode that is safe to run in a build pipeline, since it touches no runtime state.

Where PSR-4 wins, and where it does not

The README is honest about how this compares to the standard approach, and the difference is structural rather than a matter of taste. With Composer autoloading under PSR-4, namespaces and class names correspond to the directory structure and file names, so App\Router\RouterFactory lives in /path/to/App/Router/RouterFactory.php, and the mapping is computed rather than searched for. RobotLoader is not tied to any fixed structure, so it is useful when you do not want the directory layout designed exactly like the PHP namespaces, and when working on an application that historically does not follow those conventions. The README also notes that it is possible to use both loaders together, which is the realistic migration path, letting Composer handle the new PSR-4 code while RobotLoader covers the parts that do not follow the convention. For a new codebase that intends to follow PSR-4, the honest conclusion is that RobotLoader has nothing to add, because the thing it does well, searching for classes, is exactly what PSR-4 makes unnecessary.

Editorial conclusion

RobotLoader fits a codebase with an irregular directory layout, a legacy application that predates PSR-4, or a team that wants to delete hundreds of require statements without restructuring anything, and the single file distribution means you can drop it into a project that has no Composer at all. It is the wrong choice for a new project that already follows PSR-4, where Composer's autoloader does the same job with no indexing pass, and it is a poor fit if your application cannot write a cache directory or if you deploy to a platform where the cache must be regenerated on every request. Before you adopt it, confirm that the production deployment clears the cache when you upload a new version, because with setAutoRefresh(false) the index is only as current as the last build.

Frequently asked questions

Official sources

1. Issues
2. nette/robot-loader on GitHub
3. Project website
4. README
5. Releases