Himanshu SharmaSoftware engineer
Let’s talk

Composer · Lesson 9 of 15

Composer dump-autoload: regeneration and production maps

Regenerate Composer loading metadata, compare optimised and authoritative maps, and choose a safe development workflow.

12 minLoading PHP codeUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonUse dump-autoload without confusing loader regeneration with dependency updates.

After this lesson you can rebuild Composer's loading information and decide whether an optimisation suits development or a prepared release. You will also know why rebuilding a loader cannot repair an incompatible dependency constraint.

Regenerate information, not package selection

Work in the library with its original PSR-4 mapping restored. Run:

bash
composer dump-autoload

Example output captured on 2026-11; yours will differ (selected lines):

text
Generating autoload files
Generated autoload files

This reads the relevant package loading configuration and writes generated loader files. It does not perform the same job as resolving a new graph of dependency versions. If a package is missing because it was never required, regenerating the loader is not a substitute for declaring and installing it.

A change to the manifest's namespace mapping needs regeneration so the generated loader knows the new rule. A newly added class following an existing ordinary PSR-4 mapping can often be found without rebuilding because its path is derived from the class name. A classmap, by contrast, depends on the discovered entries recorded during generation.

This distinction helps you choose a useful diagnostic. First check whether the file, namespace and mapping agree. Next ask whether the loader is stale. Do not begin by deleting vendor or changing every package version when the real problem is one misspelled filename.

Generate an optimised map

bash
composer dump-autoload -o

Example output captured on 2026-11; yours will differ (selected lines):

text
Generating optimized autoload files

Optimisation precomputes class locations from suitable loading rules. This can reduce filesystem lookup work when the application runs. The course does not attach a speed percentage or promise a measurable benefit for this tiny example. Our label class is far too small to support a meaningful performance conclusion.

An ordinary optimised map still permits fallback lookup when appropriate. That can make it more forgiving than authoritative mode if a class is added after generation. Nevertheless, release preparation should generate loading support against the actual source tree to avoid depending on accidental fallback behaviour.

The official Composer Autoloader optimization guide distinguishes these levels. Choose a mode because its discovery behaviour matches your deployment, not because an option sounds more professional.

Understand the authoritative boundary

bash
composer dump-autoload --classmap-authoritative

Example output captured on 2026-11; yours will differ (selected lines):

text
Generating optimized autoload files (authoritative)

Authoritative mode treats the generated map as the source of class existence for Composer's loader. A class absent from the map is not found through its usual fallback lookup. This can be appropriate for a prepared immutable source tree, but can surprise applications that generate classes later or expect newly added classes to appear immediately.

Do not enable this blindly while following a beginner exercise that adds files step by step. A missing class can be a stale-map problem even though its namespace and filename are correct. Regenerating after the final source layout is present addresses that specific problem; disabling checks elsewhere does not.

Restore the ordinary development loader by running the first command again. Then run the existing check script to confirm that the library still behaves as expected. You should see the same passing message from the previous lesson.

Place regeneration in a repeatable workflow

Keep loader generation connected to dependency installation and release preparation. Generated files should reflect the installed packages and the source being released. Do not copy an unrelated vendor directory from another branch and assume its maps describe today's classes.

Optimisation is also separate from PHP's runtime caching mechanisms. Composer chooses how to locate class files; that does not mean it controls every aspect of PHP execution. When diagnosing performance or loading behaviour, state which layer you changed and avoid attributing every improvement to one Composer option.

Common mistakes

Running dump-autoload repeatedly cannot make an invalid namespace declaration valid. Check the source and mapping first. Another mistake is editing the generated classmap directly; the next regeneration can erase the edit and leave no maintained explanation of it.

Authoritative mode is particularly easy to carry accidentally from a release experiment back into active development. If a new class mysteriously fails to load, inspect the loader mode as well as the filesystem. Prefer a deliberate development baseline before continuing this course.

Exercise

A developer adds a correctly named class after generating an authoritative map. The old classes work, but the new one cannot load. Explain the likely cause and the narrow repair that avoids changing package versions.

Show the answer

The authoritative map may not contain the new class. Regenerate the map after the class exists, or return to ordinary development loading while actively adding classes. No dependency update is required merely to refresh loading information for your own source.

Continue learning

Previous: Composer classmaps and files: handling older PHP code

Next: Composer scripts: repeatable checks for a PHP package

Related: Composer manifests and locks: intent versus resolution

Related: Composer PSR-4: loading the bookshop library

Key points

  • Dump-autoload regenerates loading support rather than selecting package releases.
  • Optimised maps precompute class locations.
  • Authoritative maps require care when classes are created dynamically or added later.

Check yourself

1. Which operation selects new dependency releases?
2. What risk does an authoritative map introduce?
3. When should generated loaders be built for a release?