Download the PHP package zidbih/laravel-deadlock without Composer

Laravel Deadlock helps you track temporary workarounds before they turn into permanent debt.

Annotate classes or methods with an expiration date, then enforce those deadlines in local development and CI without affecting production.

What It Does

• Scans the codebase for #[Workaround] attributes
• Lists workarounds and their status
• Fails CI when a workaround has expired
• Blocks local execution of expired code
• Never enforces in production

Installation

Compatibility

• Laravel 10, 11, 12 with PHP 8.2+
• Laravel 13 with PHP 8.3+

Quick Start

Add #[Workaround] to a class or method with a clear description and expiration date.

#[Workaround] supports classes and methods. Other scopes are ignored.

When It Expires

• Local Development: Execution is blocked with an exception
• CI/CD: Pipelines fail when running the check command
• Production: No effect

Runtime Enforcement

Automatic Enforcement for Controllers

Controllers are discovered automatically and enforced at runtime.
Add the attribute; no additional calls are required.

Explicit Enforcement for Services, Jobs, and Commands

For non-controller classes, enforcement is explicit by design to avoid hidden runtime behavior.

Class-Level

Method-Level

Artisan Commands

deadlock:list

List all detected workarounds and their current status.

Example output:

Filters

• Show only expired workarounds:

• Show only active workarounds:

• Show workarounds expiring in 7 days or less:

Summary

The command includes a summary line by default so totals are visible at a glance.

deadlock:check

Fail CI when one or more workarounds have expired.

If an expired workaround is found, the command exits with code 1.

To fail before a workaround expires, use --fail-within:

This fails when a workaround is already expired or expires within the next 7 days.

To also fail when invalid workaround usage is detected, use strict mode:

Strict mode reuses the doctor checks and is useful in CI when you want unsupported targets, invalid attributes, or missing DeadlockGuard::check(...) calls to fail the pipeline.

For machine-readable output, use JSON mode:

Example JSON output:

Example failure output:

deadlock:doctor

Diagnose workaround usage that may look valid but will not behave as expected.

The doctor command reports unsupported #[Workaround] targets, invalid attribute arguments, and missing or incorrect DeadlockGuard::check(...) calls for explicit runtime enforcement.

Example output:

deadlock:extend

Update the expires date of an existing #[Workaround] attribute in your source code.

It supports three target modes:

• Extend the workaround on a class
• Extend the workaround on one method
• Extend every workaround declared on a class

Targeting

Use exactly one of these target options:

• --class=App\Services\PricingService
• --controller=TestController

--controller is a shortcut for classes under App\Http\Controllers.

Examples:

How Targeting Works

--class only:

• Targets the class-level #[Workaround] on that class

--class or --controller with --method=...:

• Targets only the workaround on that method

--class or --controller with --all:

• Targets the class-level workaround
• Targets every method-level workaround declared on that class

Date Options

You must provide either:

• --days=N
• --months=N
• --date=YYYY-MM-DD

You may combine --days and --months in the same command.

--date is absolute and replaces the current expiry date directly.

--date cannot be combined with --days or --months.

Examples

Extend a class-level workaround:

Extend a method-level workaround:

Extend every workaround on a class:

Extend a controller workaround:

Extend a nested controller method workaround:

Validation

• Use exactly one of --class or --controller
• --method and --all cannot be used together
• Without --method or --all, the command updates only the class-level workaround
• --days and --months must be positive integers
• --date must use YYYY-MM-DD
• The target class must resolve to a real PHP file
• The targeted class or method must already have a #[Workaround]

CI/CD Integration

Run the check command in your pipeline:

CI example:

Runtime Exceptions

When expired code is accessed locally, a WorkaroundExpiredException is thrown with:

• Description
• Expiration date
• Exact code location

Example exception output:

Production Safety

Laravel Deadlock never enforces workaround deadlines in production.

• Runtime exceptions only occur in local environments
• CI blocks merges before debt reaches production
• Live users are never affected

Contributing

See CONTRIBUTING.md

License

MIT