Skip to content

v2.0.0 — oito gateways, exceções tipadas e capacidades declaradas

Choose a tag to compare

@mariolucasdev mariolucasdev released this 21 Sep 05:34
· 114 commits to develop since this release
117fd83

Primeira versão com quebras de compatibilidade desde o lançamento, e a maior da biblioteca até aqui: de 2 para 8 gateways, falhas passam a ser exceção, e o projeto ganha CI, guia de migração e licença nova.

O de-para completo, quebra por quebra, está em UPGRADE.md.

🎉 Seis gateways novos

Gateway Clientes Cobranças Assinaturas Webhooks Chaves Pix
Asaas ✅ ✅ ✅ ✅ ✅
Mercado Pago ✅ ✅ ✅ — —
PagBank ✅ ✅ ✅ — —
Pagar.me ✅ ✅ ✅ — —
AbacatePay ✅ ✅ — — —
Cielo — ✅ ✅ — —
Rede — ✅ — — —
Efí — ✅ — — —

Cobre o topo do mercado brasileiro: Cielo e Rede lideram entre adquirentes (28% por usuários e 18% por volume), Mercado Pago e PagBank dominam e-commerce e PME, Pagar.me é o favorito técnico, e o AbacatePay traz o perfil Pix-nativo.

🧩 Gateways declaram o que suportam

GatewayInterface era a união de tudo que o Asaas sabe fazer — todo gateway precisava declarar cinco recursos mesmo sem suportá-los. Agora cada recurso é uma interface que o gateway implementa se, e só se, oferecer:

use PHPay\Contracts\Capability;

$phpay->supports(Capability::SUBSCRIPTIONS);
$phpay->capabilities();
$phpay->name();

Chamar um recurso indisponível diz o que o gateway oferece:

NotImplementedException: Rede não suporta chaves Pix.
                         Capacidades disponíveis: cobranças.

E quem segura o gateway concreto ganha a checagem em tempo de análise — (new RedeGateway(...))->pix() vira erro de PHPStan, não de produção.

SupportsPixKeys significa gerenciar chaves e QR Code estático, o que só um PSP que emite chave própria oferece. Todos os oito aceitam Pix — a coluna vazia não quer dizer o contrário.

🚨 Erros viram exceção

Um array retornado agora é sempre sucesso. Todas as exceções implementam PHPayException:

Exceção Quando
ValidationException payload inválido, antes de qualquer HTTP
ApiException gateway recusou ou está inacessível
NotImplementedException recurso não suportado pelo gateway

ApiException carrega getStatusCode(), getResponse(), getGateway() e isConnectionError().

💸 Unidade monetária documentada

Não estava em lugar nenhum, e errar não quebra a integração — ela cobra o valor errado:

Gateway Unidade R$ 100,50
Asaas, Mercado Pago Reais (decimal) 100.50
PagBank, Pagar.me, Cielo, Rede, AbacatePay, Efí Centavos (inteiro) 10050

Nos que usam centavos, o PHPay recusa valor decimal na validação, antes da chamada.

🐛 Correções

  • A validação de tipo não funcionava. AsaasChargeRequest usava && onde deveria usar ||: um campo presente com o tipo errado passava batido e seguia para a API.
  • setCustomer() criava cliente duplicado a cada chamada. Agora reaproveita quando o array traz id, e existe setCustomerId().
  • EfiGateway fazia chamada de rede no construtor. Autoriza sob demanda, uma vez só.
  • Efi\Charge::getStatus() apontava para o endpoint do Asaas.
  • WebhookEventsEnum usava namespace fora do autoload e não carregava.
  • EfiGateway::customer()/webhook() devolviam stdClass vazio, causando "undefined method" adiante.
  • examples/efi/charges.php passava 100.00 num gateway que usa centavos — cobraria R$ 1,00.

🧪 Qualidade

  • 3 → 219 testes (589 asserções). Todo recurso aceita um client HTTP injetado; nenhum teste toca a rede.
  • CI no GitHub Actions, matriz 8.2/8.3/8.4 com dependências locked, lowest e highest.
  • PHPStan nível 9 como fonte única, com phpVersion mínimo 8.1 garantindo a compatibilidade declarada.
  • Checagem de conformidade contra sandbox para Mercado Pago e PagBank, que roda de verdade e recusa credenciais de produção.

⚖️ Licença: MIT → Business Source License 1.1

A partir desta versão, source-available com uma única restrição comercial: ninguém pode oferecer o PHPay, ou um derivado, como biblioteca/SDK/serviço de integração de pagamentos concorrente.

Usar em produção, inclusive em software fechado e comercial, continua liberado — quem integra pagamentos no próprio produto não é afetado.

Em 2030-09-20 converte automaticamente para MIT, e cada versão converte no máximo quatro anos após ser publicada.

As versões 1.0.0 e 1.0.1 permanecem sob MIT — licença nova não é retroativa, e quem já baixou mantém aqueles direitos para sempre.

Contribuições passam a estar sujeitas ao CLA.

⚠️ Breaking changes

  1. Métodos lançam exceção em vez de retornar ['error' => ...]
  2. Gateways declaram capacidades — GatewayInterface tem só name()
  3. PHPay\Gateways\Asaas\* e Efi\* deixaram de existir
  4. pix() não aceita mais argumento
  5. messages() de cobrança e assinatura ficou plano
  6. AsaasExceptions e AsaasPixRequest removidas
  7. AsaasGateway perdeu as propriedades públicas $client e $customer

Requisitos

Consumir a lib: PHP ^8.1 (inalterado). Desenvolver: PHP ^8.2.