Deprecation Contracts Laravel Package

Getting Started

Install the package with composer require symfony/deprecation-contracts. Then, anywhere in your codebase where you’re deprecating functionality (e.g., a controller action, service method, or helper), call trigger_deprecation() with at least three arguments: the package name, the version when deprecation was introduced, and a descriptive message. For example:

trigger_deprecation('my/package', '4.0', 'The "%s" helper is deprecated. Use "%s" instead.', 'legacyHelper()', 'NewHelper::process()');

To see these deprecations, ensure your app uses Symfony’s ErrorHandler (e.g., via Symfony\Component\ErrorHandler\ErrorRenderer\PhpErrorRenderer) or a compatible custom error handler—otherwise, notices are silently suppressed.

Implementation Patterns

• Gradual API Evolution: When replacing an old method with a new one, call trigger_deprecation() first in the legacy method, before executing its logic, to warn callers before they proceed.
• Trait-Based Centralization: Create a DeprecationTrait with helper methods like warnDeprecation($old, $new) to reduce duplication across multiple classes.
• CI/CD Integration: Run a CLI test that triggers deprecated paths (e.g., API integration tests), configure an error handler to collect deprecations, and fail builds if thresholds (e.g., >5 new deprecations) are exceeded—ensuring clean upgrades.
• Environment-Based Verbosity: In development, enable display of deprecation notices by setting ErrorHandler::enable() early; in production, route them to a dedicated log channel (e.g., deprecations.log) for monitoring usage volume and patterns.

Gotchas and Tips

• ⚠️ Silent in default PHP envs: Without an error handler that intercepts E_USER_DEPRECATED, trigger_deprecation() does nothing visible—even if code paths are hit. Always verify via test or log output.
• ⚠️ Version string precision matters: Using vague versions like 'next' or ' upcoming' breaks downstream semantic-versioning expectations—use exact release versions (e.g., '4.2.0').
• 🛠️ Override carefully: Declaring function trigger_deprecation() {} anywhere (even in a test bootstrap) globally silences all deprecations from this package. Avoid in shared utilities or libraries.
• 🔍 Debugging trick: Temporarily monkey-patch during development:

  if (!function_exists('trigger_deprecation')) {
      function trigger_deprecation(string $package, string $version, string $message, ...$args): void {
          $msg = sprintf('Since ' . $package . ' ' . $version . ': ' . $message, ...$args);
          trigger_error($msg, E_USER_DEPRECATED);
      }
  }
  

• 📦 Zero runtime cost in production: The function is conditionally compiled (via function_exists() guard) and often no-op when unconditionally overridden—so no measurable performance impact even in hot paths.