Psalm Plugin Laravel Package

Technical Evaluation

Architecture Fit

• Psalm Integration: The plugin is a Psalm plugin, meaning it extends Psalm’s static analysis capabilities rather than replacing or competing with it. This aligns well with Laravel’s existing tooling (e.g., Pest, PHPUnit, Laravel Pint) and avoids fragmentation.
• PSL (PHP Standard Library) Synergy: The plugin enhances type inference for PSL’s Type, Iter, Str, and Regex components, which are increasingly used in Laravel for data validation, transformations, and collections. This reduces the need for custom type logic in business layers.
• Laravel Compatibility: Laravel’s request validation, API contracts, and Eloquent models could benefit from PSL shapes + Psalm enforcement, but the plugin itself is framework-agnostic. The TPM must define how to bridge PSL/Psalm with Laravel’s validation layer (e.g., replacing Validator::make() with PSL shapes where possible).
• Type Safety for Collections: Laravel’s Collection class could leverage PSL’s Iter and Type for statically typed operations, reducing runtime errors in loops/transformations.

Integration Feasibility

• Low Friction: Installation is Composer-based (composer require --dev) and activation is a one-liner (psalm-plugin enable). No Laravel-specific configuration is required.
• Psalm Version Lock: The plugin supports Psalm 4/5, but Laravel teams often use Psalm 5+. Verify compatibility with the latest Psalm (e.g., 5.x) and Laravel’s PHP version (e.g., 8.2+).
• CI/CD Readiness: The plugin can run in CI pipelines (e.g., GitHub Actions) alongside Laravel’s existing static analysis tools (e.g., Pest, PHPStan). Example workflow:

  - name: Psalm + PSL Plugin
    run: vendor/bin/psalm --init --plugins=Psl\Psalm\Plugin
  

• IDE Support: Psalm’s IDE integration (e.g., PHPStorm, VSCode) will automatically reflect PSL type improvements, enhancing developer productivity.

Technical Risk

Key Questions for the TPM

1. Strategic Alignment:

   • Does this plugin align with the team’s shift-left or quality gates initiatives?
   • Should we replace Laravel’s Validator with PSL shapes in new features, or use them side-by-side?

2. Adoption Path:

   • Which modules should pilot this first? (e.g., API contracts, payment processing)
   • How will we measure success? (e.g., % reduction in runtime validation errors, CI pass rate)

3. Toolchain Integration:

   • Should Psalm results block PR merges (e.g., GitHub branch protection)?
   • How will we handle IDE vs. CI discrepancies (e.g., local Psalm config vs. CI)?

4. Long-Term Vision:

   • Could this enable statically verified API schemas (e.g., OpenAPI + PSL)?
   • Should we contribute Laravel-specific PSL types (e.g., for Carbon, Illuminate\Support) upstream?

Integration Approach

Stack Fit

• Psalm + PSL Plugin: Works alongside Laravel’s existing stack (PHP 8.2+, Composer, CI/CD).
• Laravel-Specific Considerations:
  • Request Validation: Replace Validator::make() with PSL shapes where possible (e.g., API payloads).
  • Eloquent Models: Use PSL shapes for attribute casting (e.g., protected $casts = ['email' => Type\email_address()]).
  • Collections: Leverage PSL’s Iter for statically typed Collection operations.
• Alternatives Considered:
  • PHPStan: Less PSL-native than Psalm; would require custom rules.
  • Custom Validation: Higher maintenance; PSL provides batteries-included types.

Migration Path

Compatibility

• Psalm 5.x: Confirmed compatible (see release notes).
• PHP 8.2+: Plugin fixes PHP 8.2 deprecations (PR #11).
• Laravel-Specific:
  • Request Data: PSL shapes may conflict with dynamic $_GET/$_POST. Use @psalm-suppress or runtime coercion.
  • Service Container: PSL types won’t interfere with Laravel’s DI, but static analysis may flag unused bindings.

Sequencing

1. Enable in CI: Start with a non-blocking Psalm check (e.g., --no-cache).
2. Pilot Module: Choose a low-risk module (e.g., a non-critical API endpoint).
3. Gradual Enforcement: Add Psalm to pre-commit after stabilizing the pilot.
4. Replace Validation: In new features, default to PSL shapes for API contracts.
5. Deprecate Legacy: Phase out Validator::make() in favor of PSL where Psalm can verify types.

Operational Impact

Maintenance

• Plugin Updates: Monitor GitHub Releases for Psalm compatibility.
• Psalm Configuration: Maintain a psalm.json with:

  {
    "plugins": ["Psl\\Psalm\\Plugin"],
    "typeCoverageAnalysis": true,
    "suppressInvalidPsr4": true
  }
  

• Dependency Management: Pin php-standard-library/psl and vimeo/psalm to specific versions in composer.json.

Support

• Developer Onboarding:
  • Document PSL shape examples in a PSL_GUIDE.md.
  • Provide a Psalm cheat sheet for Laravel devs (e.g., @psalm-var, @psalm-suppress).
• Common Issues:
  • False Positives: Teach teams to use @psalm-suppress judiciously.
  • IDE Lag: Cache Psalm results locally (psalm --cache).

Scaling

• Performance:
  • CI: Use psalm --cache and parallelize analysis.
  • Local Dev: Cache results to avoid full scans on every file save.
• Team Growth:
  • Onboarding: New hires should run composer require --dev php-standard-library/psalm-plugin as part of setup.
  • Code Reviews: Enforce Psalm checks in PR templates.

Failure Modes

| Failure Mode