Repository navigation
v2.1.0 — Money, Customer e Woovi/OpenPix
Um gateway novo e dois value objects que fecham uma lacuna da v2.0.0: a biblioteca normalizava os nomes dos métodos entre gateways, mas deixava os payloads crus. Quem integrava ainda precisava saber que um gateway quer reais e outro quer centavos, e que o CPF se chama cpfCnpj num e document noutro.
Tudo aditivo — veja a nota de compatibilidade abaixo.
💸 Money: o erro de centavos vs reais, eliminado no tipo
Dois gateways usam reais decimais; os outros sete usam centavos inteiros. Mandar 100.50 num gateway de centavos não quebra a integração — cobra R$ 1,00, e você só descobre na conciliação.
use PHPay\Support\Money;
$valor = Money::reais(100.50); // ou Money::centavos(10050)
$asaas->charge()->setAmount($valor); // vira 100.50
$pagbank->charge()->addItem('Item', $valor); // vira 10050O mesmo objeto, a unidade certa em cada gateway.
- Aceita string em notação brasileira:
'100,50','1.234,56' multiply(),plus(),equals(),format()→'R$ 100,50'- Recusa mais de duas casas decimais em vez de arredondar calado:
Money::reais(10 / 3)lança exceção. Arredondamento silencioso é como nascem erros de um centavo na conciliação. - Novo
setAmount()no Asaas, Mercado Pago e Efí, onde o valor vivia dentro do array de payload
👤 Customer: uma forma só para o cliente
O mesmo campo tinha seis grafias: cpfCnpj, tax_id, document, taxId, taxID, cpf_cnpj.
use PHPay\Support\Customer;
$cliente = Customer::make(
name: 'Mário Lucas',
document: '123.456.789-01', // pontuação é limpa
email: 'fale@phpay.io',
phone: '(11) 94002-8922',
);
$phpay->charge()->setCustomer($cliente); // funciona em todosE carrega o que cada gateway deriva do cliente:
$cliente->isIndividual(); // o Pagar.me precisa como type
$cliente->documentType(); // 'CPF' | 'CNPJ', a Cielo quer em IdentityType
$cliente->firstName(); // o Mercado Pago quer o nome separado
$cliente->phoneParts(); // o PagBank quer {country, area, number}O value object cobre todos os campos obrigatórios de cliente dos oito gateways que têm cliente. withExtra() fica para opcionais específicos, como endereço.
🎉 Gateway novo: Woovi/OpenPix
O segundo gateway com as cinco capacidades, ao lado do Asaas.
| Gateway | Clientes | Cobranças | Assinaturas | Webhooks | Chaves Pix |
|---|---|---|---|---|---|
| Asaas | ✅ | ✅ | ✅ | ✅ | ✅ |
| Woovi/OpenPix | ✅ | ✅ | ✅ | ✅ | ✅ |
Duas empresas independentes preenchendo o mesmo contrato é evidência de que o modelo de capacidades da v2.0.0 descreve o domínio, e não um fornecedor.
$phpay->pix()->createKey(PixKeyTypeEnum::RANDOM);
$phpay->pix()->verifyKey('fale@phpay.io');
$phpay->charge()->setCorrelationId('pedido-1')->create(Money::reais(100.50));
$phpay->charge()->find('pedido-1'); // pelo SEU id, não pelo do gateway⚠️ Nota de compatibilidade
Para quem chama a biblioteca, nada muda. Todo método que recebe valor aceita Money|int (ou Money|int|float nos gateways de reais), e todo setCustomer() aceita Customer|array. Número cru e array continuam funcionando, lidos como sempre foram.
Para quem implementou SupportsCustomers num gateway próprio, há uma mudança de assinatura:
// v2.0.0
public function customer(array $customer = []): object;
// v2.1.0
public function customer(Customer|array $customer = []): object;Uma implementação com customer(array ...) passa a dar erro fatal no autoload, porque não pode aceitar menos que a interface. Ajuste a assinatura da sua implementação para Customer|array.
Pela regra estrita do SemVer isso seria major. Optamos por minor porque o contrato foi publicado na v2.0.0 horas antes, e a falha é alta — erro fatal imediato — e não silenciosa.
🧪 Qualidade
219 → 275 testes (759 asserções). Os mais importantes são os cruzados: o mesmo Money e o mesmo Customer produzindo o formato certo em cada gateway, numa expectativa só.