Composer Autoloading

Composer autoloading lets PHP load classes without manual require statements. PSR-4 mappings connect namespace prefixes to source directories and keep application structure predictable.

Working Knowledge

• Map application namespaces under autoload.psr-4.
• Keep namespace and directory casing consistent.
• Run composer dump-autoload after changing mappings.
• Use autoload-dev for test fixtures and test namespaces.
• Avoid manual file includes for normal namespaced classes.

Map A Namespace With PSR-4

{
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  },
  "autoload-dev": {
    "psr-4": {
      "Tests\\": "tests/"
    }
  }
}

With this mapping, App\Billing\Invoice belongs in:

src/Billing/Invoice.php

The namespace, directory names, and filename casing must match. A mismatch can work on a case-insensitive laptop and fail on Linux in CI or production.

Load Composer's Autoloader

An entry script loads the generated autoloader once:

<?php

declare(strict_types=1);

require dirname(__DIR__) . '/vendor/autoload.php';

Normal application classes should not need scattered manual require statements after that.

Debug Class-Not-Found Errors

Check the class namespace, directory path, filename case, mapping, and whether dependencies were installed. After changing mappings, regenerate autoload files:

composer dump-autoload

For an optimized production autoloader, follow the deployment command already used by the project.

In Application Work

When a class cannot be found, inspect its namespace, path, case, Composer mapping, and generated autoloader before adding workaround includes.

What To Check

Before moving on, make sure you can map a namespace to a directory, locate a class file from its full name, load Composer's autoloader, and diagnose casing and mapping errors.