RobotLoader is a tool that gives you comfort of automated class loading for your entire application including third-party libraries.
✅ get rid of all require
✅ 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';
...Do you like RobotLoader? Are you looking forward to the new features?
Thank you!
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-loaderIt requires PHP version 8.0 and supports PHP up to 8.3.
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 RobotLoaderAnd 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).
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();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.
If auto-refresh is enabled it is possible to get concurrency issues prior to stabilization.
This is because parallel requests may all be updating the cache to notify about (possibly the same) missing classes, and under intense conditions (such as aggressive parallelism of PHPStan) the cache may be updated at the same time as being read.
This only affects filesystems where the rename operation is not atomic.
This problem can be mitigated by reducing the retry-limit, and adding exclusions for classes you know Robotloader cannot find or have their own autoloaders:
$loader->setRetryLimit(1);
$loader->addExclusion('PHPStan\\ExtensionInstaller\\GeneratedConfig', 'JsonIncrementalParser');(this example has some classes that PHPStan tries to load and Robotloader cannot find)
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\Router\RouterFactory will be in the file /path/to/App/Router/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.
If you like RobotLoader, please make a donation now. Thank you!