Skip to content

v2.6.0 — contrato comum para os verificadores de assinatura

Choose a tag to compare

@mariolucasdev mariolucasdev released this 24 Oct 10:30
· 16 commits to develop since this release
bd66e9c

Uma mudança só, e ela é para quem não sabe o gateway em tempo de escrita.

Nenhuma quebra. O caminho até aqui passou por um desenho que quebrava, e a seção final explica.

Os verificadores de assinatura ganharam contrato

Os cinco gateways que assinam concordam em exatamente quatro métodos — um segredo, o corpo cru, os headers e uma resposta — e discordam em todo o resto: token no header, HMAC do corpo, RSA contra chave publicada, segredo na query.

Esse pedaço comum é o que código genérico precisa, e até agora ele não conseguia alcançá-lo: webhookSignature() devolvia object, sem nada para tipar.

use PHPay\Webhooks\VerifiesSignature;

$phpay = PHPay::make('asaas', $config);   // não sei o gateway em tempo de escrita

$ok = $phpay->webhookSignature()          // VerifiesSignature, não object
    ->setSecret($segredo)
    ->setPayload($corpo)
    ->setHeaders($headers)
    ->verify();

Quem segura o gateway concreto nunca teve o problema — AsaasGatewayInterface::webhookSignature() já devolve o verificador concreto. Isto é para quem não pode segurá-lo, que é o caso que a v2.5.0 passou a atender com PHPay::make().

Os setters de esquema específico ficam fora do contrato, porque pertencem a um esquema cada: setDataId() no Mercado Pago, setQuery() e setSignatureKey() na AbacatePay, setPublicKeys() na Woovi. Código genérico pergunta por eles com method_exists().

Por que a capacidade continua devolvendo object

O desenho óbvio seria estreitar o retorno da capacidade SupportsWebhookSignature. Isso é compatível para quem consome e fatal para quem implementa — tipo de retorno em PHP é covariante:

Fatal error: Declaration of GatewayPrivadoDeTerceiro::webhookSignature(): object
must be compatible with SupportsWebhookSignature::webhookSignature(): VerifiesSignature

Gateway próprio implementando uma capacidade é cenário suportado pela biblioteca, então aquele caminho exigiria um major. Em vez disso, só a facade estreita, e como a capacidade não garante mais o contrato, a facade confere em runtime e recusa um verificador que não o cumpra:

Privado: O verificador de assinatura deste gateway não cumpre
PHPay\Webhooks\VerifiesSignature.

Nos nove gateways da biblioteca isso nunca dispara, e há teste varrendo todos para continuar assim.

O que fica aberto

Quem tipa a capacidade para injeção de dependência — o que a documentação de capacidades recomenda — ainda recebe object. Fechar essa ponta exige major, e está registrado no CLAUDE.md para não ser redescoberto.

O de-para completo está no CHANGELOG.