/flags/composer/composer-install-optimize-autoloader
composer install -o (--optimize-autoloader): classmap autoloading for production
- tool
- Composer
- command
- composer install, composer update, composer dump-autoload
- flag
- -o, --optimize-autoloader; -a, --classmap-authoritative; --apcu-autoloader
- default
- off (PSR-4 and PSR-0 rules are resolved on the file system at runtime)
By default Composer's autoloader turns a class name into a file path using the PSR-4 and PSR-0 rules and checks the file system for every class it loads. composer install --optimize-autoloader (short -o) converts those rules into a classmap, one array of class name to file, so most lookups need no file system checks. The Composer documentation recommends it for production. -a (--classmap-authoritative) goes further and trusts only the classmap; --apcu-autoloader caches lookups in APCu.
Usage
composer install --no-dev --optimize-autoloader # production install
composer dump-autoload --optimize --no-dev # regenerate after copying code
composer dump-autoload --classmap-authoritative # level 2/A, implies -odump-autoload accepts the same options, which is useful when dependencies were installed before the application code was copied, as in Docker builds. See composer dump-autoload.
Optimisation levels
| Option | What it does | Trade-off |
|---|---|---|
| (none) | PSR-4/PSR-0 resolution with file_exists checks | Slowest lookups, always up to date |
| -o, --optimize-autoloader | Classmap for all PSR-4/PSR-0 classes, fallback to rules | Regenerate when classes are added |
| -a, --classmap-authoritative | Only the classmap; unknown classes fail immediately | No runtime-generated classes |
| --apcu-autoloader | Cache found and missing classes in APCu | Needs the APCu extension; cache must be cleared on deploy |
| --strict-psr-autoloader | Fail (exit code 6) on PSR-4/PSR-0 mapping errors | Useful in CI with -o or -a |
Settings in composer.json
{
"config": {
"optimize-autoloader": true,
"classmap-authoritative": false,
"apcu-autoloader": false
}
}With optimize-autoloader set, every install, update and dump-autoload produces the optimised autoloader without the flag.
Pitfalls
- Classes added after the classmap was generated are still found with
-o(through the rules fallback), but not with-a. Never deploy new code without regenerating the autoloader when using level 2. - Generated proxy classes (some ORMs, dependency injection containers) may not exist at dump time;
-abreaks them unless they are generated beforedump-autoload. - PHP's OPcache should be enabled too; the classmap removes file system checks, OPcache removes recompilation. They complement each other.
--strict-psr-autoloadersurfaces files whose namespace does not match their path, which otherwise produce confusing "Class not found" errors only in production.
The full production install, including dropping dev packages, is covered in composer install --no-dev.
FAQ
Should I use --optimize-autoloader in development?
Not normally. The classmap is generated at install time, so new classes you add while developing are found only through the PSR-4 fallback or after another dump-autoload. The speed gain matters in production, where code does not change between deploys.
What does --classmap-authoritative add?
It tells the autoloader to trust the classmap completely: a class that is not in it is reported as missing without checking the file system. That is the fastest option, but classes generated at runtime cannot be autoloaded.
Can I enable optimisation permanently?
Yes. Set optimize-autoloader to true (and optionally classmap-authoritative or apcu-autoloader) under config in composer.json, then every install and update produces the optimised autoloader.