PSR-4 Autoloading During PHP Modernization

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

Rules that break in real migrations

• Namespace prefix and directory must agree character-for-character after the base path
• Class name must match the filename (InvoiceHelper.php)
• Falling back to scanning the whole project with classmap forever hides structural debt
• Case-sensitive production filesystems fail when laptops are case-insensitive

Migration tactics

Keep old unnamespaced classes on classmap. Introduce namespaces for new modules under src/. For high-churn classes, create a namespaced wrapper that delegates to the legacy class (strangler), then swap call sites. After composer dump-autoload, prove both web and CLI entry points resolve the symbol.

Use the PSR-4 Checker on suspicious paths and the Composer.json Validator before merging autoload edits. Parent index: Composer modernization.