Autoloading with Composer
Before autoloading, PHP developers manually wrote a require or include statement for every class file a script needed, in the correct order so dependencies were defined before they were used — a brittle approach that broke the moment files were reorganized. Autoloading inverts this: instead of eagerly loading every possible class up front, you register a callback with spl_autoload_register() that PHP invokes automatically the first time an undefined class is referenced, and that callback figures out which file to load based on the class name. Composer, PHP's de facto package manager, generates and wires up this callback for you automatically according to standardized conventions, so you never write a manual require for your own classes or third-party packages again.
Cricket analogy: Old-school PHP was like a captain writing out every fielder's name and position by hand before each over; autoloading is like a coach who only sends a fielder onto the ground the instant the batsman needs to be covered, chosen automatically by spl_autoload_register().
PSR-4: mapping namespaces to directories
PSR-4 is the PHP-FIG standard that defines how a namespace prefix maps to a base directory. In composer.json, the autoload.psr-4 section declares this mapping, for example { "App\\": "src/" } means any class under the App\ namespace is expected to live under src/, with each subsequent namespace segment corresponding to a subdirectory and the final segment matching the filename. So App\Billing\Invoice resolves to src/Billing/Invoice.php. Composer reads this mapping and generates a set of files under vendor/composer/ (notably autoload_psr4.php and a class map) that spl_autoload_register() uses at runtime to translate any class name into an exact file path in constant time, without scanning the filesystem.
Cricket analogy: PSR-4's App\ to src/ mapping is like a scorecard convention where every player's name maps to a fixed position in the batting order, so anyone reading App\Billing\Invoice knows exactly which 'ground' (src/Billing/Invoice.php) to find that player on.
// composer.json
{
"autoload": {
"psr-4": {
"App\\": "src/"
},
"files": ["src/helpers.php"]
},
"autoload-dev": {
"psr-4": {
"App\\Tests\\": "tests/"
}
}
}
<?php
// public/index.php — the only require your app needs
require __DIR__ . '/../vendor/autoload.php';
use App\Billing\Invoice;
$invoice = new Invoice(199.99); // Composer loads src/Billing/Invoice.php on demand
echo $invoice->total;
Regenerating and optimizing the autoloader
Whenever you add a new namespace mapping to composer.json, or move classes between directories that break the PSR-4 convention, you must run composer dump-autoload so Composer regenerates its lookup files — simply editing composer.json does not update the generated autoloader by itself. In production, composer dump-autoload --optimize (or --classmap-authoritative for the strictest, fastest variant) precomputes a full class-to-file map ahead of time instead of resolving namespace prefixes dynamically on every request, trading a slightly larger generated file for noticeably faster class resolution under load.
Cricket analogy: Editing composer.json without running dump-autoload is like a team management changing the batting lineup on paper but forgetting to tell the scoreboard operator; composer dump-autoload --optimize is like pre-printing the final lineup card so the umpires never have to double-check positions mid-over.
Composer's autoload.files array (as shown above for helpers.php) is for loading plain function files that have no class to key off of — PSR-4 only knows how to autoload classes, interfaces, traits, and enums, never bare functions, so procedural helper files must be explicitly listed and are loaded on every request.
A very common source of 'Class not found' errors after adding a new class file is forgetting to run composer dump-autoload when the class map was previously optimized with --classmap-authoritative, since that mode refuses to fall back to dynamic file-existence checks for anything not already in the precomputed map.
- Autoloading replaces manual require/include statements with a callback invoked automatically when an undefined class is first referenced.
- PSR-4 maps a namespace prefix to a base directory in composer.json's autoload.psr-4 section.
- vendor/autoload.php is typically the only require statement an application needs to include manually.
- Editing composer.json's autoload section requires running composer dump-autoload to regenerate the actual lookup files.
- The autoload.files array loads plain procedural files (like helper functions) that PSR-4 cannot autoload since they define no class.
- composer dump-autoload --optimize precomputes the full class map for faster, more predictable production performance.
Practice what you learned
1. What PHP function does Composer register its autoloading callback with?
2. Under a PSR-4 mapping of { "App\\": "src/" }, where would the class App\Billing\Invoice be expected to live?
3. What must you do after adding a new namespace mapping to composer.json's autoload section?
4. Why does Composer's autoload have a separate 'files' array distinct from 'psr-4'?
5. What does composer dump-autoload --classmap-authoritative do?
Was this page helpful?
You May Also Like
Namespaces in PHP
Understand how PHP namespaces prevent naming collisions between classes, functions, and constants, and how import statements and resolution rules connect them across files.
Composer and Package Management
Learn how Composer manages PHP project dependencies, autoloading, versioning, and the composer.json/composer.lock files that define a project's package graph.
Classes and Objects
Explore PHP's object-oriented foundations: declaring classes, constructing objects, typed properties, visibility, and constructor promotion.
The PHP Framework Landscape
A tour of the major PHP frameworks — Laravel, Symfony, and lighter-weight alternatives — and the trade-offs that determine which one fits a given project.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics