Ajuda de campos e tipos

Consulte o contrato no próprio PHP antes de preencher uma NF-e ou NFC-e. A ajuda funciona offline, sem runtime nativo, certificado A1, Node.js ou npm. Ela descreve os metadados incluídos no pacote; não executa operações fiscais.

O que está disponível em cada versão

Interface	0.1.0-alpha1 publicada	0.1.0-alpha2 publicada
Contract::bundled()->help(TARGET)	Array PHP	Mesmo retorno
Contract::bundled()->formatHelp(TARGET)	Texto em português	Mesmo retorno
php examples/ajuda.php TARGET	Exemplo do checkout do SDK	Preservado
php examples/help.php TARGET	Exemplo JSON desta documentação	Preservado
php vendor/bin/acbr-php --help	Ajuda geral de runtime	Inclui as novas consultas
describe TARGET / describe TARGET --json	Indisponível	Texto / JSON
ajuda TARGET na CLI instalada	Indisponível	JSON
--version e ajuda de subcomandos	Indisponíveis	Versão do SDK / texto de uso

Alpha2 publicada

A referência corrente é 0.1.0-alpha2, publicada no Packagist, tag v0.1.0-alpha2. A fonte é o PR #5 mesclado, implementação dc77142285be e merge a3815542ee1a, com árvores idênticas. A tabela conserva a comparação com a alpha1, que não inclui os novos comandos CLI. O contrato de documentos e o runtime 0.2.1 permanecem iguais.

A CLI instalada da alpha1 não tem describe nem --version. Use composer show cosmemilton/acbr-php para conferir a versão instalada. A descrição de campos e tipos é feita pela API e pelos exemplos abaixo.

Consulta em código PHP

Depois da instalação Composer, salve este exemplo como ajuda-campos.php na raiz da aplicação e execute php ajuda-campos.php:

<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';

$contrato = Acbr\Contract::bundled();
$campo = $contrato->help('Ide.tpNF');
$tipo = $contrato->help('TTipoNFe');

if ($campo['values'] !== ['tnEntrada', 'tnSaida']
    || $tipo['values'] !== $campo['values']
    || $campo['declaredDefault'] !== 'tnSaida'
    || array_key_exists('declaredDefault', $tipo)) {
    throw new RuntimeException('Contrato inesperado.');
}

echo $contrato->formatHelp('Ide.tpNF'), PHP_EOL;
echo json_encode($tipo, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR), PHP_EOL;

As duas consultas mostram tnEntrada e tnSaida. O padrão tnSaida pertence ao campo Ide.tpNF, não à descrição do tipo TTipoNFe. Na entrada do documento, use o nome exato do enum ou um BackedEnum compatível; não converta automaticamente para códigos numéricos.

Um padrão declarado na ajuda é informação do contrato. O PHP não o insere automaticamente nos campos omitidos; a omissão preserva o comportamento do construtor nativo.

Exemplos no terminal

Os arquivos baixáveis desta documentação usam o autoload da aplicação consumidora. Copie a pasta examples/ para sua raiz, ou defina ACBR_PHP_AUTOLOAD para um autoload local instalado:

php examples/help.php 'Ide.tpNF'
php examples/help.php 'TTipoNFe'
php examples/help.php 'TNFe.Ide.tpNF'
php examples/help.php 'Det[].Prod.vProd'
php examples/help.php 'Det[0].Prod.vProd'
php examples/help.php 'TProd'

help.php imprime JSON em stdout e devolve saída 0. Um erro de consulta usa o diagnóstico JSON do exemplo e saída 1; autoload ausente usa stderr e saída 2. Isso descreve o exemplo desta documentação, não um novo comando da CLI do SDK. Baixe também seu bootstrap.php.

No checkout do SDK, o exemplo correspondente chama-se examples/ajuda.php. Consulte sua fonte fixada; não confunda os dois nomes de arquivo.

Campos, caminhos e coleções

Os nomes distinguem maiúsculas e minúsculas. O prefixo TNFe. é opcional para caminhos da raiz. Um nome curto pode ser ambíguo; prefira o caminho completo.

Det descreve a lista e seu tipo de item. Para chegar a Prod.vProd, selecione um item com [] ou um índice. Det[0].Prod.vProd é normalizado para TNFe.Det[].Prod.vProd; a ajuda não acessa um documento fiscal real.

O array de ajuda informa path, pascalType, kind, inputType, readonly, revisão e hashes. Conforme o alvo, inclui members, itemType, values, constraints e declaredDefault. Por exemplo, um decimal tem entrada em string. Ausência de limite ou padrão na resposta não autoriza inventar esse metadado.

formatHelp() formata a mesma consulta em texto legível. type('TTipoNFe') retorna o descritor de tipo do contrato; fields('TProd') lista campos de um objeto. fields() não aceita um enum. Veja a API de Contract, o contrato de entrada e o catálogo dos 204 tipos.

Erros e automação

<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';

try {
    $campo = Acbr\Contract::bundled()->help('CAMPO_QUE_NAO_EXISTE');
} catch (Acbr\Model\FieldHelpException $erro) {
    echo json_encode([
        'codigo' => $erro->codigo,
        'candidates' => $erro->candidates,
    ], JSON_THROW_ON_ERROR), PHP_EOL;
}

FieldHelpException estende InvalidArgumentException, com codigo e candidates; não herda de AcbrException. Entre os códigos estão CAMINHO_INVALIDO, CAMPO_INEXISTENTE, CAMPO_AMBIGUO e COLECAO_REQUER_INDICE. Para nome ambíguo, escolha um caminho de candidates. Não use o texto legível como protocolo de automação.

A ajuda não determina todos os campos obrigatórios, regras tributárias, validade do XML ou autorização fiscal. Confira os três níveis de validação e o tratamento de erros.

Fontes: Contract.php, CLI da alpha1 e exemplo do SDK. A validação desta documentação distingue testes locais de evidência recebida do SDK.

Consultas pela CLI na alpha2

Após a instalação da alpha2, execute na raiz da aplicação consumidora:

php vendor/bin/acbr-php --version
php vendor/bin/acbr-php --help
php vendor/bin/acbr-php describe --help
php vendor/bin/acbr-php describe Ide.tpNF
php vendor/bin/acbr-php describe TTipoNFe
php vendor/bin/acbr-php describe TTipoNFe --json
php vendor/bin/acbr-php describe --json 'Det[].Prod.vProd'
php vendor/bin/acbr-php ajuda Ide.tpNF

describe TARGET produz texto em português. A consulta describe Ide.tpNF começa assim:

TNFe.Ide.tpNF
Tipo: TTipoNFe (enum; entrada string)
Somente leitura: não
Valores: tnEntrada, tnSaida
Padrão declarado: tnSaida

A saída completa também informa revisão, hash do contrato e versão do SDK. describe TTipoNFe lista os mesmos valores sem o padrão do campo. Objetos listam membros, coleções mostram seu tipo de item e limites aparecem quando declarados no contrato.

Sem TARGET, describe e ajuda consultam TNFe. Caminhos como TNFe.Ide.tpNF e Det[0].Prod.vProd seguem as mesmas regras da API, incluindo normalização de índices para [].

describe TARGET --json imprime um objeto JSON; --json também pode vir antes do alvo. ajuda TARGET é a consulta JSON da CLI alpha2 e não aceita --json. Esses comandos novos não substituem a API Contract::help() nem os exemplos já existentes da alpha1.

# Salvar os metadados sem executar o motor.
php vendor/bin/acbr-php describe Ide.tpNF --json > campo.json

O JSON da CLI reúne o retorno de Contract::help() e o campo sdkVersion. Esse campo pertence ao envelope da CLI: Contract::help() mantém o retorno anterior, sem sdkVersion. Não foram acrescentadas funções PHP chamadas describe_field ou describe_type.

--version informa a versão do SDK, independente do runtime nativo 0.2.1. No checkout da alpha2, a saída é acbr-php 0.1.0-alpha2. Em uma instalação consumidora, usa a versão do pacote informada pelo Composer, omitindo o prefixo v de versões numéricas; versões de desenvolvimento conservam o nome. A alpha1 continua usando composer show cosmemilton/acbr-php.

Ajuda de comandos na alpha2

Na alpha2 instalada:

php vendor/bin/acbr-php ajuda --help
php vendor/bin/acbr-php help describe
php vendor/bin/acbr-php runtime:release --help
php vendor/bin/acbr-php runtime:install --help
php vendor/bin/acbr-php runtime:verify --help
php vendor/bin/acbr-php runtime:diagnose --help

-h também pede ajuda. Em um checkout do SDK, use php bin/acbr-php no lugar de php vendor/bin/acbr-php. Consultar ajuda não exige arquivos da pasta examples/, runtime instalado, A1 ou rede.

Os comandos runtime:release, runtime:install, runtime:verify e runtime:diagnose preservam seus argumentos e saídas JSON anteriores; não precisam de --json. Veja runtime e integridade. A expansão da ajuda não modifica os requisitos de plataforma do SDK PHP.

Erros e automação na CLI alpha2

Interface	Sucesso	Erro de consulta
describe TARGET	Texto em stdout; saída 0	Mensagem e ação em stderr; saída 1, stdout vazio
describe TARGET --json	Objeto JSON em stdout; saída 0	Diagnóstico JSON em stdout; saída 1, stderr vazio
ajuda TARGET	Objeto JSON em stdout; saída 0	Diagnóstico JSON em stdout; saída 1, stderr vazio

Um alvo inexistente ou ambíguo é erro de consulta. O diagnóstico JSON contém ok=false, codigo, mensagem, candidates e sdkVersion; entre os códigos estão CAMPO_INEXISTENTE, CAMPO_AMBIGUO e COLECAO_REQUER_INDICE. O texto legível não é um protocolo de automação.

Opção desconhecida, TARGET excedente ou outra sintaxe inválida produz saída 2 e mensagem em stderr, inclusive quando --json foi informado. ajuda TARGET --json é erro de sintaxe: ajuda já retorna JSON. Não confunda esses canais com os erros de consulta em JSON ou com os diagnósticos operacionais dos comandos de runtime.

Fontes fixas da alpha2: guia do SDK, implementação CLI e versão do SDK. Esses comandos consultam apenas metadados locais; não executam operações fiscais.