Autoload Validation Laravel Package

Product Decisions This Supports

• Developer Productivity & Quality Gates:

  • Integrate into CI/CD pipelines to automatically block misconfigured autoload paths, reducing runtime ClassNotFoundException errors in Laravel applications. Aligns with Laravel’s dependency management while adding a critical validation layer.
  • Shift-left testing: Catch autoload issues during development (e.g., pre-commit hooks) or deployment (e.g., GitHub Actions), saving hours of debugging in production.
  • Onboarding Acceleration: New developers will encounter fewer "missing class" errors, reducing ramp-up time by ensuring autoload consistency from day one.

• Technical Debt Reduction:

  • Justify investment in PHP tooling by quantifying time saved (e.g., "X hours/week spent debugging autoload issues"). Prioritize this over custom solutions unless autoload rules are highly bespoke.
  • Monorepo Support: Validate autoloads across multiple Laravel/Lumen projects sharing a composer.json, ensuring consistency in large codebases.
  • Legacy Code Refactoring: Identify orphaned or misconfigured classes during migrations, reducing technical debt in older Laravel projects.

• Build vs. Buy Decision:

  • Buy: Ideal for teams lacking static analysis expertise. The package is low-maintenance (MIT license), lightweight, and solves a niche but critical problem without reinventing the wheel.
  • Build: Only if your autoload rules require custom logic (e.g., polyfill paths, non-PSR-4 structures, or dynamic class loading). In such cases, extend this package or build a wrapper around it.
  • Complementary to Laravel Ecosystem: Works alongside tools like Laravel Forge, Envoyer, or Homestead by validating autoloads before deployment.

• Use Cases:

  • Pre-Merge Checks: Block PRs with autoload inconsistencies via GitHub Actions/GitLab CI (e.g., fail builds if composer.json autoload paths are broken).
  • CI/CD Pipeline: Run as a pre-deployment gate to ensure autoloads are correct before releasing to staging/production.
  • Local Development: Add to composer.json scripts or use a pre-commit hook (e.g., Husky) to catch issues early.
  • Laravel-Specific Scenarios:
    • Validate custom PSR-4 namespaces (e.g., App\Modules\).
    • Check classmap entries for legacy or framework-agnostic classes.
    • Ensure Laravel’s internal autoloads (e.g., Illuminate\Support\) are correctly referenced.

When to Consider This Package

Adopt If:

• Your Laravel project uses PSR-4 autoloading (default in Laravel) and has >50 classes/files, making manual validation error-prone.
• You lack a dedicated static analysis tool (e.g., PHPStan, Psalm) or need autoload-specific validation beyond what composer validate offers.
• Your team frequently encounters "Class not found" errors during development or deployment, wasting time debugging autoload paths.
• You’re using Composer 1.x/2.x and want to enforce autoload consistency without adding complex tooling.
• Your CI/CD pipeline already runs composer install/dump-autoload, making integration trivial (adds ~1–2 seconds to runs).
• You’re maintaining a monorepo with multiple Laravel/Lumen projects sharing a composer.json and need to validate autoloads across all subprojects.

Look Elsewhere If:

• Your project uses non-standard autoloading, such as:
  • Custom classmap entries for non-PSR-4 classes.
  • Dynamic class loading (e.g., via ClassLoader::addPsr4() at runtime).
  • The files key for non-PSR-4 autoloading (e.g., legacy code).
• Your codebase is tiny (<20 classes) or uses frameworks with built-in autoload checks (e.g., Symfony’s debug:container).
• You prioritize performance over validation and cannot tolerate the ~1–2s runtime overhead in CI.
• Your team prefers visual tools over CLI validation, such as:
  • IDE plugins (e.g., PHPStorm’s autoload inspection).
  • Web-based static analyzers (e.g., Scrutinizer CI).
• You’re using Laravel Vapor or serverless, where autoload paths are managed externally (e.g., Lambda layers).

How to Pitch It (Stakeholders)

For Executives:

*"This is a ‘set-and-forget’ quality gate for our Laravel codebase that will save the team 15–20% of debugging time spent on ‘Class not found’ errors. Here’s why it’s a no-brainer:

• Cost: Zero dollars (MIT license) and 5 minutes to integrate into our CI/CD pipeline.
• Impact:
  • Reduces production incidents tied to autoload misconfigurations.
  • Lowers onboarding friction for new developers by ensuring autoload consistency from day one.
  • Aligns with our ‘shift-left’ testing initiative—catching issues early in the pipeline.
• ROI: Immediate time savings for the dev team, with no ongoing maintenance. Let’s pilot it in [Project X] and measure the reduction in autoload-related bugs."

For Engineering/Tech Leads:

*"This package is a lightweight, zero-config way to enforce autoload hygiene in our Laravel projects. Here’s how we’ll use it:

1. CI/CD Integration:
   • Add to composer.json under require-dev and run ./vendor/bin/check-autoloading.php in our pipeline.
   • Example GitHub Actions step:

     - name: Validate Autoload
       run: php vendor/bin/check-autoloading.php
     

2. Local Development:
   • Add to composer.json scripts:

     "scripts": {
       "validate-autoload": "php vendor/bin/check-autoloading.php",
       "post-install-cmd": ["validate-autoload"]
     }
     

   • Or create a custom Artisan command for developer convenience:

     php artisan autoload:validate
     

3. Edge Cases:
   • Exclude directories like tests/ or resources/ by adding to composer.json:

     "autoload-exclude": ["tests/", "resources/views/"]
     

   • For Laravel-specific paths (e.g., vendor/laravel/), pass a custom root:

     ./vendor/bin/check-autoloading.php ./app
     

Tradeoff: Adds ~1–2s to CI, but catches errors that would otherwise hit QA or production. Let’s start with a pilot in [Project Y] and expand if it reduces autoload bugs by >30%."

For Developers:

*"This tool will save you hours of debugging by automatically checking if all classes in composer.json exist and are correctly autoloaded. Here’s how it helps you:

• No More ‘Class Not Found’ Surprises:
  • Catch autoload issues before you deploy, not when users report bugs.
• Works with Your Workflow:
  • Run locally with composer validate-autoload or add to your pre-commit hooks.
  • Integrates seamlessly with Laravel’s composer.json—no framework-specific hacks.
• Easy to Customize:
  • Exclude directories (e.g., tests/) by updating composer.json.
  • Suppress warnings for known edge cases (e.g., dynamically loaded classes). Try it out:

composer require --dev phpcq/autoload-validation
./vendor/bin/check-autoloading.php
```"