Skip to content

v2.1.0 — Money, Customer e Woovi/OpenPix

Choose a tag to compare

@mariolucasdev mariolucasdev released this 21 Sep 14:41
· 107 commits to develop since this release
6c9277f

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 10050

O 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 todos

E 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ó.