Psalm Laravel Package

Technical Evaluation

Architecture Fit

Psalm is a static analysis tool designed to identify errors, type inconsistencies, and security vulnerabilities in PHP applications. For a Laravel-based product, it aligns well with:

• Type Safety: Laravel’s dynamic nature (e.g., magic methods, dynamic properties) can introduce runtime errors. Psalm’s PHP 8+ type system support (e.g., union types, generics, enums) helps enforce stricter typing, reducing edge-case bugs.
• Security Analysis: Laravel apps often interact with external systems (APIs, databases, user input). Psalm’s taint tracking (e.g., TaintedLlmPrompt in v7.0) detects injection risks (SQLi, XSS) and unsafe operations (e.g., eval, unserialize).
• Legacy Code Modernization: Laravel’s older codebases (pre-PHP 8) benefit from Psalm’s backward-compatible type inference, gradually introducing types via @var, @param, and @return annotations.
• Plugin Ecosystem: Psalm’s plugin API (v7.0+) enables custom rules for Laravel-specific patterns (e.g., Eloquent query validation, Blade template safety).

Misalignment Risks:

• Performance Overhead: Psalm’s analysis is CPU-intensive (JIT disabled by default in v7.0). Large Laravel monorepos may require parallel scanning or incremental analysis (e.g., --no-cache for CI, cached results locally).
• False Positives: Laravel’s dynamic features (e.g., Model::find(), collect()) may trigger noise. Psalm’s --ignore-missing and custom stubs (e.g., for Illuminate\Support) can mitigate this.

Integration Feasibility

Key Dependencies:

• PHP Version: Psalm 7.0+ requires PHP 8.1+; Laravel 10+ is compatible.
• Composer: Must be installed globally or via dev dependency (require-dev vimeo/psalm:^7.0).
• IDE Integration: Supports PhpStorm, VSCode (via psalm-ide-helper), and CLI.

Technical Risk

Critical Questions for TPM:

1. Adoption Strategy:
   • Should Psalm be mandatory (block PRs on failures) or recommended (opt-in for teams)?
   • How will false positives be triaged (e.g., dedicated Slack channel, GitHub label)?
2. Performance:
   • What’s the acceptable scan time for the largest codebase (e.g., 10M LOC)?
   • Can incremental analysis (e.g., --changed-files) be implemented in CI?
3. Tooling:
   • Should Psalm replace PHPStan or run in parallel?
   • How will Blade template analysis be handled (e.g., pre-compilation hook)?
4. Maintenance:
   • Who owns stub updates (e.g., new Laravel versions)?
   • What’s the SLA for Psalm rule updates (e.g., new Laravel security patches)?

Integration Approach

Stack Fit

Migration Path

1. Phase 1: Pilot (2-4 Weeks)

   • Scope: Single Laravel module (e.g., auth or api).
   • Actions:
     • Install Psalm (composer require-dev vimeo/psalm).
     • Configure psalm.xml with basic rules (e.g., NoUnresolvableReferences).
     • Run in CI with --no-cache and monitor false positives.
   • Goal: Establish baseline error count and triage process.

2. Phase 2: Gradual Rollout (4-8 Weeks)

   • Scope: Expand to core services (e.g., users, payments).
   • Actions:
     • Add custom stubs for unsupported Laravel classes (e.g., Illuminate\Auth).
     • Introduce mutability annotations (@psalm-pure, @psalm-mutation-free) via --alter.
     • Integrate with IDE for real-time feedback.
   • Goal: Reduce critical errors by 30% (e.g., Nullsafe violations).

3. Phase 3: Full Integration (8-12 Weeks)

   • Scope: Entire codebase + Blade templates (if feasible).
   • Actions:
     • Implement plugin for Laravel-specific rules (e.g., Eloquent query validation).
     • Configure CI to block high-severity issues (e.g., TaintedLlmPrompt).
     • Train teams on annotating code (e.g., @psalm-param, @psalm-return).
   • Goal: Zero high-severity Psalm errors in production-critical paths.

4. Phase 4: Optimization (Ongoing)

   • Actions:
     • Cache analysis results in CI for faster runs.
     • Automate stub generation for new Laravel packages.
     • Benchmark performance and adjust --threads/--memory-limit.

Compatibility