PSR-4 Autoloading Standard

Also Known As

TL;DR

Explanation

PSR-4 defines a mapping from fully qualified class names to file paths: the namespace prefix maps to a base directory, and sub-namespaces map to subdirectories. For example, App\Controller\HomeController maps to src/Controller/HomeController.php. Composer implements PSR-4 autoloading via the autoload section in composer.json, generating an optimised classmap in production. PSR-4 replaced the older PSR-0 and eliminated the double-underscore namespace separator convention.

Common Misconception

Why It Matters

Common Mistakes

• Class namespace not matching directory structure — autoloader cannot find the class.
• Not registering the PSR-4 mapping in composer.json autoload section.
• Using multiple classes per file — PSR-4 requires one class per file, filename matching class name.
• Forgetting to run composer dump-autoload after adding new namespace mappings.

Code Examples

// Namespace doesn't match file path:
// File: src/services/UserService.php
namespace App\Services\User; // Wrong — should match: App\Services
class UserService {}

// Autoloader looks for: src/Services/User/UserService.php
// File is at:           src/services/UserService.php
// Result: class not found

// composer.json — map namespace prefix to directory
{
  "autoload": {
    "psr-4": {
      "App\\\\": "src/",
      "App\\\\Tests\\\\": "tests/"
    }
  }
}

// File: src/Domain/Order/OrderService.php
// Class must be: namespace App\\Domain\\Order; class OrderService

// Regenerate autoloader after adding new namespaces
$ composer dump-autoload --optimize

// Dev autoloader includes tests; production excludes them
$ composer dump-autoload --optimize --no-dev

Tags

Related Terms

References

• https://www.php-fig.org/psr/psr-4/
• https://getcomposer.org/doc/04-schema.md#autoload