Conformidade: roteamento de ConformanceMode e o limite de validação

Visão geral

NextPDF\Conformance é o único discriminador que informa ao writer qual contrato da International Organization for Standardization (ISO) um arquivo Portable Document Format (PDF) deve seguir. A biblioteca emite as estruturas definidas por esse contrato. Ela não certifica, nem pode certificar, o arquivo resultante como conforme. Apenas um validador externo pode certificar a conformidade.

Instalação

composer require nextpdf/core:^3

Visão conceitual

O módulo Conformance expõe dois tipos públicos. ConformanceMode é um enum baseado em valores que nomeia o contrato-alvo (Plain, PdfUa1, PdfUa2, PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f). ConformancePolicy é um objeto de valor imutável que combina um modo com chaves independentes de rigor.

O modo é a única fonte de verdade para as comportas posteriores do writer. Antes da existência deste enum, o motor inferia, a partir de flags dispersas, se um documento estava marcado conforme a especificação. ConformanceMode::isTagged(), isAccessibility(), isArchival(), pdfaPart(), pdfaConformanceLetter() e requiresPdf17() retornam, cada um, uma resposta tipada que o writer lê diretamente. O catálogo, o /MarkInfo, a linhagem do cabeçalho do arquivo e os marcadores pdfaid do Extensible Metadata Platform (XMP) permanecem alinhados à intenção declarada.

Interprete literalmente o limite de suporte. O NextPDF Core emite estruturas definidas por essas normas. A ISO 19005-4:2020 §6.7.3 especifica o esquema de identificação que registra qual variante de PDF/A um arquivo declara. A ISO 19005-4:2020 declara que a conformidade é determinada conforme especificado em sua Cláusula 5: em relação aos requisitos normativos, por uma ferramenta de verificação, não pela biblioteca produtora. A ISO 14289-2:2024 §6 enquadra a conformidade como uma propriedade que um arquivo satisfaz. Definir um modo do NextPDF é uma entrada necessária para um arquivo em conformidade. Por si só, isso não constitui um resultado de conformidade.

Isso segue a mesma disciplina de Verificado-versus-Declarado da matriz de suporte de Cascading Style Sheets (CSS). Uma capacidade é Verificada somente quando possui tanto um teste ou execução de oráculo aprovado quanto uma cláusula citada. Todo o restante é algo que a biblioteca emite: útil, mas não uma garantia de conformidade. A conformidade pertence ao arquivo final e a um validador, não a uma promessa da biblioteca. Valide a saída com o veraPDF (consulte “Conformidade” abaixo).

Um segundo limite é importante para o trabalho de arquivamento. A autoria de PDF/A-4, incluindo o dicionário OutputIntent, o perfil embutido do International Color Consortium (ICC) e o esquema de extensão XMP, é fornecida pela extensão nextpdf/pro, não pelo Core. Em uma instalação somente com o Core, Document::enablePdfA() lança InvalidConfigException porque a capacidade security.pdfa não está registrada. O Core ainda detém o discriminador ConformanceMode; portanto, a introspecção e o caminho marcado de PDF/Universal Accessibility (PDF/UA-2) funcionam, mas ele não cria um arquivo PDF/A-4 por conta própria.

Superfície da API

Tipo	Categoria	Membros principais
NextPDF\Conformance\ConformanceMode	enum: string	Plain, PdfUa1, PdfUa2, PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f; isTagged(), isAccessibility(), isArchival(), requiresPdfUa2PageTabs(), pdfaPart(): ?int, pdfaConformanceLetter(): string, requiresPdf17(): bool
NextPDF\Conformance\ConformancePolicy	final readonly class	__construct(ConformanceMode $mode = PdfUa2, bool $strictUa2 = false, bool $rejectUnvalidatedLang = false, …); lax(), strictUa2(), withUax9IsolateSupport(), withoutAstShadowMode(), withBlackPointCompensation(), withStrictOcspProducedAtTolerance(), withAllowStaleOcsp()

ConformancePolicy impõe um invariante no construtor: as chaves estritas de PDF/UA-2 se aplicam apenas quando o modo é PdfUa2, e strictUa2 = true força rejectUnvalidatedLang = true. Combinações incoerentes lançam InvalidConfigException em vez de degradar silenciosamente.

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

<?php

declare(strict_types=1);

use NextPDF\Conformance\ConformanceMode;

$mode = ConformanceMode::PdfA4f;

// Introspect the declared contract — these drive writer-side gates.
$mode->pdfaPart();              // 4
$mode->pdfaConformanceLetter(); // 'F'
$mode->requiresPdf17();         // false (PDF/A-4 is PDF 2.0 lineage)
$mode->isArchival();            // true

Exemplo de código — Produção

O caminho que acompanha o Core e exercita um contrato de conformidade de ponta a ponta é a rota marcada de PDF/UA-2. Este exemplo executável fica em examples/31-pdfua2-tagged.php. Ele também é o alvo do oráculo para o perfil estrito de PDF/UA-2.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

$doc = Document::createStandalone();

// Set the tagged-PDF contract BEFORE writing content so the HTML pipeline
// wires the TaggedContentEmitter at parser-construction time.
$doc->enableTaggedPdf(lang: 'en');

$doc->setTitle('Accessible report');
// … write content …

$doc->save(__DIR__ . '/out/report-ua2.pdf');

// The library has now emitted PDF/UA-2 structures. It has NOT asserted
// conformance. Verify the file with the pinned veraPDF oracle:
//
//   php oracle/run.php pdfua.strict
//
// (Requires the veraPDF Docker image — opt-in; see "Conformance" below.)

Casos extremos e pegadinhas

• A autoria de PDF/A-4 é Premium. Em uma instalação somente com o Core, Document::enablePdfA() lança InvalidConfigException (security.pdfa indisponível). O Core detém o discriminador, não a emissão de OutputIntent/ICC/XMP. Consulte /specifications/pdfa4/.
• Caso guarda-chuva versus casos de variante. PdfA4 é o caso guarda-chuva e reporta um pdfaConformanceLetter() vazio. A ISO 19005-4:2020 §6.7.3 determina que um arquivo que não esteja em conformidade nem com PDF/A-4e nem com PDF/A-4f não forneça nenhum pdfa:conformance. Use PdfA4e / PdfA4f apenas para as variantes do Anexo B / Anexo A.
• O PDF/UA-2 estrito é opcional. ConformancePolicy::lax() é o padrão compatível com versões anteriores. strictUa2() força /MarkInfo /Marked true e a rejeição de Best Current Practice (BCP) 47. Habilitá-lo em um modo diferente de PdfUa2 lança exceção.
• isTagged() reconhece variantes. Plain, PdfA2, PdfA3b e PdfA4e reportam como não marcados. O writer não deve inferir uma árvore de estrutura apenas a partir do modo de arquivamento.
• Um modo aprovado não é um arquivo aprovado. Definir PdfA4 não torna a saída um arquivo PDF/A-4 válido. Execute um validador.

Desempenho

ConformanceMode e ConformancePolicy são tipos de valor puros. A resolução de casos do enum e o despacho do match são O(1), sem alocação além do objeto de política imutável. Eles não adicionam custo mensurável ao caminho de escrita. O writer, não o discriminador, domina o orçamento do módulo (wall_ms: 1500). O oráculo veraPDF é uma etapa fora de banda de integração contínua (CI), não parte da geração de documentos.

Notas de segurança

As chaves estritas em ConformancePolicy controlam comportamentos de segurança fail-closed: securityPkiRfc5280Strict (validação de caminho da Request for Comments (RFC) 5280 §6), strictOcspProducedAtTolerance (janela de desvio da RFC 6960 §4.2.2.1) e allowStaleOcsp (padrão false; rejeita respostas do Open Certification Status Protocol (OCSP) sem nextUpdate). Esses padrões são conservadores e se tornarão estritos em uma versão principal futura, conforme a estratégia documentada de compatibilidade com versões anteriores. Consulte o módulo de segurança e o modelo de ameaças do projeto para detalhes do caminho de assinatura.

Conformidade

O NextPDF não certifica conformidade. Ele emite estruturas definidas pelas normas abaixo. Um validador separado decide se um arquivo está em conformidade.

Norma	Cláusula	O que o NextPDF Core faz	Status
ISO 14289-2:2024 (PDF/UA-2)	§6	Emite a árvore de estrutura, /MarkInfo /Marked true (estrito), /Lang, XMP pdfuaid pelo caminho marcado do Core	Perfil verificado: pdfua.strict validado pelo oráculo veraPDF (php oracle/run.php pdfua.strict) quando o binário veraPDF está presente (comporta opcional)
ISO 19005-4:2020 (PDF/A-4)	§6.7.3	Emite o discriminador pdfaid:part / pdfa:conformance via ConformanceMode	Declarado (emissão do discriminador, testado por unidade); a autoria de arquivo PDF/A-4 é exclusiva do Premium
ISO 32000-2:2020 (PDF 2.0)	§7.5.2	Estrutura base de catalog/document	Declarado (comportamento base do motor)

Suporte não é conformidade. O NextPDF Core emite estruturas de identificação de PDF/UA-2 e PDF/A-4, com evidência de implementação em tests/Unit/Conformance/. Apenas um validador executando o perfil correspondente pode afirmar que um arquivo está em conformidade com PDF/A-4 ou PDF/UA-2. Conforme a Cláusula 5 da ISO 19005-4:2020, determinar a conformidade é tarefa do validador, não da biblioteca produtora.

A comporta do veraPDF é honesta quanto ao seu requisito. O oráculo (oracle/run.php, oracle/lib/OracleRunner.php) invoca uma imagem Docker fixada do veraPDF. Quando o Docker ou a imagem está ausente, o executor sai com o código 2 (falha de infraestrutura) e não verifica nada. Portanto, o perfil pdfua.strict é uma comporta de conformidade opcional. Ele prova a conformidade apenas em máquinas onde o binário veraPDF está presente. O NextPDF não inclui nenhum validador embutido e não faz nenhuma declaração de conformidade na ausência dele.

As citações são parafraseadas a partir do corpus de conformidade do NextPDF. Os digests completos de 64 caracteres de reference_id são registrados no frontmatter da página e em _normative-evidence-conf.md.

Veja também

• Módulo de conformidade — validador PDF/R-1, gramática Arlington e ferramentas de ciclo de vida
• Módulo de acessibilidade — emissor de conteúdo marcado PDF/UA-2
• Mapeamento da especificação PDF/A-4 — cobertura de recursos da ISO 19005-4 e não cobertura explícita
• Mapeamento da especificação PDF/UA-2 — mapeamento de acessibilidade da ISO 14289-2
• Módulo de segurança — chaves estritas do caminho de assinatura