Repository navigation
v2.6.0 — contrato comum para os verificadores de assinatura
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.