PSR-4 Autoloading Standard in Detail

PSR-4 Specification

PSR-4 defines how to map a namespace prefix to a filesystem directory.

The Mapping Process

Step 1: Start with the fully qualified class name
  Vendor\Module\Model\Product

Step 2: Match against registered namespace prefixes
  Prefix: Vendor\Module\
  Remaining: Model\Product

Step 3: Replace namespace separators with directory separators
  Model\Product -> Model/Product.php

Step 4: Prepend the base directory from the prefix mapping
  app/code/Vendor/Module/ + Model/Product.php
  = app/code/Vendor/Module/Model/Product.php

Complete Example

composer.json:
{
    "autoload": {
        "psr-4": {
            "Vendor\\Module\\": "app/code/Vendor/Module/"
        }
    }
}

File structure:
app/code/Vendor/Module/
├── Model/
│   ├── Product.php              # Vendor\Module\Model\Product
│   ├── ProductRepository.php    # Vendor\Module\Model\ProductRepository
│   └── ResourceModel/
│       ├── Product.php          # Vendor\Module\Model\ResourceModel\Product
│       └── Product/
│           └── Collection.php   # Vendor\Module\Model\ResourceModel\Product\Collection
├── Helper/
│   └── Data.php                 # Vendor\Module\Helper\Data
├── Controller/
│   └── Index/
│       └── Index.php            # Vendor\Module\Controller\Index\Index
└── Block/
    └── Product/
        └── View.php             # Vendor\Module\Block\Product\View

PSR-4 Rules

1. The namespace prefix maps to a base directory
2. Each namespace segment maps to a subdirectory
3. The class name maps to the filename
4. The filename MUST end with .php
5. The class name MUST match the filename exactly (case-sensitive)
6. One class per file
7. The file MUST contain only PHP code

Multiple Prefixes

{
    "autoload": {
        "psr-4": {
            "Vendor\\Module\\": "app/code/Vendor/Module/",
            "Vendor\\Library\\": "lib/Vendor/Library/",
            "": "app/code/"
        }
    }
}

The empty string prefix is a fallback for any class not matched by other prefixes.

Key Takeaway

PSR-4 strips the namespace prefix and converts the remainder to a file path. The prefix maps to a base directory, and namespace segments become subdirectories.

Autoloading Methods Comparison

PSR-4 Configuration

{
    "autoload": {
        "psr-4": {
            "Vendor\\Module\\": "src/"
        }
    }
}

Classmap Configuration

{
    "autoload": {
        "classmap": [
            "src/",
            "lib/"
        ]
    }
}

Classmap scans directories and creates a map of class names to file paths.

Files Configuration

{
    "autoload": {
        "files": [
            "src/helpers.php",
            "src/constants.php"
        ]
    }
}

Files are always loaded on every request. Use for helper functions or constants.

When to Use Each

PSR-4:    Standard classes with proper namespaces (preferred)
Classmap: Legacy code without namespaces, performance-critical
Files:    Helper functions (array_*, string_*), global constants

Composer Optimization

# Development: PSR-4 (flexible)
composer install

# Production: optimized classmap (faster)
composer install --optimize-autoloader
composer dump-autoload --optimize

# This generates:
# - composer/classmap.php (pre-scanned class map)
# - composer/autoload_files.php (files to include)
# - composer/autoload_namespaces.php (PSR-4 mappings)

Key Takeaway

PSR-4 is the standard for modern PHP. Classmap provides faster loading for production. Files is only for helper functions. Always use --optimize-autoloader in production.

Magento Bootstrap Process

pub/index.php
  -> require app/bootstrap.php
    -> require vendor/autoload.php (Composer)
    -> Register Magento autoloader
    -> Bootstrap::create()
    -> Application runs

Magento's vendor/autoload.php

Composer generates this file with all configured autoloaders:

vendor/autoload.php
  -> vendor/composer/autoload_real.php
    -> vendor/composer/autoload_static.php (optimized)
    -> vendor/composer/autoload_classmap.php
    -> vendor/composer/autoload_namespaces.php
    -> vendor/composer/autoload_files.php

Debugging Autoloading

<?php
// Check registered autoloaders
print_r(spl_autoload_functions());

// Find where a class is defined
$ref = new ReflectionClass('Vendor\Module\Model\Product');
echo $ref->getFileName();

// Check if class exists (triggers autoloader)
if (class_exists('Vendor\Module\Model\Product')) {
    echo 'Class found';
}

// Composer's compiled classmap
// Run: composer dump-autoload -v

Magento-Specific Autoloading

1. Composer autoloader loads vendor packages
2. Magento registers additional autoloaders for:
   - Generated classes (factories, proxies, interceptors)
   - Theme files (templates, skins)
   - View files (JS, CSS)

3. The fallback autoloader checks:
   - app/code/ directory
   - Generated/ directory
   - Vendor/ directory
   - Theme directories

Performance Tips

# Always optimize in production
composer dump-autoload --optimize

# Regenerate after code changes
bin/magento setup:di:compile
bin/magento setup:static-content:deploy

# Check for class conflicts
composer validate
bin/magento setup:di:compile 2>&1 | grep -i error

Key Takeaway

Magento uses Composer's autoloader as the foundation, supplemented by generated classes and fallback autoloaders. Always optimize the autoloader in production for better performance.