Weave Code
Psalm Plugin Laravel Package
php-standard-library/psalm-plugin
Psalm plugin for PHP Standard Library (PSL) that improves static analysis of PSL Type specifications. It gives Psalm precise inferred types for shapes and coerce results, such as exact array shapes instead of broad unions. Install with Composer as a dev dependency and enable via psalm-plugin.
Psalm integration for the PHP Standard Library
Frequently asked questions about Psalm Plugin
- What does the php-standard-library/psalm-plugin actually do?
- It is a Psalm extension that registers return-type providers for PSL's Type component, plus a long list of Str, Iter, and Regex functions. Without it, Psalm falls back to broad unions such as array<"age"|"location"|"name", ...>; with it enabled you get precise types like array{name: string, age: int, location?: array{city: string, state: string, country: string}}. The plugin changes only what Psalm infers and adds zero runtime footprint to your application.
- How do I install php-standard-library/psalm-plugin in a Laravel project?
- Run composer require php-standard-library/psalm-plugin --dev, then enable it with php vendor/bin/psalm-plugin enable php-standard-library/psalm-plugin. Commit the resulting change to psalm.xml so the plugin is active for every developer and in CI. Confirm the package lands in require-dev only and never in your production autoload.
- Does this plugin work with PHPStan or Larastan?
- No. It is a Psalm plugin only, so it does nothing for a PHPStan plus Larastan setup, which is the default static analysis stack in the Laravel ecosystem. Adopting it presupposes Psalm is already your analyzer of record, or that your team is willing to run a second analyzer. Because Larastan is PHPStan-only, a Psalm-first posture also means either losing Laravel-specific framework modeling or maintaining two configurations.
- Which PSL, plugin, and Psalm versions are compatible?
- The README pins an explicit three-way matrix: PSL 2.x with plugin ^2.1 on Psalm v5, PSL 2.x with plugin ~2.0.0 on Psalm v4, and PSL 1.x with plugin 1.x on Psalm v4. Psalm's plugin API is not a stable public contract, so major Psalm bumps have historically required plugin-side fixes. Standardize on one triple, document who owns that pin, and treat any Psalm or PSL upgrade as a coordinated three-way change.
- Does the plugin add any runtime overhead in production?
- No. It is a dev-only Psalm extension with no service surface, no data path, and no effect on application execution. It is installed under require-dev and is removable in a single commit if you decide to drop it. The only thing it modifies is the type information Psalm produces during static analysis.
- Why do I still see broad array unions after enabling the plugin?
- The plugin degrades silently: if it is disabled, misconfigured, or fails to register a provider, Psalm does not error, it just falls back to broad array<...> types. Verify the plugin is listed in psalm.xml, that your PSL, plugin, and Psalm versions match the compatibility matrix, and that the psalm-plugin enable step was actually committed. Add @psalm-trace snapshot assertions in CI so a lost return-type provider surfaces as a failing build rather than quiet loss of precision.
- Is the plugin useful if my codebase does not use PSL Type specifications?
- No, it is inert in that case. The plugin only adds value where PSL is already, or will become, your validation and typing layer, for example Type\shape() used for request payloads, webhook bodies, config schemas, or third-party API ingestion. In a codebase that relies on Laravel's Validator and plain arrays, there is nothing for the return-type providers to improve.
- Can it improve static analysis of Laravel request payloads and API responses?
- Conditionally yes. If you call something like Type\shape([...])->coerce($input) on a request or webhook payload, the plugin gives Psalm the exact inferred shape instead of a loose union, which improves bug detection and IDE completion. If you validate with Laravel's Validator and pass plain arrays around, the plugin contributes nothing. Treat the benefit as measurable only where PSL Type objects are already the boundary.
- How do I verify in CI that the plugin is still providing precise types?
- Use @psalm-trace snapshot assertions against key PSL shape calls so an unexpected widening to array<...> fails the build. Keep the Psalm baseline from bloating unexpectedly and track type coverage, for example via Shepherd, as a trend signal. Also assert in CI that the plugin remains enabled in psalm.xml and that the pinned PSL, plugin, and Psalm versions still match the compatibility matrix.
- What are the maintenance risks of depending on this plugin?
- Blast radius is low because it is a dev dependency removable in one commit, but the project has roughly 25 stars, zero dependents, and a small contributor set, so expect to be an early adopter hitting edge cases. It is maintained under the official php-standard-library org, which is reassuring, but it is not widely exercised. Return-type provider bugs typically under-approximate (missed bugs) rather than produce noisy false positives, so failures are quiet, and you should have an exit plan if Psalm 6 or PSL 3 land before the plugin catches up. Teams that stay on PHPStan plus Larastan simply skip this package and keep PSL without Psalm integration.
Weaver
How can I help you explore Laravel packages today?