Psalm Plugin Laravel Package

Product Decisions This Supports

• Adoption of PHP Standard Library (PSL) for Type Safety Accelerate migration from Laravel’s built-in validation (e.g., Validator, FormRequest) to PSL-powered static contracts, reducing runtime overhead and production errors. This aligns with a roadmap to eliminate redundant validation layers by leveraging PSL’s type system for API contracts, Eloquent models, and service inputs/outputs. Example: Replace Validator::make($request->all(), [...]) with Psl\Type\shape() + Psalm static checks, cutting validation boilerplate by ~40% and enabling zero-cost abstractions at runtime.

• Strategic Shift to Static Analysis for Quality Gates Integrate Psalm with CI/CD pipelines to enforce PSL type correctness before code merges, reducing runtime bugs and improving code review efficiency. This supports a shift-left testing strategy, where static validation replaces manual QA for critical paths (e.g., payment processing, user auth). Example: Block PRs with Psalm errors for PSL-defined shapes, ensuring type safety at scale.

• Modernization of Legacy Laravel Codebases Prioritize this plugin for high-maintenance legacy projects where runtime validation dominates. By retrofitting PSL types to existing models/forms, Psalm can automatically infer shapes for arrays, reducing manual type annotations. This supports a low-risk modernization path without full rewrite costs. Example: Convert a FormRequest into a PSL shape and validate it statically, then incrementally replace runtime checks.

• API Contracts and Third-Party Integrations Define machine-verifiable API contracts using PSL shapes and enforce them via Psalm. This ensures consistency between Laravel’s validation and external systems (e.g., Stripe, payment gateways). Example: Define a Psl\Type\shape() for a webhook payload and use Psalm to validate all handlers, reducing runtime parsing errors by ~60%.

• Developer Experience (DX) and Onboarding Reduce false positives in IDE autocompletion and runtime type errors by enabling Psalm to accurately interpret PSL types. This improves DX, especially for teams adopting PSL or migrating from dynamic validation. Example: Psalm now correctly infers array{name: string, age: int} instead of ambiguous array<...>, enabling better refactoring support.

• Performance Optimization for High-Traffic Systems Replace runtime type checks (e.g., is_array(), array_key_exists()) with PSL/Psalm static validation, eliminating redundant operations in hot paths. Example: A high-traffic API endpoint processing 10K requests/sec could reduce validation overhead by ~30% by shifting checks to compile-time.

• Alignment with PHP 8.2+ and Modern PHP Features Justify Psalm adoption as a prerequisite for PHP 8.2’s typed arrays (array{...}) and nullish types by enabling precise static analysis. This plugin bridges PSL’s expressive types with Psalm, making it easier to adopt modern PHP features. Example: Use Psl\Type\nullish() with Psalm to enforce null|int return types, replacing runtime is_null() checks.

When to Consider This Package

• Adopt if:

  • Your team is already using PSL (PHP Standard Library) for type definitions (e.g., Psl\Type\shape, Psl\Iter, Psl\Str).
  • You’re migrating from runtime validation (e.g., Laravel’s Validator) to static contracts.
  • You need precise type inference for PSL types in Psalm (e.g., non-empty-array, literal strings).
  • Your codebase has legacy dynamic validation (e.g., array_key_exists(), loose is_array() checks) that could benefit from static enforcement.
  • You’re adopting PHP 8.2+ features (e.g., array{...} syntax) and want Psalm to understand PSL’s enhanced types.
  • Your CI/CD pipeline includes static analysis (e.g., Psalm, PHPStan), and you want to enforce PSL type correctness pre-merge.

• Look elsewhere if:

  • You’re not using PSL—this plugin is PSL-specific and won’t help with vanilla PHP or other libraries.
  • Your team relies heavily on runtime validation (e.g., FormRequest, manual Validator rules) without static typing.
  • You’re using PHPStan instead of Psalm—this plugin is Psalm-only (though PSL has a PHPStan plugin too).
  • Your project is small or prototype-based with no need for strict type contracts.
  • You lack developer buy-in for static analysis, as this requires Psalm integration and discipline.

How to Pitch It (Stakeholders)

For Executives:

*"This plugin lets us replace runtime validation with static type checks, cutting errors in production and reducing technical debt. By adopting PSL shapes and Psalm, we can:

• Eliminate ~40% of validation boilerplate (e.g., Validator rules) with zero runtime cost.
• Block bugs early via CI static analysis, reducing fire drills in high-traffic systems.
• Modernize legacy code without rewrites by retrofitting PSL types to existing models/forms.
• Justify PHP 8.2+ adoption with precise type safety for APIs and integrations. Investment: Low (Composer install + Psalm setup). ROI: Higher quality, faster onboarding, and reduced maintenance costs."

For Engineering Leaders:

*"This plugin bridges PSL’s expressive types with Psalm’s static analysis, giving us:

• Accurate type inference for PSL shapes (e.g., array{name: string} instead of array<...>).
• CI-enforced contracts for APIs, models, and services, reducing runtime surprises.
• Seamless migration from dynamic validation to static checks, with minimal refactoring.
• Better IDE support (fewer false positives, smarter autocompletion). Key ask: Pilot in 1–2 high-impact modules (e.g., payments, auth) to measure error reduction and dev productivity gains."

For Developers:

*"Psalm now understands PSL types correctly, so:

• Your Psl\Type\shape() definitions will auto-validate in Psalm, catching bugs before runtime.
• No more array_key_exists() hacks—use Psl\Type\shape() and let Psalm enforce it.
• Fewer runtime errors from type mismatches, especially in APIs and integrations. How to start: Add composer require php-standard-library/psalm-plugin, enable it, and let Psalm flag type issues in your PSL-heavy code."