Quick Start

A typical workflow consists of three steps:

  1. Ensure the key is not currently locked.
  2. Record failures whenever the protected operation fails.
  3. Record a success to reset the backoff state.

Basic Example

use Kodefarmers\Cadence\Exceptions\CadenceLockedException;
use Kodefarmers\Cadence\Facades\Cadence;

$cadence = Cadence::driver();

$key = 'operation:resource-id';

try {
    $cadence->ensureNotLocked($key);

    // Perform the protected operation...

    if ($operationFailed) {
        $result = $cadence->recordFailure($key);

        return [
            'success' => false,
            'locked' => $result->isLocked,
            'retry_after' => $result->delay,
        ];
    }

    $cadence->recordSuccess($key);

    return [
        'success' => true,
    ];
} catch (CadenceLockedException $exception) {
    return [
        'success' => false,
        'message' => 'Operation is temporarily locked.',
        'retry_after' => $exception->retryAfter(),
    ];
}

By default, the first three failures are allowed without any delay. The fourth failure becomes the first backoff violation and applies the configured delay.

Using Different Backoff Strategies

The driver() method accepts the name of the backoff strategy to use.

$cadence = Cadence::driver('fibonacci');

See the Available Backoff Strategies section for the list of built-in drivers and their behavior.

Next Steps