Repository navigation
v2.0.0 — oito gateways, exceções tipadas e capacidades declaradas
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.
SupportsPixKeyssignifica 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.
AsaasChargeRequestusava&&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 trazid, e existesetCustomerId().EfiGatewayfazia chamada de rede no construtor. Autoriza sob demanda, uma vez só.Efi\Charge::getStatus()apontava para o endpoint do Asaas.WebhookEventsEnumusava namespace fora do autoload e não carregava.EfiGateway::customer()/webhook()devolviamstdClassvazio, causando "undefined method" adiante.examples/efi/charges.phppassava100.00num 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,lowestehighest. - PHPStan nível 9 como fonte única, com
phpVersionmí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
- Métodos lançam exceção em vez de retornar
['error' => ...] - Gateways declaram capacidades —
GatewayInterfacetem sóname() PHPay\Gateways\Asaas\*eEfi\*deixaram de existirpix()não aceita mais argumentomessages()de cobrança e assinatura ficou planoAsaasExceptionseAsaasPixRequestremovidasAsaasGatewayperdeu as propriedades públicas$cliente$customer
Requisitos
Consumir a lib: PHP ^8.1 (inalterado). Desenvolver: PHP ^8.2.