Analyzer Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Alignment: Designed for PHP/Laravel ecosystems, with native support for Laravel’s class autoloading (PSR-4) and PHPDoc validation, making it a seamless fit for Laravel applications.
• Static Analysis Complement: Acts as a lightweight pre-check for tools like PHPStan/Psalm, reducing false positives by validating class existence before deeper analysis.
• Modern PHP Support: Fully compatible with PHP 8.1–8.5 and PHPUnit 10–13, aligning with Laravel’s long-term roadmap (Laravel 10+).
• Targeted Scope: Focuses exclusively on class reference correctness, avoiding the overhead of full static analysis while addressing 30–50% of runtime class-loading errors.

Integration Feasibility

• Composer Integration: Zero-configuration via composer require graham-campbell/analyzer --dev, with no runtime dependencies (dev-only).
• PHPUnit Integration: Designed as a PHPUnit extension, enabling pre-test validation of class references. Can be triggered via:
  • Custom PHPUnit listener (e.g., @group analyzer).
  • CI pre-check (e.g., GitHub Actions php vendor/bin/phpunit --group analyzer).
• Laravel-Specific Hooks: Can be integrated into:
  • Artisan commands (e.g., php artisan analyzer:check).
  • Laravel Forge/Envoyer for pre-deploy validation.
  • Laravel Pint/Pint for pre-commit checks (via pint --test).

Technical Risk

Key Questions

1. Scope of Validation:

   • Should we validate only use statements or also PHPDoc annotations (e.g., @property, @method)?
   • Recommendation: Enable both for full coverage (PHPDoc errors often cause runtime issues).

2. CI Integration Strategy:

   • Run as a pre-test check (fast, blocks bad PRs) or post-test (slower but thorough)?
   • Recommendation: Pre-test (faster feedback loop) + post-test (catch edge cases).

3. Ignore Lists:

   • Should we whitelist known "safe" missing classes (e.g., third-party SDKs) or blacklist problematic files?
   • Recommendation: Blacklist files (e.g., tests/, vendor/) + whitelist exceptions (e.g., Stripe\*).

4. Performance Trade-offs:

   • Should we parallelize analysis for large codebases (e.g., 50K+ files)?
   • Recommendation: Use --parallel flag if CI allows (PHPUnit 10+ supports this).

5. Laravel-Specific Customization:

   • Should we extend the analyzer to handle Laravel’s dynamic facades (e.g., Facade::class) or service container bindings?
   • Recommendation: No (out of scope; use PHPStan’s Laravel extension for this).

6. Alerting:

   • Should failures block CI or warn only (e.g., Slack notification)?
   • Recommendation: Block CI for critical paths (e.g., app/, src/), warn only for tests.

Integration Approach

Stack Fit

Migration Path

1. Assessment Phase (1–2 days):

   • Run analyzer in dry mode to identify existing broken references.
   • Audit false positives and configure getIgnored() accordingly.
   • Benchmark CI runtime (target: <5 min for 10K files).

2. CI Integration (1 day):

   • Add to composer.json (dev dependency):

     "require-dev": {
         "graham-campbell/analyzer": "^5.1"
     }
     

   • Configure PHPUnit (phpunit.xml):

     <listeners>
         <listener class="GrahamCampbell\Analyzer\AnalysisListener" />
     </listeners>
     

   • Add CI step (GitHub Actions example):

     - name: Run Analyzer
       run: php vendor/bin/phpunit --group analyzer
     

3. Laravel-Specific Hooks (Optional, 1 day):

   • Create an Artisan command for local checks:

     php artisan make:command AnalyzerCheck
     

     // app/Console/Commands/AnalyzerCheck.php
     use GrahamCampbell\Analyzer\Analyzer;
     use GrahamCampbell\Analyzer\AnalysisTrait;
     
     class AnalyzerCheck extends Command {
         use AnalysisTrait;
     
         protected function getPaths() { return [app_path(), base_path('src')]; }
         protected function getIgnored() { return ['tests/*', 'vendor/*']; }
     }
     

   • Integrate with Laravel Forge/Envoyer for pre-deploy validation.

4. PHPDoc Optimization (Ongoing):

   • Use analyzer to clean up PHPDoc inconsistencies (e.g., @method references).
   • Integrate with Laravel IDE Helper for syncing PHPDoc with runtime classes.

Compatibility

Sequencing

1. Phase 1: Core Validation (Week 1)

   • Validate use statements in app/ and src/ directories.
   • Block CI on failures.

2. Phase 2: PHPDoc Expansion (Week 2)

   • Enable PHPDoc validation for API Resources, Form Requests, and Policies.
   • Clean up stale PHPDoc references.

3. Phase 3: CI Optimization (Week 3)

   • Parallelize analysis for large codebases.
   • Cache results between runs (e.g., GitHub Actions cache).

4. Phase 4: Developer Adoption (Ongoing)

   • Add pre-commit hooks (e.g., Husky + Pint).