Analyzer Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Native Compatibility: Designed for PHP/Laravel ecosystems, leveraging PHPUnit for integration. Aligns with Laravel’s dependency injection, facade patterns, and service container where class reference errors are common.
• Static Analysis Focus: Specializes in class existence validation (not method/property signatures), making it a lightweight complement to PHPStan/Psalm. Ideal for pre-deployment CI checks rather than runtime validation.
• PHPDoc Support: Validates @method, @property, and @var annotations, critical for IDE tooling (PhpStorm/VSCode) and API documentation (OpenAPI/Swagger).
• Modular Design: Uses traits (AnalysisTrait) for easy integration into existing test suites or custom scripts.

Integration Feasibility

• PHPUnit Dependency: Requires PHPUnit 10–13 (Laravel 9+ default) and PHP 8.1–8.5. Low friction for modern Laravel projects.
• Composer Integration: Installs as a dev dependency, avoiding runtime overhead.
• Test Suite Hooks: Can be embedded in phpunit.xml as a pre-test step or triggered via CLI for ad-hoc validation.
• Laravel-Specific Use Cases:
  • Service Providers: Validate bind()/singleton() references.
  • Middleware/Events: Check class existence in handle() methods.
  • API Resources: Ensure toArray() references valid models.
  • Policies/Rules: Validate authorize()/rules() class dependencies.

Technical Risk

Key Questions for TPM

1. Scope of Validation:
   • Should this run only in CI or also in pre-commit hooks (e.g., Husky)?
   • Which file patterns should be analyzed (e.g., exclude vendor/, tests/)?
2. False Positive Handling:
   • How will the team triage ignored classes (e.g., App\Services\Legacy\*)?
   • Should whitelists be maintained in config or code?
3. CI/CD Integration:
   • Where in the pipeline should this run? (e.g., pre-test, post-build)
   • Should failures block merges or just warn?
4. PHPDoc Strategy:
   • Should strict mode (fail on missing classes) or lenient mode (warn only) be default?
   • How will generated PHPDoc (e.g., from IDEs) be handled?
5. Long-Term Maintenance:
   • Who owns updating ignored classes as the codebase evolves?
   • Should this be extended for custom namespace resolvers (e.g., use App;)?

Integration Approach

Stack Fit

• PHP/Laravel Ecosystem: Optimized for Laravel 9+, PHP 8.1+, and PHPUnit 10+.
• CI/CD Tools: Works with GitHub Actions, GitLab CI, CircleCI, or Laravel Forge/Envoyer.
• IDE/Editor: Complements PhpStorm, VSCode, and PHPStorm via PHPDoc validation.
• Static Analysis Tools: Complements (not replaces) PHPStan/Psalm by focusing only on class references.

Migration Path

1. Assessment Phase:
   • Audit current class reference errors (e.g., via Sentry/Rollbar) to prioritize high-impact areas.
   • Identify legacy patterns (e.g., use App; aliases) that may need pre-processing.
2. Pilot Integration:
   • Add to a single test suite (e.g., Feature\Api\*).
   • Configure getIgnored() to exclude non-critical paths.
3. CI/CD Rollout:
   • Add as a pre-test step in phpunit.xml:

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

   • Or run via custom script:

     ./vendor/bin/phpunit --testdox-html --filter AnalyzerTest
     

4. Gradual Expansion:
   • Enable for Service Providers, Middleware, and API Resources first.
   • Later, extend to PHPDoc validation for OpenAPI/Swagger.

Compatibility

Sequencing

1. Phase 1: CI-Only Validation (2–4 weeks)
   • Run in CI pipeline with lenient mode (warnings only).
   • Focus on Service Providers, Middleware, and API Resources.
2. Phase 2: Pre-Commit Hooks (Optional, 1–2 weeks)
   • Integrate with Husky/Git Hooks for local validation.
3. Phase 3: PHPDoc Enforcement (2–3 weeks)
   • Enable strict PHPDoc checks for OpenAPI/Swagger projects.
4. Phase 4: Ignored Classes Management
   • Document and automate updates to getIgnored() as the codebase evolves.

Operational Impact

Maintenance

• Low Overhead:
  • No runtime impact (dev dependency only).
  • Minimal configuration (mostly getIgnored() and getPaths()).
• Ignored Classes Management:
  • Requires periodic updates as the codebase evolves (e.g., deprecated classes).
  • Automation opportunity: Script to auto-generate ignored lists from composer.json or config/app.php.
• Dependency Updates:
  • Pin to v5.1 to avoid breaking changes (PHP 8.5 + PHPUnit 13).
  • Monitor Graham Campbell’s releases for Laravel-specific fixes.

Support

• Troubleshooting Common Issues:

  Issue	Solution
  False positives in vendor/	Exclude via getIgnored(['vendor/*']) in AnalysisTrait.
  PHPDoc errors in generated files	Use shouldAnalyzeFile() to skip migrations/, factories/.
  Slow CI runs	Limit to critical paths (provideFilesToCheck()).
  Custom namespace aliases	Pre-process aliases before analysis (e.g., use App; → App\Models).

• Documentation Gaps:
  • No Laravel-specific examples in the README (TPM must provide Laravel use cases).
  • PHPDoc filtering could be clearer (e.g., how to exclude @internal classes).

Scaling

• Performance:
  • Lightweight: Only parses class references, not full static analysis.
  • CI Optimization: Run in parallel with other tests or as a pre-step.
  • Large Codebases: Use provideFilesToCheck() to target specific directories.
• Team Adoption:
  • Onboarding: Add to developer docs as a "Class Reference Check" step.
  • Training: Highlight common failure modes (e.g., typos