Composer Autoloading: PSR-4 Flexibility vs. Production Class Map Optimization

Your PHP application deploys, and the first few requests crawl. The culprit is often not your framework but Composer's default autoloader. Under the hood, the standard PSR-4 loader resolves classes by walking namespace rules and checking the filesystem for candidate paths. In production, that repeated disk I/O adds up. The fix is not to abandon PSR-4, but to convert its rules into a static class map with composer dump-autoload --optimize-autoloader.

PSR-4 is a specification that maps a namespace prefix to a base directory. In composer.json, you declare the mapping once:

{
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}

When PHP encounters App\Http\Kernel, Composer strips the App\ prefix and looks for src/Http/Kernel.php. It is a rule-based lookup, not a pre-built index. That keeps your composer.json small and means you can add new classes without regenerating anything. The generated file vendor/composer/autoload_psr4.php simply records the prefix-to-directory pairs.

The class map trade-off

The optimized autoloader flips that model. When you run composer dump-autoload --optimize-autoloader (or the shorter -o flag), Composer scans every directory covered by your PSR-4 rules and writes a complete class map to vendor/composer/autoload_classmap.php. At runtime, PHP looks up the fully qualified class name in that array and requires the exact file. You trade a longer build step for fewer filesystem checks on every request.

The trade-off is staleness. Because the map is static, any class you add, rename, or move after the dump will be invisible until you run the command again. In a development workflow where files change constantly, that is annoying. In a deployment pipeline where the artifact is immutable, it is exactly what you want.

A practical deploy-time check

Run the command from your project root, where composer.json lives. The process needs write access to the vendor/ directory:

# Run in project root; requires write permission to vendor/
composer dump-autoload --optimize-autoloader

To verify the result, open vendor/composer/autoload_classmap.php and confirm that a known application class appears as an array entry mapping its fully qualified name to an absolute file path. If the file is missing that entry, the class was not found during the scan—check the namespace prefix and directory casing in composer.json.

If you need to revert to the rule-based loader, run composer dump-autoload without flags. That regenerates the standard PSR-4 files and removes the optimized class map from the active autoload chain.

Limitations worth planning around

Case sensitivity. macOS and Windows filesystems are typically case-insensitive; Linux is case-sensitive. A namespace App\Foo that resolves to src/foo.php may work on your laptop and fail in production. PSR-4 does not normalize casing for you; it follows your directory names literally.

Legacy code. Third-party or older libraries that do not follow PSR-4 will not be covered by the optimized scan unless you explicitly include them. Add them to the classmap directive in composer.json so Composer indexes them:

{
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    },
    "classmap": [
      "legacy/"
    ]
  }
}

Disk I/O under load. The default PSR-4 loader can issue multiple stat() calls per class when the first candidate path does not exist. Under high traffic, that filesystem chatter becomes measurable latency. The optimized class map reduces those calls to a single array lookup.

What to do next

Keep PSR-4 mappings in composer.json for day-to-day development. In your deployment pipeline, run composer install --optimize-autoloader or composer dump-autoload -o as a final step so the class map matches the exact code being shipped. Before you call the deploy healthy, check that vendor/composer/autoload_classmap.php is newer than your source files and contains your entrypoint classes. That single check catches the most common failure mode: a stale map pointing at code that no longer exists.