Getting Started

Minimal Steps

Installation Add the package to your Laravel project’s composer.json under require-dev:

"require-dev": {
    "phpcq/autoload-validation": "^1.0"
}

Run:

composer require --dev phpcq/autoload-validation

First Use Case Validate autoload configurations in your Laravel project:
```
./vendor/bin/check-autoloading.php
```
This checks if all classes defined in composer.json under autoload keys (psr-4, psr-0, classmap) exist on the filesystem.

Laravel-Specific Setup Add a custom script to composer.json for easier access:

"scripts": {
    "validate-autoload": "php vendor/bin/check-autoloading.php"
}

Now run:

composer validate-autoload

Implementation Patterns

Workflows

CI/CD Integration Add to your GitHub Actions, GitLab CI, or Laravel Forge/Envoyer workflows:
```
# GitHub Actions example
- name: Validate Autoload
  run: composer validate-autoload
```
Place this step after composer install and before running tests or deployment.
Local Development Bind to a pre-commit hook (e.g., using Husky) to catch issues early:
```
composer validate-autoload
```
Or create a custom Artisan command for Laravel developers:
```
php artisan autoload:validate
```
Monorepo Support Validate specific directories by passing a custom root path:
```
./vendor/bin/check-autoloading.php ./path/to/laravel-project
```

Integration Tips

Combine with Laravel’s composer dump-autoload Run autoload dumping before validation to ensure consistency:
```
composer dump-autoload && composer validate-autoload
```
Exclude Directories If certain directories (e.g., tests/, resources/) should be ignored, configure them in composer.json:
```
"autoload-exclude": {
    "tests/**",
    "resources/**"
}
```
Parallel Validation For large projects, run in parallel with other tools like PHPStan or Psalm:
```
composer validate-autoload & phpstan analyse src --parallel
```

Gotchas and Tips

Pitfalls

False Positives with Laravel’s Vendor Classes The tool may flag Laravel’s internal classes (e.g., Illuminate\Support\) if not explicitly defined in composer.json. Fix: Exclude Laravel’s vendor directory:
```
./vendor/bin/check-autoloading.php ./app
```
Or add to autoload-exclude:
```
"autoload-exclude": ["vendor/laravel/**"]
```
Dynamic Class Loading Classes loaded dynamically (e.g., via ClassLoader::addPsr4() at runtime) won’t be detected. Workaround: Manually add them to composer.json or suppress warnings.
Filesystem Permission Issues On shared hosting or CI environments, filesystem traversal may fail silently. Fix: Ensure the user running the command has read access to the project root.
Windows Path Handling Path separators (\ vs /) may cause issues. Fix: Use forward slashes or configure the tool to handle Windows paths (if supported).

Debugging

Verbose Output If the tool supports a --verbose flag, use it to inspect paths:
```
./vendor/bin/check-autoloading.php --verbose
```

Log Validation Results Redirect output to a file for debugging:

./vendor/bin/check-autoloading.php > autoload-validation.log

Check Exit Codes The tool should return a non-zero exit code on failure. Use this in CI/CD to block deployments:
```
- name: Validate Autoload
  run: ./vendor/bin/check-autoloading.php
  if: always()
```

Extension Points

Custom Validation Rules If the tool supports configuration (e.g., .autoload-validation.json), extend it to include project-specific rules.

Artisan Command Wrapper For Laravel developers, wrap the binary in a custom Artisan command for seamless integration:

// app/Console/Commands/ValidateAutoload.php
namespace App\Console\Commands;
use Illuminate\Console\Command;
class ValidateAutoload extends Command {
    protected $signature = 'autoload:validate';
    public function handle() {
        $exitCode = shell_exec('php vendor/bin/check-autoloading.php');
        if ($exitCode !== 0) {
            $this->error('Autoload validation failed!');
            exit($exitCode);
        }
        $this->info('Autoload validation passed.');
    }
}

Git Hook Integration Add to .git/hooks/pre-commit (or use Husky) to enforce validation before commits:
```
#!/bin/sh
composer validate-autoload || exit 1
```

Laravel-Specific Quirks

Laravel Mix/Envoyer If using Envoyer, add the validation step to your deployment script:
```
cd /path/to/project && composer validate-autoload
```
Laravel Sail For Dockerized environments, ensure the container has filesystem access:
```
sail artisan autoload:validate
```
Laravel Forge Add as a post-deploy hook in Forge’s deployment settings.

Autoload Validation Laravel Package