Modelos, schema e ajuda de campos

A entrada raiz é TNFe. O SDK traz 204 tipos gerados do contrato ACBr: 124 objetos, 55 enums e 25 coleções. Os 828 campos dos objetos estão na referência completa do contrato. A fonte da revisão é autenticada pelo hash de contrato fixado; uma troca arbitrária de JSON é recusada.

Regras de entrada

Espécie	Valor PHP/JSON aceito
Objeto	Document/modelo do tipo certo, stdClass ou array associativo; {} na entrada JSON
Coleção	Lista PHP contígua, array JSON [] ou coleção gerada do tipo certo
Enum	String exata do enum ou BackedEnum compatível; sem conversão numérica
Inteiro	int dentro do intervalo do campo; "1" e 1.0 não são inteiros
Decimal	String com ponto, como '10.00', até 64 caracteres e escala permitida
Booleano	bool real
Data/hora	String civil AAAA-MM-DD ou AAAA-MM-DDTHH:mm:ss, com até 3 casas de fração; sem Z e sem offset
Texto	string; sem coerção de número, null ou booleano

Campos e maiúsculas seguem o contrato: Ide, Emit, Det, Prod, vProd são nomes exatos. Campos desconhecidos, somente leitura, enums incorretos e tipos incompatíveis são rejeitados. Campos omitidos continuam omitidos; o PHP não inventa defaults tributários. null não substitui a omissão.

Os limites de Configuration, XML e parâmetros de operação são adicionais aos tipos do documento; veja API e operações.

Documentos imutáveis

use Acbr\Document;
use Acbr\Model\TProd;

$original = (new TProd())->withCProd('TESTE')->withVProd('10.00');
$alterado = $original->withVProd('20.00');

assert($original->getVProd() === '10.00');
assert($alterado->getVProd() === '20.00');

$nota = Document::fromArray(['Ide' => ['tpAmb' => 'taHomologacao']]);
$nova = $nota->with(['Ide' => ['modelo' => 55, 'tpAmb' => 'taHomologacao']]);

with() substitui os campos do primeiro nível; objetos aninhados são substituídos integralmente, sem merge silencioso. Guarde o novo objeto retornado. without(...$fields) remove campos conhecidos. get() retorna valor destacado; getters gerados hidratam modelos/coleções aninhados. has() distingue campo omitido.

toArray() retorna array independente. Use toJson() ou jsonSerialize() para preservar a distinção entre {} e []. As opções JSON_NUMERIC_CHECK e JSON_FORCE_OBJECT são rejeitadas por toJson() para não transformar decimais ou coleções. Evite serializar o conteúdo fiscal em logs.

As coleções geradas têm fromArray(), fromJson(), get($index), withItem(), without($index), count() e iteração. São imutáveis e reindexam a lista ao remover um item. Veja o exemplo de modelos.

Ajuda sem motor nativo

Veja o guia de ajuda de campos e tipos para consultas Ide.tpNF/TTipoNFe, valores de enum, padrões declarados e exemplos completos. A API abaixo está disponível na alpha1 publicada.

use Acbr\Contract;

$contrato = Contract::bundled();
$metadados = $contrato->metadata();
$tipos = $contrato->types();
$produto = $contrato->type('TProd');
$campos = $contrato->fields('TProd');
$campo = $contrato->help('Det[].Prod.vProd');
echo $contrato->formatHelp('Ide.tpAmb'), PHP_EOL;

Um caminho pode começar por TNFe.; use [] ou [0] ao percorrer uma coleção. O help canoniza índices para []. Um nome curto que exista em vários grupos lança FieldHelpException com codigo === 'CAMPO_AMBIGUO' e candidates; escolha o caminho completo. Não há campo inexistente criado por aproximação.

O resultado informa path, kind, pascalType, inputType, readonly, revisão e hash; pode incluir values, constraints, declaredDefault, itemType e members. Um default declarado no Pascal é informação do contrato; a omissão continua preservando o comportamento do construtor nativo.

php examples/help.php 'Det[].Prod.vProd'
php examples/help.php 'TProd'

Três níveis de validação

1. Estrutura PHP: Document, modelos e Contract::validate() verificam os tipos da entrada. Não verificam todos os campos obrigatórios ou regras fiscais de uma nota.
2. XML/schema nativo: Emitter::validar($xml) executa o worker e os schemas distribuídos, com limitações da versão fixada.
3. Autorização fiscal: depende de cadastro, regras, serviços e retorno efetivo da SEFAZ, com provas coerentes de resultado. Assinatura e schema válidos não a substituem.

Contract::validate($value, $type = 'TNFe', $strictObjects = false) não devolve documento; retorna void ou lança. No modo estrito, objetos precisam ser stdClass, preservando {}/[] de JSON. normalize() valida e devolve um valor JSON compatível destacado. fromJson() usa validação estrita de objetos, profundidade máxima 128 e JSON UTF-8 válido.