Why are there two PSR4 mappings for the database directory?

It all comes down to a single capital letter

Joel Clermont

2026-02-26

If you have ever looked at the autoload section in your Laravel project's composer.json, you might have wondered why there are three separate entries:

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Database\\Factories\\": "database/factories/",
        "Database\\Seeders\\": "database/seeders/"
    }
}

Everything under app/ is covered by the single App\\ mapping. Your models, controllers, services, jobs, and anything else you put in there all autoload without any extra configuration. That is because PSR-4 works by matching a namespace prefix to a directory, and then resolving everything beneath it by following the namespace structure.

So why not just add a single Database\\ mapping to database/ and cover everything in one entry?

In the past, a big reason was migrations. Migration files use timestamped filenames with class names that do not match the file path, which would trip up Composer's optimized autoloader. With anonymous migration classes, this is no longer an issue since there is no named class to map.

But there is still one remaining issue with case-sensitivity.

PSR-4 expects the directory structure to match the namespace exactly. Database\Seeders\DatabaseSeeder should map to database/Seeders/DatabaseSeeder.php with a capital S.

But Laravel's directory is lowercase: database/seeders/.

On a case-sensitive filesystem, the autoloader would look for database/Seeders/ and simply not find it. And even on case-insensitive systems, enabling optimize-autoloader causes Composer to detect the mismatch and silently skip those classes.

The separate entries avoid this by mapping each namespace directly to its lowercase directory.

You could also just capitalize the directories to match the namespace, and the single Database\\ mapping would work perfectly. Maybe Laravel will do this at some point, but it's not really a big deal either way, more of just a curiosity.

Sometimes it is worth stopping to understand configuration you see in every project but never thought about before.

Here to help,

Joel

P.S. Understanding how your tools work under the hood makes you a better developer. If you enjoy digging into topics like this, you would love our community.

Previous tip