Valide a conformidade: pré-verificação em processo e oráculo externo

Visão geral

Use esta receita para executar os validadores de conformidade em PHP puro e em processo do NextPDF como uma pré-verificação estrutural rápida e, em seguida, delegar a decisão de conformidade autoritativa a um validador independente. As verificações em processo são necessárias, mas não suficientes: um resultado limpo é um fato estrutural, não um veredito de conformidade. A receita usa examples/33-validate-conformance.php e o respectivo conjunto de testes tests/Cookbook/Php/ValidateConformanceRecipeTest.php.

Instalação

composer require nextpdf/core:^3

Os validadores em processo não exigem nenhuma cadeia de ferramentas externa. Para a etapa do portão autoritativo, você precisa de um validador externo no PATH. O exemplo usa o veraPDF. Você não precisa de um pacote Pro ou Enterprise.

Visão conceitual

O NextPDF inclui validadores em processo em \NextPDF\Compliance\Validator. Eles verificam invariantes normativas específicas sem iniciar processos externos:

• PdfRValidator — executa as verificações de fluxo de bytes do §5/§6 da ISO 23504-1 (PDF/R-1): a lista de permissão do cabeçalho do arquivo, objetos de geração 0, a lista de permissão de operadores de conteúdo de página do §6.5.7 (apenas q/Q/cm/Do) e a lista de permissão de chaves do dicionário Info do §6.4.3. Ele retorna um PdfRValidationFinding[] simples; uma lista vazia significa que todas as verificações do §6 sujeitas ao portão passaram.
• ArlingtonValidator — executa a gramática Arlington legível por máquina da PDF Association em modo somente relatório. Ele nunca bloqueia a build e registra, em cada descoberta, o SHA do commit fixado da gramática, para que consumidores de auditoria possam correlacionar o resultado com um snapshot upstream conhecido.

Essas verificações têm escopo deliberadamente limitado. Elas detectam desvios entre um contrato de emissão e uma especificação, mas não estabelecem conformidade ISO para perfis como PDF/A-4 ou PDF/UA-2. Um validador independente faz essa determinação, e o veredito dele é o portão da build (a ISO 19005-4 §6.7.3 deixa isso explícito para PDF/A). A receita mantém esse limite claro: ela executa a pré-verificação em processo e, em seguida, imprime e executa o comando do oráculo externo que decide.

O diagrama abaixo mostra o portão em duas etapas. Uma regra rege o fluxo: somente o veredito do oráculo externo pode ser reportado como conformidade.

Diagram

Superfície da API

A superfície da API é gerada a partir do PHPDoc. Use estes pontos de entrada principais:

• \NextPDF\Compliance\Validator\PdfRValidator::validate(string $pdfBytes): list<PdfRValidationFinding>
• \NextPDF\Compliance\Validator\PdfRValidationFinding (readonly: clause, severity, message)
• \NextPDF\Compliance\Validator\ArlingtonValidator::validateReportOnly(string $pdfPath): list<ArlingtonFinding>
• \NextPDF\Core\Document::output(?string $filename, OutputDestination $dest): string (OutputDestination::String para bytes brutos)

Exemplo de código — Início rápido

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Compliance\Validator\PdfRValidator;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'Document under conformance review.', newLine: true);

$bytes = $doc->output(dest: OutputDestination::String);

$findings = (new PdfRValidator())->validate($bytes);

// A finding list is a structural fact, not a conformance verdict.
echo $findings === []
    ? "No in-process PDF/R-1 findings (necessary, not sufficient).\n"
    : count($findings) . " in-process finding(s); not a conformance verdict.\n";

Exemplo de código — Produção

Em produção, trate o validador em processo como um portão barato que falha rápido diante de desvios estruturais óbvios. Em seguida, execute o oráculo externo como a decisão de conformidade autoritativa. Somente o veredito do oráculo pode ser reportado como conformidade.

examples/33-validate-conformance.php (gate core)

$bytes = $doc->output(dest: OutputDestination::String);
$doc->save($out);

// 1. In-process pre-check — necessary, not sufficient.
$findings = (new PdfRValidator())->validate($bytes);
foreach ($findings as $finding) {
    fwrite(STDERR, sprintf("[%s] §%s — %s\n",
        $finding->severity, $finding->clause, $finding->message));
}

// 2. The authoritative gate — the external validator decides.
$exitCode = 0;
$report = [];
exec('verapdf --flavour 4 ' . escapeshellarg($out), $report, $exitCode);

if ($exitCode !== 0) {
    fwrite(STDERR, "veraPDF FAILED — not reported conforming\n");
    fwrite(STDERR, implode("\n", $report) . "\n");
    exit(1);
}

echo "veraPDF PASS — the validator reports the file conforming\n";

Execute o exemplo com php examples/33-validate-conformance.php. Ele constrói um PDF comum e imprime as descobertas em processo. Espera-se que um PDF comum produza descobertas de PDF/R-1; esse resultado é intencional e didático. Em seguida, o exemplo imprime o comando autoritativo do oráculo externo.

Casos extremos e armadilhas

• Necessário, mas não suficiente. Uma lista de descobertas vazia do PdfRValidator significa apenas que as verificações do §6 sujeitas ao portão passaram. Não é uma declaração de conformidade com PDF/A-4 ou PDF/UA-2. Nunca reporte conformidade apenas a partir de um resultado em processo.
• Um PDF comum falha no PDF/R-1 por concepção. O PDF/R-1 é um perfil raster somente de imagem; um PDF de texto comum produz descobertas legítimas dos §6.5.7 e §6.4.3. O exemplo mostra isso de propósito para deixar claro: a saída em processo é um fato estrutural, não um veredito.
• O Arlington é somente relatório. ArlingtonValidator::validateReportOnly() nunca lança exceção e nunca bloqueia. No modo somente gramática, ele emite uma descoberta info que comprova que o SHA fixado da gramática foi carregado; ele retorna uma lista vazia quando a gramática não está materializada. Não construa um portão de pass/fail sobre ele — é um artefato de verificação cruzada.
• Bytes vs. arquivo. PdfRValidator::validate() recebe a string de bytes brutos (OutputDestination::String); o oráculo externo precisa de um caminho de arquivo. Salve o arquivo com save() para a etapa do oráculo.
• Entrada vazia. Passar uma string vazia ou sem cabeçalho para PdfRValidator::validate() retorna uma descoberta de erro do §6.2.2, em vez de lançar uma exceção. Verifique a lista de descobertas; não presuma uma exceção.

Desempenho

Os validadores em processo usam varreduras de bytes e de expressões regulares em passagem única sobre o PDF. Eles são rápidos, fazem pouca alocação para documentos típicos e permanecem dentro do orçamento de 2000 ms / 128 MB. Quando presente, o oráculo externo domina o tempo total, mas é executado fora do processo. Aplica-se o perfil de reprodutibilidade semântica. O valor do exemplo está no comportamento de validação observável, e o conjunto de testes verifica esse comportamento por meio de uma árvore de sintaxe abstrata (AST) estrutural combinada com a comparação de metadados.

Notas de segurança

Residência de dados e mitigações de PII

Os validadores leem os bytes do documento em processo, e nada sai do processo. O oráculo externo, porém, recebe o arquivo. Se você executar um validador hospedado, o conteúdo do documento sai do seu limite. Para conteúdo sensível, prefira um binário de validador local ou faça a redação antes da validação.

Telemetria segura e limpeza de logs

As descobertas podem citar caminhos de objetos e fragmentos de operadores. O exemplo escreve as descobertas em STDERR e uma linha de progresso fixa em STDOUT. Para documentos sensíveis, mantenha os logs de descobertas fora de destinos compartilhados. Nunca registre os bytes brutos do PDF em logs.

Modelo de ameaças

Um resultado em processo limpo não é sinal de integridade nem de autenticidade. Um produtor hostil pode forjar um arquivo que passa nas verificações em processo de escopo limitado, mas falha no validador completo, ou que é bem formado, porém enganoso. Trate a aprovação em processo como um filtro rápido, nunca como confiança.

Comportamento em modo FIPS

Esta receita não executa nenhuma operação criptográfica. O modo Federal Information Processing Standards (FIPS) não altera seu comportamento. Não ocorre nenhuma assinatura, criptografia ou digest de material de confiança.

Conformidade

Declaração	Especificação	Cláusula	reference_id
O conteúdo de página do PDF/R-1 usa apenas a lista de permissão de operadores q/Q/cm/Do.	ISO 23504-1	§6.5.7
As páginas de PDF/R-1 são conteúdo raster somente imagem.	ISO 23504-1	§6.5.5
O PDF/R-1 restringe as chaves do dicionário de informações do documento.	ISO 23504-1	§6.4.4
A gramática Arlington é uma verificação cruzada de modelo de objetos legível por máquina.	Arlington PDF Model	gramática
Um validador, não o produtor, decide a conformidade.	ISO 19005-4	§6.7.3

Os validadores em processo do NextPDF verificam invariantes normativas específicas. Suporte não é conformidade; validação não é certificação. Um resultado em processo limpo não estabelece conformidade ISO; um validador independente (por exemplo, veraPDF) faz essa determinação. Use o veredito dele como portão da build.

Veja também

• Módulo Compliance
• Página de conformidade
• Produza saída em PDF/A-4
• Emita uma árvore de estrutura PDF/UA-2 com tags