Laravel Deadlock: Manage Technical Debt with Expiring Code Markers

Every developer has written code they intended to be temporary—a quick workaround before a demo, a feature flag for a gradual rollout, or a placeholder while waiting for a vendor fix. The problem? TODO comments get buried, tickets get forgotten, and "temporary" code becomes permanent.

Laravel Deadlock, a package by Med Mahmoud Hdaya, addresses this by letting you mark temporary workarounds with explicit expiration dates using PHP attributes. When a deadline passes, the package enforces accountability through runtime exceptions in development and build failures in CI/CD pipelines.

#How It Works

#Marking Code for Review

Add the #[Workaround] attribute to any class or method you intend to revisit. Include a description explaining why the code is temporary and set an expiration date.

For example, marking a controller method during an API migration:

use Zidbih\Deadlock\Attributes\Workaround;
 
class PaymentController extends Controller
{
    #[Workaround(
        description: 'Using old Stripe API v2 until upgrade to v3 is complete',
        expires: '2026-01-05'
    )]
    public function processPayment(Request $request)
    {
        // Temporary workaround using legacy API
        return $this->legacyStripeService->charge($request->amount);
    }
}

You can also mark entire classes, useful for feature flags or deprecated code paths:

use Zidbih\Deadlock\Attributes\Workaround;
 
#[Workaround(
    description: 'Remove legacy dashboard after all users migrated',
    expires: '2026-02-15'
)]
class LegacyDashboardController extends Controller
{
    // Old dashboard implementation to be removed
}

#Listing Workaround Code

Run php artisan deadlock:list to audit all temporary code in your project:

+---------+------------+-------------------------------------+---------------------------------------------------+
| Status  | Expires    | Location                            | Description                                       |
+---------+------------+-------------------------------------+---------------------------------------------------+
| EXPIRED | 2026-01-05 | PaymentController::processPayment   | Using old Stripe API v2 until upgrade to v3       |
| OK      | 2026-02-15 | LegacyDashboardController           | Remove legacy dashboard after all users migrated  |
| OK      | 2026-01-20 | CacheAdapter::get                   | Temporary Redis workaround until cache driver fix |
+---------+------------+-------------------------------------+---------------------------------------------------+

This command helps teams systematically track technical debt. During sprint planning or code review, you have a clear view of what needs attention.

#Enforcing Deadlines

Laravel Deadlock distinguishes between development and production environments. In local development, executing code with an expired deadline throws an exception, blocking further progress until you either extend the deadline or fix the underlying issue. In production, runtime enforcement is disabled to ensure users never experience interruptions.

For automated enforcement in CI/CD, integrate the check command into your pipeline:

# .github/workflows/tests.yml
name: Tests
 
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
 
jobs:
  test:
 
    runs-on: ubuntu-latest
 
    steps:
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
 
      - name: Checkout Code
        uses: actions/checkout@v4.1.7
 
      - name: Install dependencies
        run: composer install
 
      - name: Check for expired deadlocks
        run: php artisan deadlock:check
 
      - name: Run tests
        run: php artisan test

If any workaround code has expired, the build fails with exit code 1, preventing deployment until the team addresses the technical debt.

The output would look something like:

Expired workarounds detected:
 
- Remove legacy dashboard after all users migrated | expires: 2026-02-15 | LegacyDashboardController
- Temporary Redis workaround until cache driver fix | expires: 2026-01-20 | CacheAdapter::get

#Runtime Enforcement for Services

Controllers are automatically checked for expired workarounds, but services and other classes need explicit enforcement. Use DeadlockGuard::check() to trigger expiration checks when the class is instantiated:

use Zidbih\Deadlock\Attributes\Workaround;
use Zidbih\Deadlock\Support\DeadlockGuard;
 
#[Workaround(description: 'Temporary legacy pricing logic', expires: '2026-02-01')]
final class PricingService
{
    public function __construct()
    {
        DeadlockGuard::check($this);
    }
}

For method-level enforcement, pass the method name as a second argument: DeadlockGuard::check($this, __FUNCTION__).

#Practical Use Cases

Laravel Deadlock works well for several common scenarios:

• Feature flag removal: Mark feature flags with deadlines tied to rollout completion dates
• API migration paths: Track temporary adapters or compatibility layers during vendor upgrades
• Deprecated functionality: Set deadlines for removing old code after user migrations complete
• Post-launch cleanup: Mark quick fixes made during production incidents with follow-up dates
• Time-boxed experiments: Give experimental features explicit expiration dates for evaluation periods

Install Laravel Deadlock via Composer:

composer require zidbih/laravel-deadlock

The package requires PHP 8.2 or higher and is compatible with Laravel 10, 11, and 12. Check out the GitHub repository for full documentation and to view the source code.