Phpstorm Attributes Laravel Package

Product Decisions This Supports

• Making the "developer experience" investment case concrete. This package is a near-zero-cost lever for raising code quality without adding runtime complexity. It doesn't change behavior in production — it makes PhpStorm smarter for the people writing the code. For a PM, that's an easy win to bundle into existing work rather than justify as a standalone initiative.
• Deprecation and upgrade strategy. #[Deprecated] with reason and replacement turns a CHANGELOG line into an inline, actionable warning at every call site — including parameter substitution (e.g. %class%, %parameter0%) so the IDE quick-fix rewrites the call. Support for Laravel major-version upgrades (10 → 11, 11 → 12) and internal API sunsets is the strongest product justification: fewer "is this still safe to use?" Slack threads, and a measurable path to removing legacy surface area.
• API and payload contract clarity. Laravel codebases are full of structured arrays: JsonResource::toArray(), config() defaults, report aggregates, validator messages, DB::select() rows. #[ArrayShape] and #[ObjectShape] document those shapes next to the code, giving key autocomplete and type inference with no static-analyser setup. Product impact: fewer integration defects at boundaries, faster onboarding for engineers new to the domain, and less ambiguity in API documentation.
• Build vs buy. Build nothing. Apache-2.0, JetBrains-maintained, dev-only, bundled with PhpStorm 2020.3+, zero runtime footprint. An internal equivalent would be pure maintenance overhead.
• Roadmap prioritization input. Adoption is a one-line composer require --dev plus a convention, not an epic. Scope it as an enabler inside existing feature work — annotate new DTOs and resources as they're written, retrofit deprecations only when you touch them. No dedicated sprint required.
• Signal for engineering-standards conversations. If the team is investing in static analysis (PHPStan/Psalm), this package plus the phpstan-phpstorm extension gives CI-enforced contracts on purity and immutability — a cheap quality gate that complements, rather than replaces, a typed-DTO migration.

When to Consider This Package

Adopt when:

• The team standardizes on PhpStorm 2020.3+ as the primary IDE, and the project is PHP 8.0+ with Composer.
• You are actively executing deprecations — framework upgrades, API versioning, replacing custom helpers with first-party equivalents — and want migration hints surfaced inline rather than buried in release notes.
• Your Laravel app has many array/object-returning boundaries (API Resources, config providers, report builders, hydrators) where shapes are implicit and frequently misread.
• You want purity/immutability contracts enforced in CI via phpstan-phpstorm, with no runtime change.
• You need to support PHP ≤ 7.4 during transition — several attributes work on a single line.

Look elsewhere or defer when:

• The team uses VS Code, or a mixed-IDE environment where these attributes yield little benefit. Note this is a real constraint: the package is PhpStorm-specific by design.
• The project is pre-PHP 8 or does not use Composer-based dependency management.
• Existing tooling already covers the ground — typed DTOs, PHPStan generics, Psalm — where additional annotations are redundant noise and a second source of truth to keep in sync.
• The codebase is small or early-stage, where annotation overhead outweighs the returns.
• You would be tempted to over-annotate. Coverage should stay targeted at public APIs and critical data flows; blanket annotation degrades readability for little gain and creates maintenance drag.

Maturity note for the risk register: the package is a thin bag of ~8 attribute classes with a low-velocity release cadence and a single maintainer organization (JetBrains). Risk is low — attributes are inert at runtime and the package can be dropped at any time with no code change beyond deleting annotations — but it is a dependency owned by your IDE vendor, not your application. Keep it in require-dev and treat it as tooling, not architecture.

How to Pitch It (Stakeholders)

For executives: "This is a free, JetBrains-maintained tooling package that makes our IDE smarter about our own code — flagging deprecated APIs with the exact replacement, catching type mistakes in array and object payloads, and enforcing data contracts before code review reaches a human. It has zero impact on production performance, requires no infrastructure or configuration, and costs one dev-dependency line. Expected outcomes: faster delivery with fewer avoidable defects, a cleaner and more measurable story for deprecating and upgrading systems, and a lower onboarding ramp for engineers new to the codebase."

For engineering: "Add jetbrains/phpstorm-attributes as a dev dependency — no service provider, no config, no facade, no bootstrapping. Requirements are PHP 8+ and PhpStorm 2020.3+. The payoff: key autocomplete and type inference on JsonResource::toArray() and config arrays via #[ArrayShape]; typed dynamic objects such as DB::select() rows and json_decode(..., false) results via #[ObjectShape]; inline strikethrough warnings with IDE quick-fix rewrites on deprecated methods via #[Deprecated] with replacement parameter substitution; immutability contracts on value objects via #[Immutable]; accurate control-flow and dead-code analysis via #[NoReturn]; sharper type inference from #[Pure]; and enum-backed parameter suggestions via #[ExpectedValues]. Start with the two highest value-to-effort attributes: #[Deprecated] on anything currently tagged @deprecated in a docblock, and #[ArrayShape] on API Resources and report payloads. Attributes are ignored at runtime, so non-PhpStorm tools and CI see no behavior change. To get CI-level enforcement, add the phpstan-phpstorm extension. Retrofit high-traffic service boundaries afterward, and keep annotations targeted to public APIs and critical data flows — over-annotating internal methods hurts readability for little gain."