Overview
Composer is more than a package installer. Its autoloader maps class names to files so application code does not need a long chain of require statements. PSR-4 is the common convention for mapping namespaces to directory paths.
Define an application namespace
A minimal composer.json can map an application namespace to a source directory:
{
"name": "example/site",
"type": "project",
"require": { "php": ">=8.3" },
"autoload": {
"psr-4": { "App\": "app/" }
}
}
A class named App\Services\ReportService would live at app/Services/ReportService.php, following the namespace and filename conventions.
Generate and load the autoloader
Run composer dump-autoload after changing autoload mappings. Include the generated file once from the application bootstrap:
require dirname(__DIR__) . '/vendor/autoload.php';
Use the actual relative path for your directory layout. Do not commit the vendor directory if your deployment process installs dependencies from the lock file.
Production dependency workflow
Commit composer.json and composer.lock. On production, use composer install --no-dev --prefer-dist --optimize-autoloader when deployment permits Composer execution. install uses the exact locked versions; update resolves newer compatible versions and should normally happen in development with review and tests.
Common problems
Namespace spelling and directory case must match on case-sensitive Linux filesystems. Check that the autoload mapping ends with the correct slash, the class has the expected namespace, and Composer's generated autoloader is included. Regenerate the autoloader after changing mappings.
Official references
Composer autoload schema Composer basic usage
Configure PSR-4
A custom project can use Composer without adopting a framework. In composer.json, map a project namespace to the application directory:
{
"autoload": {
"psr-4": {
"App\\": "app/"
}
}
}
After changing the mapping, regenerate the autoloader:
composer dump-autoload
A class named App\\Services\\MailService should then live at app/Services/MailService.php, following the namespace and filename conventions. Class names and paths should match consistently, especially when code is deployed to a case-sensitive Linux filesystem.
Load the autoloader once
The public front controller or bootstrap file should include vendor/autoload.php. Avoid requiring it repeatedly from individual controllers. Keep application classes under your own namespace and let Composer manage third-party package namespaces.
Production considerations
Commit composer.json and composer.lock so deployments use the same dependency versions. On production, install from the lock file with an appropriate production command, and do not run development tooling unnecessarily. Review package scripts and dependencies before deployment.
Troubleshooting
If a class is not found, verify the namespace, directory mapping, filename case and whether composer dump-autoload ran after the change. Do not solve an autoloading problem by adding a growing chain of manual require statements.