Static Analysis Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Tooling: The package is a meta-package aggregating dependencies for static analysis (primarily Psalm, a PHP static analyzer). It aligns well with Laravel/PHP projects seeking type safety, code quality, and maintainability via static checks.
• Complementary to Laravel: While Laravel itself is dynamically typed, integrating Psalm can enforce stricter type contracts, improving refactoring safety and catching edge cases early (e.g., method signatures, return types, or undefined properties).
• Non-Intrusive: The package does not modify runtime behavior; it’s purely a development-time tool, reducing technical debt without impacting production performance.

Integration Feasibility

• Low Barrier to Entry: Requires only:
  1. Composer dependency installation (--dev scope).
  2. Configuration file (psalm.xml) setup.
• Psalm Compatibility: Psalm is a mature tool with Laravel support (via plugins like vimeo/psalm or laravel/psalm-plugin). The package abstracts dependency management, simplifying setup.
• Laravel-Specific Considerations:
  • Framework-Specific Types: Laravel’s dynamic features (e.g., magic methods, dynamic properties) may require Psalm configuration tuning (e.g., @mixin, @property annotations).
  • Testing Integration: Psalm can run alongside PHPUnit/Pest, but may need baseline files to suppress false positives in legacy code.

Technical Risk

• False Positives/Negatives: Psalm’s accuracy depends on codebase maturity and annotation coverage. Laravel’s dynamic nature (e.g., __get(), __call()) may trigger noise.
• Tooling Overhead: Requires developer buy-in for static analysis in CI/CD pipelines (e.g., failing builds on errors).
• Dependency Bloat: The meta-package pulls in Psalm + analyzers (e.g., phpstan/extension-installer), which may increase composer.json complexity.
• Future-Proofing: Psalm is actively maintained, but Laravel’s evolving ecosystem (e.g., Symfony components) may require configuration updates.

Key Questions

1. Static Analysis Goals:
   • Is the primary objective type safety, code quality, or compliance (e.g., PSR-12)?
   • Should Psalm replace or supplement existing tools (e.g., PHPStan, PHPMD)?
2. Laravel-Specific Challenges:
   • How will Psalm handle dynamic Laravel features (e.g., Illuminate\Support\Facades)?
   • Are there legacy codebases with undefined properties/methods requiring @mixin?
3. CI/CD Integration:
   • Should Psalm block merges (fail builds) or run as a pre-commit hook?
   • What error thresholds (e.g., errorLevel) are acceptable?
4. Maintenance:
   • Who will curate Psalm configurations (e.g., suppressing false positives)?
   • How will the team adapt to Psalm’s evolving rules?

Integration Approach

Stack Fit

• PHP/Laravel Ecosystem: Psalm is PHP-native and integrates seamlessly with Laravel’s dependency injection, Facades, and Blade templates (with annotations).
• Toolchain Synergy:
  • Composer: --dev scope ensures no runtime impact.
  • PHPUnit/Pest: Psalm can run alongside tests (e.g., via phpunit.xml configuration).
  • IDE Support: Psalm provides autocompletion and type hints in VSCode/PHPStorm.
• Alternatives Considered:
  • PHPStan: More strict but less Laravel-aware; may require more configuration.
  • In-house Rules: Custom PHPCS/PHPMD rules lack type safety.

Migration Path

1. Pilot Phase:
   • Install in a non-critical branch (composer require --dev innmind/static-analysis).
   • Configure psalm.xml with lenient settings (errorLevel="3" → start).
   • Run ./vendor/bin/psalm --init to generate a baseline.
2. Incremental Adoption:
   • Phase 1: Focus on src/ directory; ignore vendor/ and tests/ initially.
   • Phase 2: Add Laravel-specific configurations (e.g., @mixin for Facades).
   • Phase 3: Integrate with CI (e.g., fail builds on errorLevel="1").
3. Tooling Setup:
   • Add Psalm to composer.json scripts:

     "scripts": {
       "psalm": "vendor/bin/psalm --no-cache",
       "psalm-fix": "vendor/bin/psalm --fix"
     }
     

   • Configure IDE plugins (e.g., VSCode’s Psalm extension).

Compatibility

• Laravel Versions: Psalm supports Laravel 8+ (via vimeo/psalm or laravel/psalm-plugin). For older versions, manual configuration may be needed.
• Dependency Conflicts: The meta-package pulls in Psalm + analyzers, which may conflict with existing phpstan/extension-installer or roave/security-advisories. Resolve via composer.json overrides.
• Custom Code: Psalm may flag dynamic Laravel patterns (e.g., __get() in models). Mitigate with:

  <mixins>
    <mixin from="Illuminate\Database\Eloquent\Model" />
  </mixins>
  

Sequencing

Operational Impact

Maintenance

• Configuration Drift: Psalm rules and Laravel’s internals evolve. Quarterly reviews of psalm.xml and @mixin annotations are recommended.
• Dependency Updates: The meta-package may pull in new Psalm versions with breaking changes. Pin versions in composer.json if stability is critical:

  "require-dev": {
    "innmind/static-analysis": "^1.0",
    "vimeo/psalm": "^5.0"
  }
  

• False Positive Management: Maintain a baseline file (psalm-baseline.xml) and document suppressed errors.

Support

• Onboarding: Developers must learn:
  • Psalm’s error codes (e.g., MixedReturnType, UndefinedClass).
  • Laravel-specific annotations (e.g., @mixin, @property).
• Debugging Workflow:
  • Psalm errors may point to Laravel framework issues (e.g., undefined Facade methods). Escalate to Laravel’s issue tracker if needed.
  • Use --no-cache flag to bypass stale analysis.
• Support Channels:
  • Psalm: GitHub Discussions.
  • Laravel: Laravel Psalm Plugin.

Scaling

• Performance:
  • Psalm scans all src/ files by default. For large codebases, use:

    <projectFiles>
      <directory name="src" excludeFiles="\\.blade\\.php$" />
    </projectFiles>
    

  • Cache results with --cache-globals for faster subsequent runs.
• Parallelization: Psalm supports parallel analysis (--parallel) in CI.
• Distributed Teams: Centralize psalm.xml in a monorepo or shared config repo.

Failure Modes

Ramp-Up

• Training:
  • Workshop: 1-hour session on Psalm basics + Laravel annotations.
  • Cheat Sheet: Document common Psalm