Composer autoloader class map and PHP runtime resolution precedence

Direct Answer

Precedence order (when overlapping definitions exist):

1. Static class‑map entries (generated by composer dump-autoload --optimize or the default autoload_classmap.php)
2. PSR‑4 namespace mappings (looked up at runtime)
3. PSR‑0 mappings (fallback, legacy)

Enabling the APCu autoloader does not change this order; it only caches the file path that results from the standard lookup sequence.

An optimized class map takes precedence over a PSR‑4 lookup whenever the class name is present in the map. In that case Composer skips the PSR‑4 runtime check entirely.

Confirmed Facts (documented in Composer’s source and docs)

• Composer’s autoload.php first includes autoload_classmap.php and checks the map.
• Only if the map lookup fails does it invoke the PSR‑4 resolver, followed by the PSR‑0 resolver.
• APCu support (enabled via COMPOSER_APCU=true or --apcu) simply stores the resolved file path after the normal lookup; it does not reorder the lookup steps.
• When composer dump-autoload --optimize is run, Composer writes a fully resolved map and removes the runtime PSR‑4/PSR‑0 checks for classes that are present in the map.

Practical Verification Steps

1. composer dump-autoload --optimize to generate a full map.
2. Open vendor/composer/autoload_classmap.php and confirm the target class is listed.
3. Create a test class that exists only in a PSR‑4 directory (not in the map), then require it and verify Composer performs a PSR‑4 lookup (e.g., by adding a debug log in autoload_psr4.php).
4. Enable APCu autoloading: COMPOSER_APCU=true composer install (or composer install --apcu). Trigger a class load and inspect the APCu cache with apcu_cache_info() or a custom script to see the cached file path.
5. On a case‑sensitive filesystem, add a class with a different case in the map and attempt to load it with the original case to confirm that the map entry wins over the PSR‑4 lookup.

When to Consider Optimizing

• If you have a large codebase and notice filesystem latency during class resolution.
• When the majority of classes are already present in the static map (e.g., vendor libraries).
• Avoid optimization if you rely on dynamic class generation or on a very small set of classes where the overhead of generating the map outweighs the benefit.

Missing Diagnostic Detail?

To tailor this advice further, could you confirm:

• Composer version and PHP runtime (e.g., PHP 8.1, Composer 2.6).
• Whether you have any custom SPL autoloaders registered after Composer’s autoload.php.

Precedence Table

Lookup Step	Type	Order
Class‑map	Static file map	1
PSR‑4	Runtime namespace mapping	2
PSR‑0	Legacy underscore mapping	3