Phpstan Deprecation Rules Laravel Package

Getting Started

Install the package via Composer as a development dependency:

composer require --dev phpstan/phpstan-deprecation-rules

If you use phpstan/extension-installer, the rules are auto-configured. Otherwise, manually include vendor/phpstan/phpstan-deprecation-rules/rules.neon in your PHPStan config (phpstan.neon). Run vendor/bin/phpstan analyse — the extension will now catch all usages of deprecated classes, methods, properties, constants, and traits annotated with @deprecated.

Implementation Patterns

• Detect deprecations in third-party packages: Use PHPStan stub files to annotate @deprecated on external classes/methods (e.g., in stubs/). Place stubs in your repo and reference them via parameters.stubsDir in config.
• Suppress false positives in legacy code: Wrap test code for deprecated APIs in @group legacy and implement a custom DeprecatedScopeResolver to exclude those scopes from warnings.
• Custom deprecation markers: Define your own attributes (e.g., #[Deprecated(reason: '…')]) and implement a DeprecationRuleExtension to register custom deprecation detection.
• Daily workflow: Run PHPStan in CI before merges to catch accidental use of deprecated symbols. Integrate deprecation warnings into your PR checks to enforce proactive migration.

Gotchas and Tips

• Deprecation warnings are not reported in deprecated scopes (e.g., methods/functions marked @deprecated) — this prevents noise when maintaining legacy code.
• Since v2.0+, several legacy rules were consolidated under *Restricted*Extension classes (e.g., RestrictedMethodUsageExtension), meaning method, property, and constant deprecations now share logic — ensure you’re using the latest version to benefit from fixes.
• PHP version awareness: Deprecation reporting for constants respects Scope->getPhpVersion() — align your phpVersion setting in phpstan.neon with your target environment.
• Avoid hard-to-debug false negatives: Stub files must be loaded before analysis — verify stubsDir is set and stubs include all relevant symbols (missing annotations won’t be caught).
• Extensibility: The DeprecatedScopeResolver interface is your main extension point for custom logic — combine it with @group annotations, custom docblocks, or symfony/contracts-style #[Deprecated] to scale adoption.