Value Objects nos SDKs SUOT — tipagem de campos fiscais

<?php

use Suot\Fiscal\ValueObjects\Cnpj;
use Suot\Fiscal\ValueObjects\ChaveCTe;
use Suot\Fiscal\ValueObjects\Protocolo;
use Suot\Fiscal\Exceptions\InvalidValueException;

// ✅ Construção bem-sucedida — CNPJ válido
$cnpj = new Cnpj('12345678000195');

// ❌ Lança InvalidValueException imediatamente — CNPJ com dígito verificador errado
try {
    $cnpjInvalido = new Cnpj('12345678000100');
} catch (InvalidValueException $e) {
    // O erro está aqui, na origem, não dentro do Handler ou no retorno da SEFAZ.
    echo $e->getMessage(); // "CNPJ inválido: dígito verificador incorreto."
}

// ❌ Lança InvalidValueException — chave com comprimento errado
try {
    $chaveIncompleta = new ChaveCTe('35240112345678');
} catch (InvalidValueException $e) {
    echo $e->getMessage(); // "ChaveCTe deve ter exatamente 44 dígitos."
}

<?php

// O PHPStan detecta esse erro antes da execução:
// Argument #1 ($emitente) of CteAutorizacaoCommand::__construct()
// expects Suot\Fiscal\ValueObjects\Cnpj, string given.

$command = new CteAutorizacaoCommand(
    emitente: '12345678000195', // ← erro de tipo detectado estaticamente
    chave: new ChaveCTe('35240112345678000195570010000000011000000014'),
    xml: $xmlAssinado,
);

<?php

use Suot\Antt\Rntrc\ConsultaRntrcCommand;
use Suot\Antt\ValueObjects\Rntrc;
use Suot\Antt\ValueObjects\Cnpj;

// Named arguments + Value Objects = intent clara, sem ambiguidade
$command = new ConsultaRntrcCommand(
    transportador: new Cnpj('98765432000188'),
    rntrc: new Rntrc('87654321'),
);

// Comparação: o mesmo código sem Value Objects e sem named arguments
// $command = new ConsultaRntrcCommand('98765432000188', '87654321');
// ↑ Qual é o transportador? Qual é o RNTRC? Qual é a ordem dos argumentos?
//   Isso só pode ser respondido consultando a assinatura do construtor.