Consistency Patterns Knowledge

Consistency Patterns Knowledge Base

Quick reference for consistency guarantees, locking strategies, idempotency, and conflict resolution in distributed PHP applications.

Strong vs Eventual Consistency

┌─────────────────────────────────────────────────────────────────────────────┐
│                     CONSISTENCY DECISION TREE                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│                   Is data safety-critical?                                    │
│                      (money, inventory)                                       │
│                        /          \                                           │
│                      YES           NO                                         │
│                      /              \                                         │
│              Single write      Can tolerate                                   │
│              location?         stale reads?                                   │
│               /      \           /       \                                    │
│             YES      NO        YES       NO                                  │
│              |        |         |          |                                  │
│              ▼        ▼         ▼          ▼                                  │
│          ┌───────┐ ┌────────┐ ┌────────┐ ┌──────────┐                        │
│          │Strong │ │Saga +  │ │Eventual│ │Lineariz- │                        │
│          │(ACID) │ │Compen- │ │Consist.│ │able      │                        │
│          │       │ │sation  │ │+ TTL   │ │Reads     │                        │
│          └───────┘ └────────┘ └────────┘ └──────────┘                        │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Idempotency Keys

Overview

Idempotency ensures that performing the same operation multiple times produces the same result. Critical for payment processing, message handling, and API retries.

Delivery Guarantees

Idempotency Middleware (PSR-15)

<?php

declare(strict_types=1);

namespace Infrastructure\Http\Middleware;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

final readonly class IdempotencyMiddleware implements MiddlewareInterface
{
    private const string HEADER = 'Idempotency-Key';

    public function __construct(
        private \Redis $redis,
        private int $ttlSeconds = 86400,
    ) {}

    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler,
    ): ResponseInterface {
        if ($request->getMethod() === 'GET') {
            return $handler->handle($request);
        }

        $key = $request->getHeaderLine(self::HEADER);
        if ($key === '') {
            return $handler->handle($request);
        }

        $cacheKey = sprintf('idempotency:%s', $key);
        $cached = $this->redis->get($cacheKey);

        if ($cached !== false) {
            return unserialize($cached, ['allowed_classes' => true]);
        }

        $response = $handler->handle($request);

        $this->redis->setex($cacheKey, $this->ttlSeconds, serialize($response));

        return $response;
    }
}

Optimistic Locking

Assumes conflicts are rare. Reads a version, performs work, writes only if version unchanged.

Doctrine Versioned Entity

<?php

declare(strict_types=1);

namespace Domain\Model;

use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ORM\Table(name: 'products')]
final class Product
{
    #[ORM\Id]
    #[ORM\Column(type: 'string', length: 36)]
    private string $id;

    #[ORM\Column(type: 'string', length: 255)]
    private string $name;

    #[ORM\Column(type: 'integer')]
    private int $stock;

    #[ORM\Version]
    #[ORM\Column(type: 'integer')]
    private int $version = 1;

    public function __construct(string $id, string $name, int $stock)
    {
        $this->id = $id;
        $this->name = $name;
        $this->stock = $stock;
    }

    public function decrementStock(int $quantity): void
    {
        if ($this->stock < $quantity) {
            throw new InsufficientStockException($this->id, $this->stock, $quantity);
        }

        $this->stock -= $quantity;
    }

    public function getVersion(): int
    {
        return $this->version;
    }
}

Handling Optimistic Lock Failures

<?php

declare(strict_types=1);

namespace Application\UseCase;

use Doctrine\ORM\OptimisticLockException;

final readonly class DecrementStockUseCase
{
    public function __construct(
        private ProductRepositoryInterface $repository,
        private int $maxRetries = 3,
    ) {}

    public function execute(string $productId, int $quantity): void
    {
        $attempt = 0;

        while ($attempt < $this->maxRetries) {
            try {
                $product = $this->repository->findById($productId);
                $product->decrementStock($quantity);
                $this->repository->save($product);

                return;
            } catch (OptimisticLockException) {
                $attempt++;
                if ($attempt >= $this->maxRetries) {
                    throw new ConcurrencyConflictException($productId);
                }
                usleep(random_int(10_000, 50_000));
            }
        }
    }
}

Pessimistic Locking

Assumes conflicts are likely. Acquires a lock before reading, blocks other transactions.

Deadlock Prevention Rules

1. Always acquire locks in consistent order (e.g., by entity ID ascending)
2. Use lock timeouts (SET innodb_lock_wait_timeout = 5)
3. Keep transactions short (< 1 second)
4. Avoid user interaction within transactions

Conflict Resolution Strategies

CRDT Basics

Saga Compensation vs Distributed Transactions

Redis Atomic Operations

<?php

declare(strict_types=1);

namespace Infrastructure\Lock;

final readonly class RedisAtomicOperations
{
    public function __construct(
        private \Redis $redis,
    ) {}

    public function acquireLock(string $resource, string $token, int $ttlMs): bool
    {
        return $this->redis->set(
            sprintf('lock:%s', $resource),
            $token,
            ['NX', 'PX' => $ttlMs],
        ) === true;
    }

    public function releaseLock(string $resource, string $token): bool
    {
        $script = <<<'LUA'
            if redis.call("get", KEYS[1]) == ARGV[1] then
                return redis.call("del", KEYS[1])
            else
                return 0
            end
        LUA;

        return $this->redis->eval(
            $script,
            [sprintf('lock:%s', $resource), $token],
            1,
        ) === 1;
    }

    public function compareAndSwap(string $key, string $expected, string $newValue, int $ttl): bool
    {
        $script = <<<'LUA'
            if redis.call("get", KEYS[1]) == ARGV[1] then
                return redis.call("setex", KEYS[1], ARGV[3], ARGV[2])
            else
                return 0
            end
        LUA;

        return $this->redis->eval(
            $script,
            [$key, $expected, $newValue, (string) $ttl],
            1,
        ) !== 0;
    }
}

Common Violations Quick Reference

Detection Patterns

# Optimistic locking
Grep: "@Version|ORM\\\\Version|version" --glob "**/Entity/**/*.php"
Grep: "OptimisticLockException|StaleObjectStateException" --glob "**/*.php"
Grep: "LOCK_OPTIMISTIC|LockMode::OPTIMISTIC" --glob "**/*.php"

# Pessimistic locking
Grep: "FOR UPDATE|FOR SHARE|LOCK_PESSIMISTIC" --glob "**/*.php"
Grep: "LockMode::PESSIMISTIC|SKIP LOCKED|NOWAIT" --glob "**/*.php"

# Idempotency patterns
Grep: "Idempotency|idempotency.key|IdempotencyKey" --glob "**/*.php"
Grep: "deduplication|dedup|duplicate.check" --glob "**/*.php"

# Distributed locks
Grep: "SETNX|NX.*PX|redis.*lock|Lock::acquire" --glob "**/*.php"
Grep: "Redlock|RedisLock|LockFactory" --glob "**/*.php"

# Saga patterns
Grep: "compensat|SagaStep|SagaOrchestrator" --glob "**/*.php"
Grep: "CompensatingAction|rollback|undo" --glob "**/Saga/**/*.php"

# Consistency indicators
Grep: "EventualConsistency|ReadModel|Projection" --glob "**/*.php"
Grep: "transaction|beginTransaction|commit|rollback" --glob "**/*.php"

References

For detailed information, load these reference files:

• references/locking-patterns.md — Optimistic locking, pessimistic locking, distributed locks, Redlock algorithm, Symfony Lock component
• references/idempotency-patterns.md — Idempotency key generation, deduplication store, PSR-15 middleware, delivery guarantees, non-idempotent operations