Understanding Composer Autoload and PHP Class Loading in Laravel

In Laravel development, models, controllers, and routes are organized, but developers may overlook PHP's loading mechanism, which requires explicit file inclusion besides namespace usage.

Example of a simple Greeting class (src/models/Greeting.php) and its usage in src/index.php without requiring the file leads to a fatal error.

<?php

// path: src/models/Greeting.php

namespace Test\Models;

class Greeting
{
    public function greet($name)
    {
        return "Hello, $name!\n";
    }
}

The fatal error occurs because the class file is not loaded.

PHP Fatal error: Uncaught Error: Class "Test\Models\Greeting" not found in /test/src/index.php:5

To avoid this, the class file must be required before use, but manually requiring each class is cumbersome.

Composer's autoload mechanism solves this by generating a class map based on PSR‑4 configuration in composer.json.

{
    "name": "test/test",
    "type": "project",
    "autoload": {
        "psr-4": {
            "Test\\": "src/"
        }
    },
    "authors": [
        {
            "name": "Winnie Tsou"
        }
    ],
    "require": {}
}

By running composer dump-autoload , Composer creates vendor/autoload.php, which can be required once in the entry script, enabling automatic loading of all classes under the Test namespace.

<?php

// at the bottom of the program include vendor/autoload.php

require __DIR__ . '/../vendor/autoload.php';

use Test\Models\Greeting;

$greeting = new Greeting();

echo $greeting->greet('World');

Running the script after autoload setup outputs "Hello, World!" without the previous fatal error.

root@bb70c18bed6b:/test# php src/index.php
Hello, World!

The autoload process involves several generated files: vendor/autoload.php, vendor/composer/autoload_real.php, vendor/composer/autoload_static.php, and the ClassLoader class which registers the PSR‑4 loader via spl_autoload_register .

/**
 * Register this instance as an autoloader
 *
 * @param bool $prepend Whether to prepend the autoloader or not
 * @return void
 */
public function register($prepend = false)
{
    spl_autoload_register(array($this, 'loadClass'), true, $prepend);

    if (null === $this->vendorDir) {
        return;
    }

    if ($prepend) {
        self::$registeredLoaders = array($this->vendorDir => $this) + self::$registeredLoaders;
    } else {
        unset(self::$registeredLoaders[$this->vendorDir]);
        self::$registeredLoaders[$this->vendorDir] = $this;
    }
}

The ClassLoader's loadClass method looks up the file using the static map and includes it, completing the class loading.

/**
 * Load the given class or interface
 *
 * @param string $class The name of the class
 * @return true|null True if loaded, null otherwise
 */
public function loadClass($class)
{
    if ($file = $this->findFile($class)) {
        $includeFile = self::$includeFile;
        $includeFile($file);
        return true;
    }

    return null;
}