Composer PSR-4 Autoloading

When to use

• The user hits a "class not found" error and needs to fix the autoload mapping or regenerate the autoloader.
• The user needs to always load a file of global helper functions or constants that has no class to autoload.
• The user wants Composer to autoload classes by mapping a namespace prefix to a source directory.

When NOT to use

• Do not use this skill for a project that does not use Composer; register a manual spl_autoload_register callback instead.
• Do not rely on this skill to load a class whose file path is computed at runtime outside any namespace convention.

Core guidance

• Put test namespaces under autoload-dev — Map test and fixture namespaces under autoload-dev.psr-4 (for example "Tests\\": "tests/") rather than autoload.
• Map each namespace prefix to one base directory — In the autoload.psr-4 block, map a namespace prefix ending in a backslash to a single base directory, so "App\\": "src/" resolves App\Http\Kernel to src/Http/Kernel.php.
• Choose PSR-4 for conventional code, classmap for legacy — Use psr-4 for code that follows the namespace-to-path convention, and reserve classmap for legacy directories where file layout does not match namespaces.

Quick recipe

1. Add an autoload.psr-4 entry mapping your root namespace to its source directory, e.g. "App\\": "src/". (verify: composer.json contains the App\\ -> src/ mapping under autoload.psr-4)
2. Run composer dump-autoload so Composer regenerates the loader with the new mapping. (verify: A fresh vendor/composer/autoload_psr4.php includes the new prefix)
3. Require vendor/autoload.php and instantiate a mapped class to confirm resolution, e.g. new App\Http\Kernel(). (verify: The class instantiates without a class-not-found error)

Best practices

• After editing any autoload block, run composer dump-autoload to regenerate the loader; PSR-4 code picks up new classes automatically, but changed mappings do not
• For production, run composer dump-autoload --optimize --classmap-authoritative to convert PSR-4 lookups into a static classmap and skip filesystem probing

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Directory or file case does not match the class name — A file or directory whose case differs from the class or namespace segment fails to autoload on case-sensitive filesystems. Fix: Rename files and directories to match the class and namespace segment casing exactly, then run composer dump-autoload.
2. PSR-4 prefix missing its trailing separator — A PSR-4 key without a trailing namespace separator can shadow sibling namespaces or fail to match. Fix: Always end a PSR-4 namespace key with an escaped backslash, e.g. "App\\", and re-dump the autoloader.
3. Forgetting to dump the autoloader after a mapping change — Changing a namespace mapping without regenerating the autoloader leaves the old resolution in place. Fix: Run composer dump-autoload after any edit to the autoload configuration in composer.json.

Version notes

• Composer 2 changes optimized autoloader flags (PHP >=7.4) — Composer 2 splits the old --optimize behavior so --classmap-authoritative implies optimization and skips the filesystem fallback entirely.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/composer/autoload-psr4.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: composer/dependency-management, psr/psr4-autoloading