Psalm Plugin Laravel Package

Product Decisions This Supports

• Build vs. buy: adopt the plugin instead of building custom Psalm extensions. The package is MIT-licensed, dev-only, and maintained under the php-standard-library organization. Writing and maintaining custom Psalm return-type providers for PSL would consume engineering time without creating product differentiation. Adopting this plugin is a low-cost “buy” decision that unlocks PSL’s type system inside Psalm.
• Roadmap: shift type validation left into CI. Add Psalm with this plugin as a CI gate for PSL-heavy modules. A sensible rollout is:
  1. Pilot on one high-risk module such as API payload handling, payments, or webhooks.
  2. Expand to modules where PSL Type\shape() already supplements or replaces runtime validation.
  3. Measure reduction in runtime validation code and type-related defects before broad rollout.
• Feature: statically verified, self-documenting data contracts. Use PSL shapes for request/response schemas, configuration payloads, and webhook bodies. With the plugin enabled, Psalm infers precise array shapes such as array{name: string, age: int, location?: array{city: string, state: string, country: string}} instead of broad array<...> unions. This improves IDE autocomplete and catches schema drift during analysis.
• Use cases: data-heavy and high-assurance paths. Financial webhooks, third-party API ingestion, Laravel API request validation, configuration validation, and data transformation pipelines benefit most. In Laravel, PSL shapes can complement Validator/FormRequest validation where static guarantees are more valuable than runtime-only checks.
• Product risk is low and reversible. The plugin is a dev dependency; it does not affect production runtime. If it proves noisy or incompatible, removal is a Composer and Psalm configuration change. The main adoption cost is requiring teams to use Psalm and PSL.
• Adoption risk is mainly ecosystem maturity. With 25 stars, 0 dependents, and a small contributor base, the plugin is niche. Treat it as a tactical enabler for teams already standardized on Psalm + PSL, not as a broad platform bet.

When to Consider This Package

• Consider adoption when:
  • Your team already uses Psalm for static analysis.
  • You use or plan to use PSL (php-standard-library/psl) for typed validation, collections, strings, or data transformation.
  • Your code relies on Psl\Type\shape(), Type\optional(), coerce(), or parse() and you want precise inferred types instead of broad unions.
  • You want stronger IDE autocomplete and earlier detection of schema drift in Laravel request/response payloads, webhook bodies, or configuration.
  • You are willing to add a dev dependency and run psalm-plugin enable php-standard-library/psalm-plugin.
  • Your versions align: PSL 2.x with plugin ^2.1 and Psalm v5, or PSL 2.x with plugin ~2.0.0 and Psalm v4; legacy PSL 1.x maps to plugin 1.x and Psalm v4.
• Look elsewhere when:
  • Your team does not use Psalm. If you use PHPStan or no static analysis, this plugin adds no value.
  • You do not use PSL’s Type component. The plugin’s primary value is PSL-specific type inference.
  • You need production runtime validation only. This is a static-analysis tool, not a runtime validator.
  • You require a large, battle-tested plugin ecosystem. The low star count and zero dependents suggest limited community validation; evaluate maintenance cadence and compatibility before broad rollout.
  • Version compatibility is a blocker. Confirm PSL, Psalm, and plugin versions match before committing to a migration.

How to Pitch It (Stakeholders)

• Executives: This is a low-cost, low-risk developer tool that improves type safety and reduces schema-related defects. It is MIT-licensed, used in development only, and reversible. Pilot it on one high-risk module to measure fewer runtime validation gaps, better IDE support, and reduced type-related bugs before wider adoption.
• Engineering: Enabling the plugin gives Psalm precise array shape inference for PSL Type\shape() and correct handling of optional keys. It catches bugs that Psalm’s default broad unions miss, improves autocomplete, and fits naturally into CI. Setup is one command, and it does not affect production runtime.
• Product and QA: The plugin turns PSL shape specifications into self-documenting, statically checked contracts for request/response payloads, webhook bodies, and configuration. This helps catch schema drift during CI rather than after deployment, while complementing existing Laravel validation rather than replacing runtime safeguards.