Repository navigation
v2.5.0 — estorno, status e webhook com forma única, e o gateway podendo vir da config
Cinco frentes entraram desde a v2.4.0, e quatro delas são a mesma ideia aplicada em lugares diferentes: o que divergia entre os nove gateways passa a ter forma única.
Nenhuma assinatura existente mudou de comportamento. Duas quebram em caso de borda, e estão descritas no fim.
Estorno virou capacidade
Seis gateways já estornavam, com três nomes para a mesma operação — refund, cancel, void —, três unidades e três sentidos para valor ausente. E nenhum era alcançável pela facade: quem segurava PHPay tinha que descer para o gateway concreto e saber de antemão como o método se chamava ali.
$phpay->refund($id); // devolve tudo
$phpay->refund($id, 2500); // parte, na unidade daquele gateway
$phpay->refund($id, Money::reais(25.50)); // o mesmo valor nos seteAsaas e Woovi ganharam o método — os dois gateways completos não o tinham, embora a API dos dois exponha o endpoint. Cielo e Pagar.me ganharam refund() sobre o endpoint que já tinham; cancel() continua nas duas, porque ali um endpoint só anula e estorna.
Efí e AbacatePay ficam de fora, cada uma pelo seu motivo, e os motivos estão na documentação.
Status de pagamento numa forma só
A mesma cobrança paga voltava como RECEIVED, COMPLETED, approved, PAID, paid, CONCLUIDA ou '00', dependendo de quem respondeu.
use PHPay\Asaas\Enums\InvoiceStatusEnum;
use PHPay\Support\PaymentStatus;
if (InvoiceStatusEnum::of($cobranca['status']) === PaymentStatus::PAID) {
// libera o pedido
}Os enums concretos continuam existindo e acessíveis. Cinco gateways não tinham enum de status e ganharam o seu — a Efí ganhou dois, porque as APIs de Cobranças e Pix respondem em vocabulários diferentes com as mesmas credenciais.
Três estados merecem nota, porque conflatá-los erraria sobre dinheiro: AUTHORIZED não é PAID (Cielo, PagBank e Mercado Pago separam autorização de captura), PARTIALLY_PAID existe pelo underpaid do Pagar.me, e PAID não é estado final — estorno e chargeback ainda vêm depois.
O webhook, do outro lado
A v2.3.0 provou que a notificação veio do gateway. Esta lê o que ela diz:
foreach ($gateway->webhookEvents($corpo) as $evento) {
if ($evento->type === EventType::PAID) {
liberarPedido($evento->resourceId);
}
}Devolve lista, nunca um evento. A API Pix da Efí manda pix como array — vários pagamentos numa requisição — e o PagBank manda o pedido com todas as cobranças. Tratar como objeto único perderia pagamento em silêncio.
E quando a notificação não carrega estado — Mercado Pago manda só data.id, a Cielo manda três campos —, status é null e requiresLookup() diz que é preciso consultar:
if ($evento->requiresLookup()) {
$cobranca = $phpay->charge()->find($evento->resourceId);
}O gateway pode vir da configuração
Antes só era possível começar sabendo a classe e a assinatura do construtor.
$phpay = PHPay::make('asaas', ['token' => $token, 'sandbox' => true]);PHPay::gateway() continua sendo o preferido quando você sabe o gateway em tempo de escrita: segurando o concreto, capacidade ausente é erro de análise e não de runtime.
Config errada falha na construção, nomeando a chave — inclusive chave desconhecida, porque um skandbox engolido é typo que só aparece em produção.
Guzzle 8, em comportamento e em tipos
A v2.5.0 aceita ^7.3 || ^8.0. A RetryPolicy continua distinguindo "não saiu da máquina" de "deu timeout depois de enviar" nas duas majors — a decisão que impede cobrança duplicada —, e agora o PHPStan nível 9 passa nas duas, com job próprio no CI.
Nada de nível afrouxado nem ignoreErrors: o que se passa ao Guzzle virou forma de array fechada, e a pilha de handlers é montada como variável local, porque declarar HandlerStack como tipo falha numa das duas majors com ou sem argumento genérico.
De passagem
Cobertura de testes de 88,8% para 91,2%, fechando os oito arquivos piores — entre eles o Asaas/Charge, que era o recurso mais usado da biblioteca e estava em 56,5%.
Duas quebras de borda
-
O parâmetro do
refund()do Mercado Pago foi renomeado de$valuepara$amount. O tipo alargou (?float→Money|int|float|null), então chamada posicional continua valendo e número cru continua lido em reais. Quebra só quem chamava por argumento nomeado:refund($id, value: 10.5). -
Três métodos
protectedsaíram doHasRedeClient:clientRedeOauthBoot(),oauthUri()eoauthTokenPath(). Não tinham chamador em lugar nenhum — oRedeGatewaysempre montou aquele client inline. É trait interno, mas quem o tivesse usado em código próprio sentiria.
O de-para completo está no CHANGELOG.