Deprecation Contracts Laravel Package

Getting Started

1. Installation: Add the package via Composer:

   composer require symfony/deprecation-contracts
   

2. First Use Case: Trigger a deprecation in a legacy method (e.g., a controller or service) to notify users of upcoming changes:

   // app/Services/OldService.php
   public function legacyMethod()
   {
       trigger_deprecation('my/package', '1.0.0', 'Method "%s" is deprecated. Use "%s" instead.', 'legacyMethod()', 'newMethod()');
       // ... existing logic
   }
   

3. Visibility Setup: Ensure Laravel’s Symfony ErrorHandler is configured to capture E_USER_DEPRECATED notices. Add to bootstrap/app.php:

   use Symfony\Component\ErrorHandler\ErrorHandler;
   ErrorHandler::register();
   

4. Test Locally: Run a test that invokes deprecated paths and verify notices appear in logs or error output.

Implementation Patterns

1. Deprecation Workflow in Laravel

• Pre-Execution Warnings: Call trigger_deprecation() at the start of deprecated methods to alert callers before logic executes:

  public function oldAuthenticate(Request $request)
  {
      trigger_deprecation('laravel/framework', '10.0', 'Use "%s" instead.', 'auth:old');
      return $this->newAuthenticate($request);
  }
  

• Facade/Helper Integration: Wrap trigger_deprecation() in a reusable trait or helper:

  // app/Traits/DeprecationHelper.php
  trait DeprecationHelper
  {
      protected function deprecate(string $package, string $version, string $old, string $new): void
      {
          trigger_deprecation($package, $version, 'Using "%s" is deprecated. Use "%s".', $old, $new);
      }
  }
  

  Usage:

  class OldController
  {
      use DeprecationHelper;
  
      public function index()
      {
          $this->deprecate('my/package', '2.0', 'OldController', 'NewController');
          // ...
      }
  }
  

2. CI/CD Enforcement

• Deprecation Gatekeeper: Add a PHPUnit test to fail builds if new deprecations are introduced:

  // tests/DeprecationTest.php
  public function test_no_new_deprecations()
  {
      $this->expectDeprecationCount(0); // Fail if any deprecations triggered
      $this->get('/legacy-route');
  }
  

  Use symfony/error-handler to track counts during tests.

3. Environment-Specific Handling

• Development: Display notices directly via ErrorHandler::enable().
• Production: Route to a dedicated log channel (e.g., deprecations.log) by extending Laravel’s logging:

  // config/logging.php
  'channels' => [
      'deprecations' => [
          'driver' => 'single',
          'path' => storage_path('logs/deprecations.log'),
          'level' => 'debug',
      ],
  ],
  

  Configure the error handler to log E_USER_DEPRECATED to this channel.

4. Monorepo Coordination

• Centralized Deprecation Registry: Maintain a DEPRECATIONS.md file listing all active deprecations, with links to their first occurrence in code. Update this file via a script that parses trigger_deprecation() calls.

Gotchas and Tips

Pitfalls

• Silent Failures: Without ErrorHandler::register(), deprecations vanish. Always test with:

  php artisan tinker --env=local
  trigger_deprecation('test', '1.0', 'Test notice');
  

  (Should output a deprecation notice.)
• Version String Mismatches: Use exact version strings (e.g., '1.2.3', not 'v1.2' or 'upcoming'). Downstream tools (e.g., dependency updaters) rely on semantic versions.
• Global Overrides: Declaring trigger_deprecation() anywhere (even in tests) disables all deprecations. Avoid in shared autoloaded files.
• Nested Deprecations: Chaining trigger_deprecation() calls in the same method may flood logs. Group related deprecations into a single call with a composite message.

Debugging

• Temporary Override: Force notices during development by replacing the function:

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

• Log Filtering: Use Laravel’s log channels to filter deprecations:

  // app/Providers/AppServiceProvider.php
  public function boot()
  {
      \Log::listen(function ($level, $message, array $context) {
          if (str_contains($message, 'DEPRECATION')) {
              \Log::channel('deprecations')->info($message, $context);
          }
      });
  }
  

Advanced Tips

• Deprecation Metadata: Extend the function to include removal dates or migration guides:

  trigger_deprecation(
      'my/package', '1.0',
      'Method "%s" will be removed in v2.0. See docs: %s',
      'oldMethod()', 'https://example.com/migration-guide'
  );
  

• Laravel-Specific: Integrate with Laravel’s Illuminate\Support\Facades\DeprecatesFunctions (if available) to auto-generate deprecation stubs during upgrades.
• Performance: The function is zero-cost in production when unconditionally overridden (common in optimized builds). Verify with:

  php -d opcache.enable=0 -n -r 'trigger_deprecation("test", "1.0", "test");'