Autoloading Classes

What Is Autoloading?

In simple terms: Without autoloading, every file that uses a class must first require the file that defines it. In a project with hundreds of classes, these lists of require statements become long, fragile, and easy to get wrong. Autoloading lets PHP load a class file automatically the first time the class is used.

Technically: When PHP encounters a class, interface, trait, or enum that has not been defined yet, it calls the autoloader functions registered with spl_autoload_register(), passing the fully qualified class name. An autoloader translates that name into a file path and includes the file. In practice, almost every PHP project uses the autoloader generated by Composer, following the PSR-4 standard.

Without vs With Autoloading

// Without autoloading
require __DIR__ . '/src/Models/User.php';
require __DIR__ . '/src/Models/Order.php';
require __DIR__ . '/src/Services/Greeter.php';
// ... and many more, in the right order

// With autoloading
require __DIR__ . '/vendor/autoload.php';
// every class is loaded on demand

The PSR-4 Convention

PSR-4 defines how class names map to files:

Namespace prefix   App\           →  base directory   src/
Class              App\Models\User
Relative name      Models\User    →  file             src/Models/User.php

Rules:

1. A namespace prefix (such as App0) is mapped to a **base directory** (such as src/`).
2. The rest of the class name becomes the path: namespace separators 0 become directory separators /`.
3. The file name is the class name plus .php, with exactly the same capitalization.

Writing an Autoloader With spl_autoload_register()

The following script creates two class files and loads them through a small PSR-4 autoloader. The autoloader prints a message each time it is called, which shows when loading happens.

<?php
$base = __DIR__ . '/autoload-demo/src';
@mkdir("$base/Models", 0755, true);
@mkdir("$base/Services", 0755, true);

file_put_contents("$base/Models/User.php", <<<'PHP'
<?php
namespace App\Models;

final class User
{
    public function __construct(public readonly string $name) {}
}
PHP);

file_put_contents("$base/Services/Greeter.php", <<<'PHP'
<?php
namespace App\Services;

use App\Models\User;

final class Greeter
{
    public function greet(User $user): string
    {
        return "Hello, {$user->name}!";
    }
}
PHP);

spl_autoload_register(function (string $class) use ($base): void {
    $prefix = 'App\\';

    if (!str_starts_with($class, $prefix)) {
        return;   // not our namespace: let other autoloaders try
    }

    $relative = substr($class, strlen($prefix));
    $file = $base . '/' . str_replace('\\', '/', $relative) . '.php';

    echo "Autoloading $class\n";

    if (is_file($file)) {
        require $file;
    }
});

echo "Script started\n";

$user = new App\Models\User('Asha');
echo "Created user {$user->name}\n";

$greeter = new App\Services\Greeter();
echo $greeter->greet($user) . "\n";

var_dump(class_exists('App\Models\Invoice'));
var_dump(class_exists('App\Models\User'));

Output

Script started
Autoloading App\Models\User
Created user Asha
Autoloading App\Services\Greeter
Hello, Asha!
Autoloading App\Models\Invoice
bool(false)
bool(true)

How It Works

1. spl_autoload_register() adds the closure to PHP's list of autoloaders. Nothing is loaded yet — "Script started" appears first.
2. new App\Models\User(...) refers to an unknown class, so PHP calls the autoloader with 'App\Models\User'. It maps the name to src/Models/User.php and includes the file.
3. Greeter is loaded only when it is first used. The type hint User in its method does not trigger loading again, because User is already defined.
4. class_exists() also triggers autoloading. For Invoice, the autoloader finds no file, so the class does not exist and false is returned.
5. class_exists('App\Models\User') returns true without calling the autoloader, because the class is already loaded.

Rules for Autoloader Functions

• Return silently if the class is not yours, so other registered autoloaders can try.
• Do not throw exceptions or print errors for missing classes; class_exists() checks rely on a quiet "not found".
• Several autoloaders can be registered; PHP calls them in order until the class exists.

Autoloading With Composer

In real projects, you do not write autoloaders yourself. Composer generates an optimized one from your composer.json:

{
    "name": "gocourse/shop",
    "require": {
        "php": ">=8.3"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        },
        "files": [
            "src/helpers.php"
        ]
    },
    "autoload-dev": {
        "psr-4": {
            "Tests\\": "tests/"
        }
    }
}

composer dump-autoload

<?php
// public/index.php
require __DIR__ . '/../vendor/autoload.php';

use App\Models\User;
use App\Services\Greeter;

echo (new Greeter())->greet(new User('Asha'));

What the Configuration Means

vendor/autoload.php registers autoloaders for your code and for every package installed with Composer, so a single require covers everything (see Composer).

Optimizing for Production

composer dump-autoload --optimize --classmap-authoritative

--optimize builds a class map — a precomputed array of class names and file paths — so the autoloader no longer checks the filesystem for each class. --classmap-authoritative additionally tells Composer that every class is in the map, so unknown classes are rejected immediately. Use these options during deployment (re-run them whenever classes are added).

Common Mistakes

File and Class Names That Do Not Match

Effect: Class "App\Models\User" not found, often only on Linux servers (case-sensitive filesystems), while it worked on Windows or macOS.

Fix: Match file names and directories exactly, including capitalization.

Forgetting composer dump-autoload

Effect: New mappings or the class map do not include new classes.

Fix: Regenerate the autoloader after changing composer.json (and after adding classes when using an optimized class map).

Mixing Manual require With Autoloading

Effect: "Cannot declare class ... because the name is already in use" errors when a file is included twice.

Fix: Let the autoloader load classes; remove manual requires for them.

Expecting Functions to Be Autoloaded

Effect: Call to undefined function.

Fix: Use Composer's files autoloading or static methods in classes.

Throwing Exceptions in Autoloaders

Effect: class_exists() and other autoloaders break.

Fix: Return quietly when a class cannot be found.

Best Practices

• Follow PSR-4: one class per file, namespaces mirroring directories.
• Use Composer's autoloader instead of writing your own.
• Include vendor/autoload.php once, in the application's entry point.
• Use the files section only for genuinely global helper functions.
• Generate an optimized class map for production deployments.

Official reference: https://www.php.net/manual/en/language.oop5.autoload.php