Deprecations Laravel Package

Getting Started

Start by requiring the package via Composer:

composer require doctrine/deprecations

Then, in your application (e.g., public/index.php or bootstrap/app.php), configure how deprecations should be handled — typically by forwarding them to a PSR-3 logger:

\Doctrine\Deprecations\Deprecation::enableWithPsrLogger($yourLogger);

For initial debugging, you may instead use enableWithTriggerError() to surface deprecations as native E_USER_DEPRECATED warnings.
The first use case is usually detecting deprecations in your app that originate from dependencies (e.g., Doctrine ORM): after enabling logging, check your logs for entries like Deprecation: doctrine/orm: some method is deprecated....

Implementation Patterns

• In libraries/packages: Use Deprecation::triggerIfCalledFromOutside() when deprecating internal APIs — this ensures only consumers of your library see the deprecation, not your own internal usage. Call trigger() only when you want to force a deprecation (e.g., during internal refactors where self-calls should also warn).
• In applications: Centralize deprecation setup (e.g., in config/deprecations.php or service provider), and prefer PSR-3 logging over trigger_error for observability-friendly stacks (Symfony, Laravel).
• In tests: Use the VerifyDeprecations trait to assert specific deprecations are emitted or not emitted — essential for tracking breaking changes ahead of upgrades.
• Bulk suppression: Use ignorePackage('vendor/package') or ignoreDeprecations('https://...') in test bootstraps to silence known, non-critical deprecations while retaining visibility into new ones.
• Environment-driven behavior: Leverage DOCTRINE_DEPRECATIONS env vars (track, trigger, disabled) for environment-specific handling (e.g., track in CI for telemetry, trigger in dev for visibility).

Gotchas and Tips

• Do NOT call enableWith*() methods in libraries — this violates separation of concerns; only applications should decide how deprecations are handled.
• Deduplication is on by default: Each deprecation identifier triggers once per request — disable with withoutDeduplication() if you need frequency analysis (e.g., in test suites or debug middleware).
• Suppression via @ is ignored: In PHPUnit, use ignoreSuppressionOfDeprecations="true" in <source> or #[IgnoreDeprecations] attribute to avoid accidental masking.
• Stack traces are shallow but sufficient: Each deprecation includes one caller frame — enough to locate the offending line, but not full stacks.
• Identifiers must be unique & stable: Use GitHub issue/PR URLs (e.g., https://github.com/doctrine/orm/issues/1234) — they’re machine-parseable and provide context.
• triggerIfCalledFromOutside() can misfire if called from eval’d/anonymous code: Since it inspects the call stack, obfuscated or auto-generated code may incorrectly appear as “inside” your package.
• Tracking is always on: Even with deprecation handling disabled (disable() or DOCTRINE_DEPRECATIONS=disabled), getTriggeredDeprecations() remains usable for introspection.