Deprecation Contracts Laravel Package

Getting Started

Install via Composer:

composer require symfony/deprecation-contracts

First Use Case: Deprecate a legacy method in a Laravel service:

// app/Services/OldUserService.php
public function getUserByLegacyId($id)
{
    trigger_deprecation('my/package', '1.0.0', 'Method "%s" is deprecated. Use "%s" instead.', __METHOD__, 'UserService::findById()');

    return User::where('legacy_id', $id)->first();
}

Verify Setup: Ensure Symfony’s ErrorHandler is configured (Laravel includes it by default). Test in development:

php artisan serve

Check browser console or logs for deprecation notices.

Implementation Patterns

1. Deprecation Workflow in Laravel

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

  public function oldAuthenticate(Request $request)
  {
      trigger_deprecation('my/app', '2.0', 'Use "%s" instead.', 'auth()->attempt()');
      return Auth::attempt($request->only('email', 'password'));
  }
  

• Controller/Route Deprecations: Use middleware to log deprecated routes:

  // app/Http/Middleware/DeprecationLogger.php
  public function handle($request, Closure $next)
  {
      if ($request->is('legacy/*')) {
          trigger_deprecation('my/app', '3.0', 'Route "%s" is deprecated.', $request->path());
      }
      return $next($request);
  }
  

2. Centralized Deprecation Management

• Trait for DRY Code:

  // app/Traits/DeprecationHelper.php
  trait DeprecationHelper
  {
      protected function warnDeprecation(string $oldMethod, string $newMethod): void
      {
          trigger_deprecation('my/app', '1.0.0', 'Method "%s" is deprecated. Use "%s".', $oldMethod, $newMethod);
      }
  }
  

  Usage:

  class OldService {
      use DeprecationHelper;
  
      public function deprecatedMethod() {
          $this->warnDeprecation(__METHOD__, 'NewService::replacement()');
          // ... legacy logic
      }
  }
  

3. CI/CD Enforcement

• Deprecation Budget Checks: Fail builds if new deprecations exceed a threshold (e.g., 3/month).

  // tests/DeprecationBudgetTest.php
  public function test_no_new_deprecations()
  {
      $this->withoutExceptionHandling();
      $this->get('/legacy-endpoint');
      $this->assertFalse(DeprecationTracker::hasNewDeprecations());
  }
  

  Use a custom DeprecationTracker class to aggregate notices.

4. Environment-Specific Handling

• Development: Display notices in logs/console:

  // bootstrap/app.php
  if (app()->environment('local')) {
      \Symfony\Component\ErrorHandler\ErrorHandler::register();
  }
  

• Production: Route to a dedicated log channel:

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

  Configure ErrorHandler to use this channel:

  \Symfony\Component\ErrorHandler\ErrorHandler::register(
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,
      null,