Analyzer Laravel Package

Technical Evaluation

Architecture Fit

• Laravel/PHPUnit Ecosystem Alignment: Designed for PHPUnit integration, making it a seamless fit for Laravel’s testing-first workflow. Leverages PHPUnit’s test suite for validation, reducing friction in adoption.
• Lightweight Static Analysis: Focuses exclusively on class reference validation (no method/property signature checks), avoiding overlap with PHPStan/Psalm. Ideal for complementary use in CI pipelines.
• Modular Design: Uses traits (AnalysisTrait) for extensibility, allowing customization of:
  • File paths to analyze (getPaths()).
  • Ignored classes/methods (getIgnored()).
  • File filtering logic (shouldAnalyzeFile()).
• PHP 8.x/Modern PHPUnit Support: Native support for PHP 8.1–8.5 and PHPUnit 10–13, aligning with Laravel 10+ and modern PHP stacks.

Integration Feasibility

• Composer Integration: Zero-configuration via composer require --dev, with no runtime dependencies (dev-only).
• PHPUnit Hooks: Can be integrated as a pre-test hook or standalone test class, fitting into:
  • Laravel’s phpunit.xml configuration.
  • CI pipelines (GitHub Actions, GitLab CI, etc.).
• Laravel-Specific Use Cases:
  • Validating service providers, event listeners, and API resources before deployment.
  • Ensuring PHPDoc consistency in Form Requests, Policies, and API contracts.
• CI/CD Readiness: Designed for fast feedback (sub-second execution for medium codebases), making it ideal for pre-merge gates.

Technical Risk

Key Questions for TPM

1. CI Pipeline Impact:
   • How will this integrate with existing pre-commit hooks (e.g., Laravel Pint, Pest)?
   • Should it fail builds or warn only (configurable via PHPUnit exit codes)?
2. False Positive Handling:
   • What classes/interfaces should be whitelisted (e.g., Laravel’s Illuminate\Support\Facades\Route)?
   • How to handle third-party SDKs (e.g., Stripe’s PHPDoc classes)?
3. Performance Baseline:
   • What’s the max acceptable runtime for the team’s codebase?
   • Should it run only on changed files (via Git diff) or full scans?
4. Laravel-Specific Customization:
   • Should it skip vendor/laravel/ files by default?
   • How to handle dynamic proxies (e.g., Eloquent relationships)?
5. Maintenance:
   • Who owns updating ignored classes as the codebase evolves?
   • Should it be version-locked or floating in composer.json?

Integration Approach

Stack Fit

• PHPUnit-Centric: Leverages PHPUnit’s test runner, making it a natural fit for Laravel’s testing infrastructure.
• Dev-Only Dependency: Installed via --dev, avoiding runtime overhead.
• Composer Compatibility: No conflicts with Laravel’s core dependencies (tested with PHP 8.1–8.5).
• Toolchain Synergy:
  • GitHub Actions/GitLab CI: Add as a pre-test job.
  • Laravel Forge/Envoyer: Deploy only if tests pass.
  • Local Dev: Integrate with Laravel Valet/Sail via phpunit --testdox-html.

Migration Path

1. Pilot Phase:
   • Install in a feature branch:

     composer require --dev graham-campbell/analyzer:^5.1
     

   • Create a custom test class extending AnalyzerTestCase:

     use GrahamCampbell\Analyzer\AnalyzerTestCase;
     
     class ClassReferenceTest extends AnalyzerTestCase
     {
         protected static function getPaths(): array
         {
             return [__DIR__ . '/../../app', __DIR__ . '/../../config'];
         }
     
         protected static function getIgnored(): array
         {
             return [
                 'Illuminate\\*', // Skip Laravel core
                 'Laravel\\SerializableClosure', // Dynamic classes
             ];
         }
     }
     

2. CI Integration:
   • Add to phpunit.xml:

     <phpunit>
         <extensions>
             <extension class="GrahamCampbell\Analyzer\Extension"/>
         </extensions>
     </phpunit>
     

   • Or run as a separate CI job:

     # GitHub Actions example
     - name: Run Class Reference Analyzer
       run: vendor/bin/phpunit --testdox-html --colors=never tests/ClassReferenceTest
     

3. Gradual Rollout:
   • Start with critical paths (e.g., app/Providers, app/Http/Controllers).
   • Expand to PHPDoc-heavy modules (e.g., API resources, Form Requests).

Compatibility

    - `eval()` or `create_function()`.
    - Runtime namespace aliases (e.g., `use App;`).
    - Dynamic proxies (e.g., Eloquent’s `HasMany` relationships).                   |

| Third-Party SDKs | Whitelist SDK PHPDoc classes (e.g., Stripe\*) in getIgnored(). |

Sequencing

1. Pre-Analysis:
   • Run composer dump-autoload to ensure autoloader is up-to-date.
   • Exclude generated files (e.g., bootstrap/cache/) from analysis.
2. Analysis Execution:
   • Option A: As a PHPUnit extension (runs with every test suite).
   • Option B: As a standalone test class (runs in CI).
3. Post-Analysis:
   • Fail builds on errors (default PHPUnit behavior).
   • Generate reports (e.g., --testdox-html) for developer feedback.

Operational Impact

Maintenance

• Low Overhead:
  • No runtime maintenance (dev-only package).
  • Update strategy: Pin to ^5.1 for PHP 8.5 support; monitor for breaking changes.
• Ignored Classes Management:
  • Maintain a centralized whitelist (e.g., config/analyzer.php) for:
    • Laravel core classes (Illuminate\*).
    • Third-party SDKs (Stripe\*, PayPal\*).
    • Dynamic classes (e.g., Laravel\SerializableClosure).
• False Positive Handling:
  • Automated: Use getIgnored() for known safe classes.
  • Manual: Document exceptions in README.md or CONTRIBUTING.md.

Support

• Troubleshooting:
  • Common Issues:
    • False positives from typo-prone PHPDoc (e.g., @property App\Post $post).
    • Missing autoload entries (run composer dump-autoload).
  • Debugging Tools:
    • Run with --verbose to see skipped files.
    • Use --filter to test specific paths.
• Documentation:
  • Add a .analyzer.md file with:
    • Whitelisted classes.
    • Known limitations (e.g., dynamic proxies).
    • Example configurations.
• Escalation Path:
  • For parser errors, check [PHP Parser v2 issues](