/commands/composer/composer-dump-autoload
composer dump-autoload -o: regenerate and optimize the autoloader
- tool
- Composer
- versions
- Composer 2.x
- os
- any
composer dump-autoload (alias dumpautoload) regenerates vendor/autoload.php and the files in vendor/composer/ without installing or updating packages. Run it after you change the autoload or autoload-dev section of composer.json (a new PSR-4 namespace, a files entry, a classmap folder) or add classes to a classmap-based directory. In production, use composer dump-autoload -o --no-dev to build an optimized class map.
Usage
composer dump-autoload # after editing "autoload" in composer.json
composer dump-autoload -o # optimized: classmap of every PSR-4/PSR-0 class
composer dump-autoload -o --no-dev # production: skip autoload-dev
composer dump-autoload --classmap-authoritative # -a: only the classmap, no filesystem lookups
composer dump-autoload --apcu # cache lookups in APCuExample autoload section
{
"autoload": {
"psr-4": { "App\\": "src/" },
"files": ["src/helpers.php"]
},
"autoload-dev": {
"psr-4": { "App\\Tests\\": "tests/" }
}
}After adding this, run composer dump-autoload; App\Http\Kernel then loads from src/Http/Kernel.php.
Options
| Option | Effect | Use in |
|---|---|---|
| -o, --optimize | Convert PSR-4/PSR-0 rules into a class map (faster lookups) | Production |
| -a, --classmap-authoritative | Load only from the class map; unknown classes are not searched on disk (implies -o) | Production, when no classes are generated at runtime |
| --apcu | Cache found and missing classes in APCu | Production with APCu enabled |
| --no-dev | Ignore autoload-dev rules | Production |
| --dev | Include autoload-dev (the default) | Development |
| --strict-psr | Fail if a class does not match its PSR-4 path (with -o) | CI checks |
composer install and composer update dump the autoloader automatically; composer install --optimize-autoloader --no-dev (-o) does the same optimization during deployment.
Optimization levels
Composer's autoloader optimization guide describes three levels. All of them belong in production builds, not in development:
| Level | How to enable | Trade-off |
|---|---|---|
| 1: class map | dump-autoload -o, install -o, or "optimize-autoloader": true in config | None worth noting; misses still fall back to slow filesystem checks |
| 2/A: authoritative class map | dump-autoload -a, or "classmap-authoritative": true | Fastest; classes generated at run time are never found |
| 2/B: APCu cache | dump-autoload --apcu, or "apcu-autoloader": true | Needs the APCu extension; uses APCu memory; combine with level 1 yourself |
Setting the config keys in composer.json applies the optimization to every install, update and dump-autoload, so a deployment script cannot forget the flag.
What it generates
vendor/autoload.php is the only file your code includes. It loads vendor/composer/autoload_real.php, which reads the generated maps: autoload_psr4.php and autoload_namespaces.php (PSR-4 and PSR-0 prefixes), autoload_classmap.php (every class found in classmap directories, and every class when you use -o), autoload_files.php (files included on every request) and autoload_static.php, a static copy of all of them. Never edit these files: the next dump overwrites them.
Troubleshooting class not found
- Check that the namespace in the file matches the PSR-4 prefix and folder:
App\Http\Kernelwith"App\\": "src/"must live insrc/Http/Kernel.php, with the same letter case (Linux file systems are case-sensitive). - Run
composer dump-autoload -o: Composer warns about classes that do not comply with PSR-4 and skips them, which points at the mismatch. - If production uses
-aand the class is generated at run time, switch to-oor--apcu. - For a new
filesentry, dump again: helper files are included only after they appear inautoload_files.php.
FAQ
Do I need composer dump-autoload after adding a new class?
Not with plain PSR-4 rules in development: the autoloader finds new classes on disk by their namespace. You need it after editing the autoload section, after adding files to a classmap directory, and whenever you use -o or -a, because the class map is fixed at dump time.
Should I use -o in development?
No. Composer recommends the optimizations for production only; with a class map, classes you add or move are not found until you dump again.
Can I combine --classmap-authoritative and --apcu?
No. Both address autoload misses in different ways, and Composer's documentation says to choose one of them.