README

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!

Faça um fork do repositório
Crie uma branch com sua feature (git checkout -b feat/nova-policy)
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

resilience4u / r4php

Maintainers

Details