🛡️ R4PHP — Resilience4u for PHP

R4PHP é a biblioteca da família Resilience4u para o ecossistema PHP — um conjunto de políticas de resiliência (Retry, Circuit Breaker, Bulkhead, Time Limiter, Rate Limiter) inspiradas no Resilience4j.

---

🚀 Visão geral

O R4PHP fornece uma API simples e extensível para aplicar políticas de resiliência a qualquer operação crítica do seu sistema — chamadas HTTP, queries, integrações externas, filas, etc.

Com ele, você pode:

• Controlar quantas execuções simultâneas são permitidas (Bulkhead)
• Repetir operações com falha (Retry)
• Interromper fluxos quando uma dependência externa estiver instável (Circuit Breaker)
• Limitar o tempo máximo de execução (Time Limiter)
• Restringir taxa de requisições (Rate Limiter)
• Compor todas as políticas em cadeia, aplicadas de forma declarativa via Factory::fromConfig()

---

📦 Instalação

composer require resilience4u/r4php

---

🧩 Políticas disponíveis

Policy	Classe	Descrição	Dependência
RetryPolicy	Resiliente\R4PHP\Policies\RetryPolicy	Repete operações com backoff exponencial ou constante	sts/backoff
CircuitBreakerPolicy	Resiliente\R4PHP\Policies\CircuitBreakerPolicy	Abre/fecha circuitos com thresholds configuráveis	ackintosh/ganesha
BulkheadPolicy	Resiliente\R4PHP\Policies\BulkheadPolicy	Limita execuções simultâneas	nativo
RateLimiterPolicy	Resiliente\R4PHP\Policies\RateLimiterPolicy	Controla taxa de requisições por segundo	symfony/rate-limiter
TimeLimiterPolicy	Resiliente\R4PHP\Policies\TimeLimiterPolicy	Interrompe operações que excedem o tempo máximo	nativo

---

⚙️ Uso básico

use Resiliente\R4PHP\Contracts\Executable;
use Resiliente\R4PHP\Core\Config;
use Resiliente\R4PHP\Core\Factory;

require __DIR__ . '/../vendor/autoload.php';

// Define as políticas
$cfg = Config::fromArray([
    'rateLimiter' => ['tokensPerSecond' => 20, 'limit' => 40],
    'bulkhead'    => ['maxConcurrent' => 32],
    'timeLimiter' => ['timeoutMs' => 1500],
    'retry'       => [
        'maxAttempts' => 5,
        'initialMs'   => 200,
        'maxMs'       => 3000,
        'multiplier'  => 2.0,
        'jitter'      => true
    ],
    'circuitBreaker' => [
        'name' => 'core',
        'failureRatePct' => 50,
        'minSamples' => 10,
        'openMs' => 30000,
        'timeWindowSec' => 10,
    ],
]);

$policy = Factory::fromConfig($cfg);

// Executa uma operação resiliente
$result = $policy->execute(new class implements Executable {
    public function __invoke(): mixed {
        if (random_int(0, 1)) {
            throw new \RuntimeException('falhou');
        }
        return "ok";
    }
});

echo $result, PHP_EOL;

---

🌐 Integração com Guzzle

O R4PHP inclui middleware pronto para o Guzzle HTTP Client:

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use Resiliente\R4PHP\Core\Factory;
use Resiliente\R4PHP\Core\Config;
use Resiliente\R4PHP\Integrations\Guzzle\R4Middleware;

require __DIR__ . '/../vendor/autoload.php';

$policy = Factory::fromConfig(Config::fromArray([
    'retry' => ['maxAttempts' => 3, 'initialMs' => 100, 'maxMs' => 500],
    'circuitBreaker' => [
        'name' => 'http',
        'failureRatePct' => 50,
        'minSamples' => 4,
        'openMs' => 5000,
        'timeWindowSec' => 5,
    ],
]));

$stack = HandlerStack::create();
$stack->push(R4Middleware::wrap($policy));

$client = new Client([
    'base_uri' => 'http://httpbin:8080',
    'handler'  => $stack,
    'timeout'  => 3.0,
]);

$response = $client->get('/status/200');
echo $response->getStatusCode(), PHP_EOL;

---

🧠 Design

O design segue princípios inspirados em Resilience4j:

• Cada política implementa Resiliente\R4PHP\Contracts\Policy
• Operações encapsulam a execução via Executable
• As políticas podem ser compostas dinamicamente via Factory
• Suporte a configuração declarativa (Config::fromArray ou YAML/JSON)

---

🧪 Testes

Para executar a suíte de testes (PHPUnit):

composer install
composer test

---

🗺️ Roadmap

• Policy: Fallback
• Policy: Cache / Result Caching
• Integração com OpenTelemetry
• Exportadores de métricas (Prometheus / StatsD)
• Benchmarks de performance
• Console CLI (r4 monitor)
• Adaptação para frameworks (Laravel / Symfony)

---

👥 Contribuindo

Contribuições são muito bem-vindas!

1. Faça um fork do repositório
2. Crie uma branch com sua feature (git checkout -b feat/nova-policy)
3. Envie um PR descrevendo a motivação e uso

Consulte CONTRIBUTING.md e siga os padrões PSR-12 e SemVer.

---

📜 Licença

Licenciado sob Apache 2.0.
Parte do ecossistema Resilience4u.

---

🌎 Projetos irmãos

Projeto	Linguagem	Repositório
R4Go	Go	resilience4u/r4go
R4Js	JavaScript / Node.js	resilience4u/r4js
R4PHP	PHP	resilience4u/r4php