Retries and Circuit Breakers Belong in the Adapter, Not Your Use Case

#php #architecture #hexagonal #resilience

Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You open a use case that places an order. It loads a customer, builds the order, charges a payment gateway, saves, publishes an event. Clean. Then a sprint ago someone added a retry loop around the charge call, because the gateway flaps under load. Now the use case has a for ($i = 0; $i < 3; $i++), a usleep(), and a comment that says // gateway is flaky on Mondays.

The business rule is buried under retry plumbing. A reader who wants to know what placing an order means has to skip past sleep timers and exception counters to find it. Worse, the next person who adds a second outbound call copies the loop. Soon every call to the network has its own hand-rolled retry, each with a slightly different backoff, none of them tested.

The use case learned about transient failure. It should never have.

Transient failure is not a business rule

A use case answers one question: what does the application do when this thing happens? Place an order. Cancel a subscription. Issue a refund. Those are decisions the business cares about.

"The payment gateway returned a 503 and we should try again in 200ms" is not a business decision. It is a property of the network between your process and theirs. The domain does not know the gateway is HTTP. It does not know there is a network at all. It asked a port to charge a customer, and the port either succeeds or raises a domain exception.

Here is the port, stated in domain language:

<?php

declare(strict_types=1);

namespace App\Application\Port;

use App\Domain\Customer\CustomerId;
use App\Domain\Shared\Money;

interface PaymentGateway
{
    public function charge(
        CustomerId $customerId,
        Money $amount,
        string $idempotencyKey,
    ): PaymentReceipt;
}

No Response, no status code, no int $retries. The use case calls charge and trusts it. If charging is impossible right now, the implementation raises PaymentGatewayUnavailable, a domain exception the use case can choose to handle. Whether the adapter tried once or five times before giving up is none of the use case's concern.

The decorator carries the resilience

The port has one interface and can have many implementations. The real one talks HTTP. A second one wraps the real one and adds retries. A third wraps that and adds a circuit breaker. Each is a PaymentGateway. The use case sees one type.

Start with the base adapter that translates HTTP errors into domain exceptions:

<?php

declare(strict_types=1);

namespace App\Infrastructure\Payment;

use App\Application\Port\PaymentGateway;
use App\Application\Port\PaymentReceipt;
use App\Domain\Customer\CustomerId;
use App\Domain\Shared\Money;
use GuzzleHttp\ClientInterface;
use GuzzleHttp\Exception\RequestException;

final readonly class HttpPaymentGateway implements PaymentGateway
{
    public function __construct(
        private ClientInterface $http,
        private string $endpoint,
    ) {}

    public function charge(
        CustomerId $customerId,
        Money $amount,
        string $idempotencyKey,
    ): PaymentReceipt {
        try {
            $response = $this->http->request('POST', $this->endpoint, [
                'headers' => ['Idempotency-Key' => $idempotencyKey],
                'json' => [
                    'customer_id' => $customerId->value,
                    'amount_minor' => $amount->amountInMinorUnits,
                    'currency' => $amount->currency,
                ],
                'timeout' => 5,
            ]);
        } catch (RequestException $e) {
            if ($e->getResponse()?->getStatusCode() === 402) {
                throw new PaymentDeclined($customerId, $amount);
            }
            throw new PaymentGatewayUnavailable(previous: $e);
        }

        $body = json_decode(
            (string) $response->getBody(),
            associative: true,
            flags: JSON_THROW_ON_ERROR,
        );
        return new PaymentReceipt($body['receipt_id'], $body['status']);
    }
}

PaymentDeclined is a business outcome — the card was refused. PaymentGatewayUnavailable is transient — the network or the remote service failed. The retry logic cares only about the second kind. A declined card should never be retried; retrying it just means asking the same question again.

Now the retrying decorator:

<?php

declare(strict_types=1);

namespace App\Infrastructure\Payment;

use App\Application\Port\Clock;
use App\Application\Port\PaymentGateway;
use App\Application\Port\PaymentReceipt;
use App\Domain\Customer\CustomerId;
use App\Domain\Shared\Money;

final readonly class RetryingPaymentGateway implements PaymentGateway
{
    public function __construct(
        private PaymentGateway $inner,
        private Sleeper $sleeper,
        private int $maxAttempts = 3,
        private int $baseDelayMs = 100,
    ) {}

    public function charge(
        CustomerId $customerId,
        Money $amount,
        string $idempotencyKey,
    ): PaymentReceipt {
        $attempt = 0;

        while (true) {
            $attempt++;
            try {
                return $this->inner->charge(
                    $customerId,
                    $amount,
                    $idempotencyKey,
                );
            } catch (PaymentGatewayUnavailable $e) {
                if ($attempt >= $this->maxAttempts) {
                    throw $e;
                }
                $this->sleeper->sleepMs(
                    $this->baseDelayMs * (2 ** ($attempt - 1)),
                );
            }
        }
    }
}

It catches only PaymentGatewayUnavailable. A PaymentDeclined flies straight through, untouched, because it is not transient. The backoff doubles each attempt. The same idempotencyKey goes out on every try, so a charge that actually landed before a timeout is not double-billed — the remote side dedupes on the key.

Sleeper is a tiny port (sleepMs(int): void) so a unit test can pass a fake that records delays instead of blocking the suite. Real sleeping is one line of usleep in the production implementation.

The circuit breaker stops the bleeding

Retries help when failure is brief. They hurt when the gateway is down hard: every request now waits through three timeouts before failing, and your worker pool fills with stalled calls. A circuit breaker fixes that. After enough failures it stops calling the gateway at all and fails fast, giving the remote service room to recover.

<?php

declare(strict_types=1);

namespace App\Infrastructure\Payment;

use App\Application\Port\PaymentGateway;
use App\Application\Port\PaymentReceipt;
use App\Domain\Customer\CustomerId;
use App\Domain\Shared\Money;

final readonly class CircuitBreakerPaymentGateway implements PaymentGateway
{
    public function __construct(
        private PaymentGateway $inner,
        private CircuitState $state,
    ) {}

    public function charge(
        CustomerId $customerId,
        Money $amount,
        string $idempotencyKey,
    ): PaymentReceipt {
        if ($this->state->isOpen()) {
            throw new PaymentGatewayUnavailable(
                message: 'circuit open',
            );
        }

        try {
            $receipt = $this->inner->charge(
                $customerId,
                $amount,
                $idempotencyKey,
            );
            $this->state->recordSuccess();
            return $receipt;
        } catch (PaymentGatewayUnavailable $e) {
            $this->state->recordFailure();
            throw $e;
        }
    }
}

CircuitState is a port too. The production version keeps the failure count and the open-until timestamp in Redis so all your workers share one view of the gateway's health. A fake keeps it in an array for tests. The decorator does not know or care which one it holds.

Note the breaker also raises PaymentGatewayUnavailable when it short-circuits. The use case sees the same domain exception whether the gateway timed out, retried out, or was fenced off by an open circuit. One failure type, handled in one place upstream.

Wiring it at the composition root

The stacking happens once, where you build the container. The use case asks for a PaymentGateway and receives the whole onion without knowing its layers.

$c->set(PaymentGateway::class, fn(C $c) =>
    new CircuitBreakerPaymentGateway(
        new RetryingPaymentGateway(
            new HttpPaymentGateway(
                $c->get(ClientInterface::class),
                $_ENV['PAYMENT_GATEWAY_URL'],
            ),
            $c->get(Sleeper::class),
        ),
        $c->get(CircuitState::class),
    ),
);

Read it inside out: HTTP at the core, retries around it, the breaker on the outside so it fences off the whole retrying stack when the gateway is unhealthy. Want retries without the breaker in a low-traffic service? Drop one constructor call. Want a different backoff for a different gateway? Pass different numbers. The use case file does not change. It never knew any of this existed.

What this buys you

The use case stays readable. Open PlaceOrder and you read the business sequence with nothing in the way. No loop, no sleep, no failure counting.

The resilience is testable in isolation. RetryingPaymentGateway has its own unit test that asserts it retries three times on PaymentGatewayUnavailable, gives up on the fourth, and never retries a PaymentDeclined. It uses a fake inner gateway and a fake sleeper. No network, no real timer.

public function test_retries_then_succeeds(): void
{
    $inner = new FlakyGateway(failTimes: 2);
    $sleeper = new RecordingSleeper();

    $gateway = new RetryingPaymentGateway($inner, $sleeper);
    $receipt = $gateway->charge(
        new CustomerId('c-1'),
        new Money(3000, 'EUR'),
        'key-1',
    );

    self::assertSame('ok', $receipt->status);
    self::assertSame(3, $inner->attempts());
    self::assertSame([100, 200], $sleeper->delays());
}

And the policy lives in one place. When ops asks for five attempts instead of three, or a longer breaker cooldown, you change a constant at the composition root or in one decorator. You do not grep the application layer for hand-rolled loops, because there are none. The use case asked a port to charge a customer. Everything about how hard to try is an infrastructure detail, and infrastructure details live in adapters.

The next time a retry loop shows up in a use case during review, ask what it is protecting against. If the answer is "the network," it is in the wrong file. Move it out, wrap the adapter, and let the use case go back to describing the business.

If this was useful

Decorating adapters with retries, breakers, timeouts, and caching, without leaking any of it into the domain, is one of the threads Decoupled PHP follows from the first port to a production-shaped service. The book builds the same vocabulary used here and pushes into the failure modes that show up once the happy path works: partial writes, poison messages, and the migration path for a framework-coupled codebase that needs this discipline most.