CLI: manipuladores de comandos e adaptadores para validadores externos

Visão geral

O módulo da interface de linha de comando (CLI) fornece a superfície de comandos para diagnóstico e conformidade do mecanismo. Ele inclui manipuladores para os comandos benchmark, diff, init, verify e capabilities, além de adaptadores que encapsulam validadores externos de Portable Document Format (PDF), incluindo o veraPDF e o modelo Arlington PDF, por trás de uma única interface. Um único comando verify pode executar qualquer adaptador.

Instalação

composer require nextpdf/core:^3

Visão conceitual

Cada comando usa uma classe manipuladora cujo método execute() retorna um código de saída do processo. BenchmarkHandler executa cenários de benchmark. DiffHandler compara documentos. InitHandler gera a estrutura de um projeto. VerifyHandler executa a verificação de conformidade. CapabilitiesHandler reporta o suporte do runtime. CliOutput é o escritor enxuto de stdout/stderr compartilhado pelos manipuladores, de modo que a saída permaneça testável em vez de acoplada a variáveis globais. BinaryFinder resolve o caminho de uma ferramenta externa no host (@since 2.5.0).

A superfície de validação é o principal limite arquitetural. AlternateValidatorAdapter é a interface implementada por um validador externo. validate() recebe um caminho de PDF e um ComplianceFlavour e retorna um ComplianceValidationResult. isAvailable() reporta se a ferramenta subjacente está instalada. toolIdentifier() identifica essa ferramenta. VeraPdfCliAdapter, ArlingtonValidatorAdapter e AsyncValidatorAdapter implementam essa interface. O mecanismo não reimplementa validadores de terceiros. Ele executa as ferramentas de referência e normaliza o veredito delas. Quando um validador não está instalado, ele reporta isAvailable() === false em vez de fazer a execução falhar, de modo que a verificação registre explicitamente a ferramenta ausente. Os adaptadores são @since 3.0.0; os manipuladores principais são @since 2.3.0–@since 2.5.0.

Superfície da API

Classe	Membros principais	Função
BenchmarkHandler	execute(string $format = 'pretty', ?string $scenario = null): int	Executa cenários de benchmark (@since 2.4.0)
VerifyHandler	execute(): int	Conduz a verificação de conformidade
DiffHandler / InitHandler	execute(): int	Diff de documento / estrutura do projeto
CapabilitiesHandler	execute(string $format = 'pretty'): int	Reporta as capacidades do runtime (@since 2.3.0)
AlternateValidatorAdapter (interface)	validate(), isAvailable(), toolIdentifier()	Contrato de validador externo (@since 3.0.0)
VeraPdfCliAdapter	implementa o adaptador	Envolve a CLI do veraPDF (@since 3.0.0)
ArlingtonValidatorAdapter	implementa o adaptador	Envolve o modelo Arlington PDF (@since 3.0.0)
AsyncValidatorAdapter	implementa o adaptador	Wrapper de validador com suporte a execução assíncrona (@since 3.0.0)
CliOutput	write(), writeln(), error()	Escritor de stdout/stderr testável (@since 2.3.0)
BinaryFinder	resolução de caminho de ferramenta externa	Localiza ferramentas no host (@since 2.5.0)

Para a tabela completa de PHPDoc, execute composer docs:generate-api-php -- --module=Cli.

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

Fonte: examples/33-validate-conformance.php. Selecione um adaptador de validador e verifique a disponibilidade antes de usá-lo:

<?php

declare(strict_types=1);

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

use NextPDF\Cli\VeraPdfCliAdapter;
use NextPDF\Compliance\ComplianceFlavour;

$validator = new VeraPdfCliAdapter(/* binary path / process factory */);

if (!$validator->isAvailable()) {
    fwrite(STDERR, "veraPDF is not installed; conformance verification skipped.\n");
    exit(2);
}

$result = $validator->validate('/srv/out/report.pdf', ComplianceFlavour::PdfA4);
echo $result->isCompliant() ? "PASS\n" : "FAIL\n";

Exemplo de código — Produção

Execute a verificação por meio dos validadores presentes. Trate uma ferramenta ausente como uma verificação ignorada, não como uma falha.

<?php

declare(strict_types=1);

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

use NextPDF\Cli\AlternateValidatorAdapter;
use NextPDF\Compliance\ComplianceFlavour;
use Psr\Log\LoggerInterface;

final readonly class ConformanceGate
{
    /** @param list<AlternateValidatorAdapter> $validators */
    public function __construct(
        private array $validators,
        private LoggerInterface $logger,
    ) {}

    public function verify(string $pdfPath, ComplianceFlavour $flavour): bool
    {
        $ran = false;

        foreach ($this->validators as $validator) {
            if (!$validator->isAvailable()) {
                $this->logger->info('Validator absent; skipped.', ['tool' => $validator->toolIdentifier()]);
                continue;
            }

            $ran = true;

            if (!$validator->validate($pdfPath, $flavour)->isCompliant()) {
                $this->logger->error('Conformance failed.', ['tool' => $validator->toolIdentifier()]);

                return false;
            }
        }

        // No validator available is not a pass — surface it.
        return $ran;
    }
}

Casos extremos & pegadinhas

• Um validador indisponível retorna isAvailable() === false e não lança exceção. “Nenhum validador disponível” não é uma aprovação; trate isso como um estado separado, como no exemplo de produção.
• Os adaptadores executam binários externos. O veredito deles é o veredito normalizado da ferramenta externa, não uma reimplementação independente. Mantenha as ferramentas atualizadas.
• O execute() do manipulador retorna um código de saída do processo. Um código diferente de zero é uma falha. Propague-o a partir do seu wrapper em vez de descartá-lo.
• BinaryFinder resolve o caminho de uma ferramenta no host. Um host diferente pode resolver uma versão diferente da ferramenta. Fixe o ambiente para uma verificação reproduzível.
• O perfil de reprodutibilidade é structural: os relatórios de verificação incluem timestamps e versões das ferramentas, portanto esses campos diferem entre execuções.

Desempenho

A sobrecarga do manipulador é desprezível. Os processos dos validadores externos dominam o custo, e documentos grandes podem ser lentos. AsyncValidatorAdapter permite que você sobreponha essa latência. O performance_budget de 1500 ms de tempo de parede / 64 MB de pico é a referência do mecanismo, não um limite para um validador externo. A saída do benchmark tem uma estrutura determinística, mas necessariamente inclui dados de tempo.

Notas de segurança

Os adaptadores iniciam processos externos para um caminho de PDF. Trate o PDF como entrada não confiável e execute a verificação em um ambiente restrito. Os validadores externos analisam dados hostis. Valide e canonicalize qualquer caminho de arquivo antes de passá-lo a um manipulador, para que o path traversal não possa alcançar um arquivo inesperado. Não passe entradas de usuário sem sanitização como argumentos de comando. Os adaptadores constroem argumentos de processo, não strings de shell. O próprio arquivo de entrada permanece controlado pelo atacante. Consulte o modelo de ameaças do mecanismo em /modules/core/security/.

Conformidade

Este módulo não faz nenhuma alegação normativa da especificação do PDF por conta própria. Ele orquestra a verificação de conformidade delegando a validadores de referência: o veraPDF para PDF/A e PDF/UA, e o modelo Arlington PDF para as regras estruturais da ISO 32000-2. A ferramenta externa fornece o veredito autoritativo de conformidade. Este módulo normaliza e reporta esse veredito. A conformidade de ponta a ponta e as baselines golden estão descritas em /modules/core/conformance/.

Veja também

• Módulo Inspect — introspecção programática exposta por meio da CLI.
• Visão geral de conformidade — o modelo de verificação e as suítes golden.
• Módulo Compliance — os perfis ComplianceFlavour verificados pelos validadores.
• Modelo de segurança do mecanismo