Download the PHP package allyson/laravel-http-service without Composer

HTTP Service - Laravel Package

Pacote Laravel para gerenciamento avançado de requisições HTTP com logging automático e controle de rate limiting.

Características

• Logging automático de todas as requisições HTTP (URL, payload, response)
• Controle inteligente de rate limiting (429) usando banco de dados
• Armazenamento completo do histórico de requisições
• Totalmente configurável via arquivo de config ou .env
• Compatível com Laravel 12
• Gerenciamento de domínios bloqueados com timestamps
• Tracking de tempo de resposta
• Comandos Artisan para gerenciamento
• Controle granular - habilite/desabilite logging e rate limit por requisição

Instalação

Via Composer

Configuração Inicial

Execute o comando de instalação que irá publicar config e migrations:

Execute as migrations:

Uso Rápido

Métodos Disponíveis

Requisições HTTP

Controles Opcionais

Cache de Requisições

O pacote oferece recursos avançados de cache para otimizar requisições repetidas.

Cache com Expiração Dinâmica

Cache baseado em campos da resposta que contêm informações de expiração:

Máscara de Expiração

Defina como interpretar o valor do campo de expiração:

• expiresAsDatetime() - Data/hora no formato Y-m-d H:i:s ou ISO 8601 (padrão)
• expiresAsSeconds() - Valor em segundos
• expiresAsMinutes() - Valor em minutos

TTL de Fallback

Use um TTL padrão caso o campo não seja encontrado:

Cache Fixo

Cache com tempo de vida fixo:

Cache Condicional

Cache ativado apenas após múltiplas chamadas:

Desabilitar Cache

Limpar Cache

Cache por Status (cacheOnly / cacheExcept)

Você pode controlar o cache com base nos códigos HTTP da resposta usando os métodos cacheOnly e cacheExcept.

• cacheOnly(array $statuses, ?int $ttl = null): self

  • Armazena em cache apenas as respostas cujo status_code esteja presente em $statuses.
  • Se $ttl for passado, ele sobrescreve o TTL para essa requisição específica (em segundos).
  • Retorna uma cópia (clone) do HttpService, então a configuração afeta apenas a cadeia encadeada desta chamada.
• cacheExcept(array $statuses, ?int $ttl = null): self
  • Armazena em cache todas as respostas exceto aquelas cujo status_code esteja em $statuses.
  • Se $ttl for passado, ele sobrescreve o TTL para essa requisição específica (em segundos).
  • Retorna uma cópia (clone) do HttpService, então a configuração afeta apenas a cadeia encadeada desta chamada.

Observações de implementação:

• Os métodos cacheOnly e cacheExcept definem cacheStrategy = 'always', portanto ativam o cache para aquela chamada.
• Os filtros são aplicados somente no momento de armazenamento: o pacote verifica o status da resposta e respeita cacheOnlyStatuses e cacheExceptStatuses antes de persistir no cache.
• cacheOnly limpa cacheExceptStatuses e vice-versa; assim, elas não entram em conflito.
• Se você preferir limpar ambos os filtros manualmente, use clearCacheStatusFilters().

Revisão da implementação

Após revisar src/Services/HttpService.php, os métodos cacheOnly e cacheExcept já estão implementados corretamente e não precisam de alterações funcionais imediatas. Uma sugestão opcional para consistência é que clearCacheStatusFilters() poderia retornar um clone (como outros métodos que configuram comportamento) para manter o padrão imutável/encadeável, mas isso não é obrigatório.

Formatos de Data/Hora Suportados

Para expiresAsDatetime():

• Y-m-d H:i:s - Exemplo: "2025-12-17 13:02:14"
• ISO 8601 - Exemplo: "2025-12-17T13:02:14Z"
• Qualquer formato aceito pelo construtor DateTime do PHP

Notação de Ponto para Campos Aninhados

• 'field' → busca $response['field']
• 'data.auth.expires' → busca $response['data']['auth']['expires']
• 'user.preferences.cache.ttl' → busca $response['user']['preferences']['cache']['ttl']

Exemplos Completos

Veja examples/cache-expires-examples.php para mais exemplos de uso.

Rate Limiting

O pacote gerencia automaticamente erros 429 (Too Many Requests):

Funcionamento Automático

1. Antes da requisição: Verifica se o domínio está bloqueado
2. Durante a requisição: Executa normalmente se não houver bloqueio
3. Após 429: Bloqueia o domínio automaticamente
4. Retry-After: Respeita o header Retry-After do servidor

Tratamento de Exceções

Estratégia Wait-on-Rate-Limit

Ao invés de lançar RateLimitException, o serviço pode aguardar de forma síncrona até o bloqueio expirar e então executar a requisição normalmente.

Ativar globalmente via config ou .env:

Ativar por chamada com waitOnRateLimit():

Desativar pontualmente (quando estiver ligado globalmente):

Atenção: O processo ficará bloqueado (via sleep) pelo tempo exato restante do bloqueio. Não use em requests web síncronos com bloqueios longos. Ideal para jobs/queues ou cenários onde o default_block_time é pequeno.

Gerenciamento Manual

Circuit Breaker

O circuit breaker é um padrão de resiliência que abre o circuito após N falhas consecutivas de um domínio, bloqueando requisições imediatamente (sem nem tentar a conexão) durante um período de recuperação. Diferente do rate limiting (que reage a 429), o circuit breaker é genérico e protege contra qualquer tipo de falha (5xx, timeouts, erros de conexão).

Estados

Habilitando Globalmente

Via config ou .env:

Exemplo: configurando tempos (circuit breaker)

O HTTP_SERVICE_CIRCUIT_BREAKER_RECOVERY_TIME é expresso em segundos. Exemplo: aumentar para 120 segundos (2 minutos):

Observação: diferentemente do rate limit, que usa minutos para o bloqueio padrão (default_block_time), o circuit breaker usa segundos para recovery_time.

Habilitando por Chamada

Tratamento de Exceções

Wait on Circuit Breaker

Por padrão, quando o circuito está OPEN o serviço lança CircuitBreakerException imediatamente. Com waitOnCircuitBreaker() o comportamento muda: o serviço aguarda (sleep) até o tempo de recuperação expirar e então tenta a requisição novamente em estado HALF-OPEN — idêntico ao waitOnRateLimit() para o rate limiting.

Atenção: não use em processos web síncronos com recovery_time longo. Ideal para jobs/queues ou quando o circuit_breaker_recovery_time for baixo.

Ativando globalmente via config ou .env:

O método throwOnCircuitBreaker() permite sobrescrever o comportamento global em chamadas específicas.

Diferença entre Circuit Breaker e Rate Limiting

Namespace Compartilhado entre Projetos

Por padrão, o estado do circuit breaker é isolado por aplicação — cada projeto mantém sua própria contagem de falhas. Isso é o comportamento correto na maioria dos casos.

Se dois ou mais projetos usam o mesmo driver de cache (ex: mesmo Redis) e precisam compartilhar o estado — para que o App B saiba que o App A já detectou que um domínio está fora do ar — configure o mesmo namespace nos dois:

Com isso, as chaves de cache ficam no formato http_cb_produtivo_<md5(domain)> e são compartilhadas entre os projetos.

Se HTTP_SERVICE_CB_NAMESPACE não for definido (padrão), cada app tem seu estado independente com chaves http_cb_<md5(domain)>.

Atenção: ao compartilhar namespace, um único projeto sofrendo falhas de rede ou erros locais pode abrir o circuito para todos os outros. Use com cuidado em ambientes heterogêneos.

Consultar Logs

Models e Query Scopes

Estrutura do Log

Cada log contém:

• url - URL completa da requisição
• method - Método HTTP (GET, POST, etc)
• payload - Dados enviados (JSON)
• response - Resposta recebida (JSON)
• status_code - Código de status HTTP
• response_time - Tempo de resposta em segundos
• error_message - Mensagem de erro (se houver)
• created_at / updated_at - Timestamps

Estrutura do Controle de Rate Limit

Cada registro de bloqueio contém:

• domain - Domínio bloqueado
• blocked_at - Momento do bloqueio
• wait_time_minutes - Duração do bloqueio em minutos
• unblock_at - Momento em que o bloqueio expira
• reason - Motivo do bloqueio (opcional, preenchível via create/update)
• created_at / updated_at - Timestamps

Comandos Artisan

Instalação

Gerenciamento de Bloqueios

Limpeza de Logs

Configuração

Arquivo config/http-service.php:

Variáveis de Ambiente (.env)

Tabelas Customizáveis

Por padrão o pacote usa http_request_logs e rate_limit_controls. Para usar nomes diferentes sem alterar as migrations:

Os models HttpRequestLog e RateLimitControl aplicam o nome configurado via setTable() no construtor.

Conexões de Banco Separadas

Para isolar logs e rate limiting da conexão principal (útil para garantir persistência mesmo com rollback de transação):

Se HTTP_SERVICE_RATELIMIT_CONNECTION não estiver definido, o pacote usa HTTP_SERVICE_LOGGING_CONNECTION como fallback. Se nenhum estiver definido, usa a conexão padrão do Laravel.

Exemplos de Uso

Em Controllers

Em Jobs/Queue

Com Retry Logic

Manutenção e Performance

Limpeza Automática

Configure tarefas agendadas no app/Console/Kernel.php:

Índices de Banco de Dados

As migrations já incluem índices otimizados para:

• Consultas por URL
• Consultas por método HTTP
• Consultas por status code
• Consultas por data
• Verificação de bloqueios de domínio

Requisitos

• PHP 8.2 ou superior
• Laravel 12.x
• Banco de dados (MySQL, PostgreSQL, SQLite, etc)

Estrutura do Pacote

Documentação Adicional

• Guia de Instalação Detalhado
• Exemplos de Uso
• Changelog

Contribuindo

Contribuições são bem-vindas! Por favor, abra uma issue ou pull request.

Licença

MIT License - veja LICENSE para detalhes.

Suporte

Para dúvidas ou problemas:

• Abra uma issue no GitHub
• Email: [email protected]

Créditos

Desenvolvido por Allyson P. da Mata