php 75 lines · 9 steps

How a circuit breaker guards a flaky service

A cache-backed circuit breaker that stops calling a failing dependency once errors pile up, then lets it recover.

Explained by highlit

Intermediate circuit-breaker resilience caching state-machine fault-tolerance

1<?php
2 
3namespace App\Resilience;
4 
5use Psr\SimpleCache\CacheInterface;
6use RuntimeException;
7 
8final class CircuitBreaker
9{
  private const CLOSED = 'closed';
  private const OPEN = 'open';
  private const HALF_OPEN = 'half_open';
13 
  public function __construct(
      private readonly CacheInterface $cache,
      private readonly string $service,
      private readonly int $failureThreshold = 5,
      private readonly int $openDuration = 30,
  ) {
  }
21 
  public function call(callable $operation): mixed
  {
      $state = $this->state();
25 
      if ($state === self::OPEN) {
          throw new CircuitOpenException("Circuit for '{$this->service}' is open");
      }
29 
      try {
          $result = $operation();
          $this->onSuccess();
          return $result;
      } catch (RuntimeException $e) {
          $this->onFailure();
          throw $e;
      }
  }
39 
  private function state(): string
  {
      $openedAt = $this->cache->get($this->key('opened_at'));
43 
      if ($openedAt === null) {
          return self::CLOSED;
      }
47 
      if (time() - $openedAt >= $this->openDuration) {
          return self::HALF_OPEN;
      }
51 
      return self::OPEN;
  }
54 
  private function onSuccess(): void
  {
      $this->cache->delete($this->key('failures'));
      $this->cache->delete($this->key('opened_at'));
  }
60 
  private function onFailure(): void
  {
      $failures = (int) $this->cache->get($this->key('failures'), 0) + 1;
      $this->cache->set($this->key('failures'), $failures, $this->openDuration * 2);
65 
      if ($failures >= $this->failureThreshold) {
          $this->cache->set($this->key('opened_at'), time(), $this->openDuration);
      }
  }
70 
  private function key(string $suffix): string
  {
      return "circuit_breaker:{$this->service}:{$suffix}";
  }
75}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1A circuit breaker fails fast once a dependency looks unhealthy, sparing callers from repeated slow errors.
2Storing state in a shared cache with TTLs lets the breaker expire and self-heal without a background job.
3Modeling three states — closed, open, half-open — gives you a controlled path back to normal operation.

Related explainers

ruby

class Order
  class InvalidTransition < StandardError; end
 
  TRANSITIONS = {

A state machine for order transitions in Ruby

state-machine data-driven error-handling

Intermediate 8 steps

php

<?php
 
namespace App\Http\Controllers;

Streaming a filtered CSV export in Laravel

streaming csv-export query-builder

Intermediate 9 steps

python

import time
import threading
from enum import Enum
from functools import wraps

Building a circuit breaker in Python

circuit-breaker resilience decorators

Advanced 7 steps

php

<?php
 
namespace App\Http\Middleware;

Idempotent requests with Laravel middleware

idempotency middleware caching

Advanced 8 steps

python

from django.contrib.postgres.search import SearchQuery, SearchRank, SearchVector
from django.core.cache import cache
from django.db.models import F
from django.http import JsonResponse