Phpstorm Attributes Laravel Package

Getting Started

Install as a dev dependency with composer require --dev jetbrains/phpstorm-attributes. No bootstrapping or config changes are needed — PhpStorm 2020.3+ recognizes these attributes out of the box. Start by applying #[Deprecated] to methods scheduled for removal (e.g., deprecated APIs in Laravel service providers), and use #[ArrayShape] on functions returning structured arrays like config() results or API response payloads. These two yield the biggest immediate IDE improvement with minimal effort.

Implementation Patterns

• Refactoring Safeguards: Tag deprecated methods/properties with #[Deprecated(reason: '…', replacement: '…')] in Laravel packages to provide inline warnings and automated find/replace hints in PhpStorm — invaluable during upgrades (e.g., Laravel 10 → 11 migrations).
• Type-Safe Configuration & DTOs: Use #[ArrayShape([...])] on methods returning config structures (e.g., custom service provider configs) or #[ObjectShape([...])] for dynamic object hydrations from Eloquent or external APIs — enables autocomplete for keys like 'timeout' => 'int'.
• Performance & Safety Tuning: Annotate pure helper functions (#[Pure]) in utility classes to let PhpStorm flag unused calls and improve type inference. Mark #[NoReturn] methods like abort(403) wrappers or terminal CLI commands to improve dead-code detection.
• Input Validation Clarity: Apply #[ExpectedValues(valuesFromClass: Status::class)] on controller/route parameters (Status::class being an enum) to restrict autocomplete and surface invalid value warnings at edit time.
• DTO Immutability Contracts: Apply #[Immutable] to value objects (e.g., Money, EmailAddress) to signal immutability expectations — PhpStorm will warn about direct writes and integrate with static analysis tools for verification.

Gotchas and Tips

• IDE-Only Runtime: These attributes have zero runtime impact — PHP ignores them unless a tool like Psalm/PHPStan with a dedicated plugin (e.g., phpstan-phpstorm) interprets them. Safe to commit without conditional checks.
• PHP Version Gotchas: For PHP ≤7.4, attributes like #[ArrayShape([...])] must be written on a single line (no newlines in the attribute). Prefer multiline formatting only when targeting PHP ≥8.0.
• Null Handling: In ArrayShape, optional keys require explicit nullable types: 'user' => '?App\Models\User' or 'count' => '?int'. PhpStorm uses this for null-safety diagnostics.
• Name Resolution: When referencing classes in valuesFromClass, ObjectShape, or ArrayShape, always use fully qualified names or use statements — PhpStorm resolves attributes statically and may misinfer unqualified names.
• Tooling Integration: Enable the phpstan-phpstorm extension in PHPStan to surface these attributes in CI/CD pipelines — ensures #[Immutable] and #[Pure] contracts are enforced beyond the IDE.
• Avoid Over-Annotation: Only annotate public-facing APIs, critical data flows, and shared DTOs. Bombarding internal methods with attributes harms readability and offers diminishing returns. Focus on areas where IDE hints reduce bugs (e.g., complex array transformations or legacy code interactions).