Cli: gestores de comandos y adaptadores para validadores externos

De un vistazo

El módulo Cli proporciona la superficie de comandos que respalda las herramientas de diagnóstico y conformidad del motor. Reúne gestores de comandos: benchmark, diff, init, verify y capabilities. También incluye adaptadores que encapsulan validadores de PDF externos (veraPDF, el modelo Arlington PDF) detrás de una interfaz única. Un único comando verify puede ejecutar cualquiera de ellos.

Instalación

composer require nextpdf/core:^3

Visión general conceptual

Cada comando se implementa como una clase gestora con un execute() que devuelve un código de salida del proceso. BenchmarkHandler ejecuta los escenarios de evaluación comparativa. DiffHandler compara documentos. InitHandler genera la estructura inicial de un proyecto. VerifyHandler ejecuta la verificación de conformidad. CapabilitiesHandler informa de lo que admite el entorno de ejecución. CliOutput es el escritor ligero de stdout/stderr que comparten los gestores, para que la salida pueda verificarse en pruebas y no quede acoplada a variables globales. BinaryFinder resuelve la ruta de una herramienta externa en el host (@since 2.5.0).

El punto arquitectónico clave es la superficie de validación. AlternateValidatorAdapter es la interfaz que implementa un validador externo. validate() recibe una ruta de PDF y un ComplianceFlavour y devuelve un ComplianceValidationResult. isAvailable() indica si la herramienta subyacente está instalada. toolIdentifier() devuelve su nombre. VeraPdfCliAdapter, ArlingtonValidatorAdapter y AsyncValidatorAdapter implementan esa interfaz. Esto significa que el motor no reimplementa los validadores de terceros. Ejecuta las herramientas de referencia y normaliza su veredicto. Un validador no instalado informa de isAvailable() === false en lugar de hacer fallar la ejecución, de modo que la verificación se degrada de forma explícita. Los adaptadores son @since 3.0.0; los gestores del núcleo son @since 2.3.0–@since 2.5.0.

Superficie de la API

Clase	Miembros clave	Función
BenchmarkHandler	execute(string $format = 'pretty', ?string $scenario = null): int	Ejecuta escenarios de evaluación comparativa (@since 2.4.0)
VerifyHandler	execute(): int	Ejecuta la verificación de conformidad
DiffHandler / InitHandler	execute(): int	Diff de documentos / estructura inicial del proyecto
CapabilitiesHandler	execute(string $format = 'pretty'): int	Informa de las capacidades del entorno de ejecución (@since 2.3.0)
AlternateValidatorAdapter (interfaz)	validate(), isAvailable(), toolIdentifier()	Contrato de validador externo (@since 3.0.0)
VeraPdfCliAdapter	implementa el adaptador	Envuelve la CLI de veraPDF (@since 3.0.0)
ArlingtonValidatorAdapter	implementa el adaptador	Envuelve el modelo Arlington PDF (@since 3.0.0)
AsyncValidatorAdapter	implementa el adaptador	Envoltorio de validador con capacidad asíncrona (@since 3.0.0)
CliOutput	write(), writeln(), error()	Escritor de stdout/stderr verificable en pruebas (@since 2.3.0)
BinaryFinder	resolución de rutas de herramientas externas	Localiza herramientas en el host (@since 2.5.0)

Ejecutar composer docs:generate-api-php -- --module=Cli para obtener la tabla completa de PHPDoc.

Ejemplo de código — Inicio rápido

Fuente: examples/33-validate-conformance.php. Selección de un adaptador de validador y comprobación de su disponibilidad antes de utilizarlo:

<?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";

Ejemplo de código — Producción

Ejecutar la verificación a través de los validadores que estén presentes y tratar una herramienta ausente como una comprobación omitida en lugar de un fallo.

<?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 límite y trampas

• Un validador no disponible devuelve isAvailable() === false. No lanza una excepción. «Ningún validador disponible» no es una aprobación: hay que tratarlo como un caso diferenciado, como hace el ejemplo de producción.
• Los adaptadores ejecutan binarios externos. Su veredicto es el veredicto de la herramienta externa, normalizado, no una reimplementación independiente. Mantener las herramientas actualizadas.
• El execute() del gestor devuelve un código de salida del proceso. Un valor distinto de cero es un fallo. Propagarlo desde el envoltorio en lugar de descartarlo.
• BinaryFinder resuelve la ruta de una herramienta en el host. Un host diferente puede resolver una versión diferente de la herramienta. Fijar el entorno para una verificación reproducible.
• El perfil de reproducibilidad es structural: un informe de verificación incluye marcas de tiempo y versiones de las herramientas, por lo que dos ejecuciones difieren en esos campos.

Rendimiento

La sobrecarga del gestor es insignificante. El coste viene dominado por el proceso del validador externo, que puede ser lento en documentos grandes. AsyncValidatorAdapter existe para permitir el solapamiento de esa latencia. El performance_budget de 1500 ms de tiempo de reloj / 64 MB de pico es la referencia del motor, no un límite para un validador externo. La salida de la evaluación comparativa es determinista en su estructura, pero, por su naturaleza, incluye datos de temporización.

Notas de seguridad

Los adaptadores ejecutan procesos externos sobre una ruta de PDF. Tratar el PDF como entrada no confiable. Ejecutar la verificación en un entorno restringido. Los validadores externos analizan datos hostiles. Validar y canonizar cualquier ruta de archivo antes de pasarla a un gestor para evitar un cruce de rutas hacia un archivo no previsto. No pasar entrada de usuario sin sanear como argumentos de comando. Los adaptadores construyen argumentos de proceso, no cadenas de shell. El propio archivo de entrada sigue estando bajo el control del atacante. Consultar el modelo de amenazas del motor en /modules/core/security/.

Conformidad

Este módulo no formula ninguna exigencia normativa propia de la especificación PDF. Orquesta la verificación de conformidad delegando en validadores de referencia (veraPDF para PDF/A y PDF/UA, el modelo Arlington PDF para las reglas estructurales de ISO 32000-2). El veredicto de conformidad que tiene autoridad es el de la herramienta externa. Este módulo lo normaliza y lo comunica. La conformidad de extremo a extremo y las líneas base de referencia se describen en /modules/core/conformance/.

Véase también

• Módulo Inspect: la introspección programática que la CLI también expone.
• Visión general de la conformidad: el modelo de verificación y las suites de referencia.
• Módulo Compliance: los perfiles de ComplianceFlavour que los validadores comprueban.
• Modelo de seguridad del motor