Psalm Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Integration: Psalm is a PHP static analysis tool designed to complement Laravel’s existing tooling (PHPStan, PHPUnit, Pest). It integrates seamlessly into CI/CD pipelines via CLI, making it ideal for pre-commit hooks, GitHub Actions, or custom workflows.
• Type Safety & Security: Psalm’s fine-grained type inference and security-focused analysis (e.g., taint tracking, prompt injection detection) align with Laravel’s emphasis on type safety (e.g., PHP 8.1+ attributes, return type hints).
• Plugin Ecosystem: The new plugin API (v7.0+) allows custom rules, enabling TPMs to extend Psalm for Laravel-specific concerns (e.g., Eloquent query validation, Blade template analysis).
• Performance: Psalm’s JIT (Just-In-Time) compilation (opt-in) and project caching reduce analysis time, critical for large Laravel monorepos.

Integration Feasibility

• Laravel Compatibility:
  • Supports PHP 8.0+ (Laravel’s LTS versions).
  • Works with composer-based projects (no framework-specific dependencies).
  • Stub files for Laravel’s core (e.g., Illuminate\Support, Illuminate/Database) are auto-generated or manually configurable.
• CI/CD Readiness:
  • Lightweight CLI (psalm --init generates config) integrates with GitHub Actions, GitLab CI, or CircleCI.
  • Parallel analysis possible via --workers flag for monorepos.
• IDE Support:
  • PhpStorm/JetBrains integration via phpstorm.php config (included in Laravel IDE Helper packages).
  • VS Code via php-pact or intelephense plugins.

Technical Risk

• False Positives/Negatives:
  • Psalm’s strictness may flag Laravel’s magic methods (e.g., __get, __set) or dynamic properties as errors. Mitigation: Configure psalm.xml to ignore specific files/classes.
  • Security analysis (e.g., taint tracking) may misidentify Laravel’s dependency injection or service containers as unsafe. Solution: Use @psalm-suppress or custom stubs.
• Configuration Complexity:
  • Requires initial setup (psalm.xml, psalm-discover.xml for multi-project setups). Risk: Misconfiguration leads to noisy output or missed issues.
  • Autofix limitations: Some annotations (e.g., @psalm-pure) require manual review.
• Performance Overhead:
  • Full analysis on large codebases (e.g., Laravel + Forge) may slow CI. Mitigation: Use --no-cache sparingly, leverage incremental analysis.
• Breaking Changes:
  • v7.0+ introduces mutability annotations (e.g., @psalm-pure), which may require backward-compatible migration for existing codebases.

Key Questions for TPM

1. Adoption Strategy:
   • Should Psalm replace PHPStan (which Laravel already uses) or run in parallel?
   • How will false positives be triaged (e.g., via psalm:fix or manual review)?
2. CI/CD Impact:
   • What thresholds (error levels) will trigger CI failures (e.g., ERROR, WARNING)?
   • How will analysis time be optimized (e.g., caching, parallel workers)?
3. Developer Experience:
   • Will Psalm be mandatory in PRs or opt-in for teams?
   • How will IDE integration be standardized (e.g., PhpStorm vs. VS Code)?
4. Long-Term Maintenance:
   • Who will curate stub files for Laravel’s evolving APIs (e.g., new Eloquent features)?
   • How will plugin development be governed (e.g., internal vs. community plugins)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • PHP 8.1+: Psalm’s enhanced type system (e.g., union types, attributes) aligns with Laravel’s modern PHP support.
  • Composer: Psalm is a composer package (vimeo/psalm), requiring no framework-specific changes.
  • Testing Tools: Complements Pest/PHPUnit by catching logical errors (e.g., null returns, type mismatches) before runtime.
• Toolchain Synergy:
  • PHPStan: Psalm can validate stub files generated by PHPStan or vice versa.
  • Laravel Pint: Psalm’s code analysis can run alongside code formatting in CI.
  • Git Hooks: Integrate with Laravel’s php-cs-fixer via pre-commit hooks.

Migration Path

1. Pilot Phase:
   • Single Project: Start with a non-critical Laravel package (e.g., a microservice).
   • Gradual Rollout: Use --init to generate psalm.xml, then adjust config (e.g., ignore vendor/, storage/).
   • Error Level Tuning: Begin with --level=1 (errors only), then expand to warnings.
2. Full Adoption:
   • CI Integration: Add Psalm to GitHub Actions (example workflow below).
   • IDE Setup: Configure PhpStorm/VS Code for real-time feedback.
   • Autofix: Use --alter for safe fixes (e.g., adding @var annotations).
3. Advanced Customization:
   • Stub Files: Generate stubs for custom Laravel packages using psalm-plugin.
   • Plugins: Develop Laravel-specific rules (e.g., validate HasFactory usage).

Compatibility

Sequencing

1. Phase 1: Setup & Configuration
   • Install Psalm globally or via project composer.json.
   • Generate psalm.xml and adjust for Laravel’s structure:

     <projectFiles>
         <directory name="app" />
         <directory name="src" />
         <exclude-name>*.blade.php</exclude-name>
     </projectFiles>
     

   • Configure error levels (e.g., fail CI on ERROR only).
2. Phase 2: Initial Analysis
   • Run psalm --init to generate a baseline.
   • Use --stats to identify high-error-density files.
3. Phase 3: CI/CD Integration
   • Add to .github/workflows/psalm.yml:

     - name: Psalm
       run: vendor/bin/psalm --no-cache --output-format=github
     

   • Set failure thresholds (e.g., ERROR level).
4. Phase 4: Optimization
   • Cache analysis results for faster CI runs.
   • Parallelize with --workers=4.
   • Autofix safe issues (--alter --issues=MissingReturnType).
5. Phase 5: Advanced Use Cases
   • Develop custom plugins for Laravel-specific rules.
   • Integrate with security scanning (e.g., TaintedLlmPrompt for API inputs).

Operational Impact

Maintenance

• Configuration Drift:
  • Risk: psalm.xml may become outdated as Laravel evolves.
  • Mitigation: Use versioned configs (e.g., psalm.xml.v8.1, psalm.xml.v10) and template files for new projects.
• Stub File Management:
  • Risk: Manual stubs for custom packages require updates.
  • Mitigation: Automate stub generation via psalm-plugin or CI scripts.
• Dependency Updates:
  • Risk: Psalm’s PHP version support may lag Laravel’s.
  • **Mitigation