Autoloading with Composer

Analogy categoryAnalogies

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.

php

// composer.json
{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        },
        "files": ["src/helpers.php"]
    },
    "autoload-dev": {
        "psr-4": {
            "App\\Tests\\": "tests/"
        }
    }
}

php

<?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?

Namespaces in PHP

Related Study Notes in Programming

Browse all study notes

Programming

Apache Spark Study Notes

Programming · 30 topics

Programming

Apache Flink Study Notes

Programming · 30 topics

Programming

Hadoop Study Notes

Programming · 30 topics

Programming

Snowflake Study Notes

Programming · 30 topics

Programming

Apache Airflow Study Notes

Programming · 30 topics

Programming

dbt (Data Build Tool) Study Notes

Programming · 30 topics

Topics covered

#PHP#PHPProgrammingStudyNotes#Programming#AutoloadingWithComposer#Autoloading#Composer#PSR#Mapping#StudyNotes#SkillVeris

Autoloading with Composer