CLI: commandhandlers en adapters voor externe validators

In het kort

De command-line interface (CLI)-module biedt de commando-interface van de engine voor diagnostiek en conformiteit. De module bevat handlers voor de commando’s benchmark, diff, init, verify en capabilities, plus adapters die externe Portable Document Format (PDF)-validators, waaronder veraPDF en het Arlington PDF model, achter één interface verpakken. Eén verify-commando kan elke adapter uitvoeren.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

Elk commando gebruikt een handlerklasse waarvan de methode execute() een proces-exitcode retourneert. BenchmarkHandler voert benchmarkscenario’s uit. DiffHandler vergelijkt documenten. InitHandler genereert de basisstructuur van een project. VerifyHandler voert conformiteitsverificatie uit. CapabilitiesHandler rapporteert de runtime-ondersteuning. CliOutput is de lichtgewicht stdout/stderr-writer die de handlers delen, zodat de uitvoer testbaar blijft in plaats van gekoppeld te zijn aan globals. BinaryFinder bepaalt het pad naar een extern hulpprogramma op de host (@since 2.5.0).

Het validatie-oppervlak is de centrale architecturale grens. AlternateValidatorAdapter is de interface die een externe validator implementeert. validate() neemt een PDF-pad en een ComplianceFlavour en retourneert een ComplianceValidationResult. isAvailable() rapporteert of het onderliggende hulpprogramma is geïnstalleerd. toolIdentifier() benoemt het hulpprogramma. VeraPdfCliAdapter, ArlingtonValidatorAdapter en AsyncValidatorAdapter implementeren deze interface. De engine implementeert validators van derden niet opnieuw. De engine voert de referentiehulpprogramma’s uit en normaliseert hun oordeel. Een validator die niet is geïnstalleerd, rapporteert isAvailable() === false in plaats van de run te laten mislukken, zodat de verificatie het ontbrekende hulpprogramma expliciet vastlegt. De adapters zijn @since 3.0.0; de core-handlers zijn @since 2.3.0–@since 2.5.0.

API-oppervlak

Klasse	Belangrijkste members	Rol
BenchmarkHandler	execute(string $format = 'pretty', ?string $scenario = null): int	Voert benchmarkscenario’s uit (@since 2.4.0)
VerifyHandler	execute(): int	Stuurt de conformiteitsverificatie aan
DiffHandler / InitHandler	execute(): int	Documentvergelijking / projectscaffolding
CapabilitiesHandler	execute(string $format = 'pretty'): int	Rapporteert de runtime-mogelijkheden (@since 2.3.0)
AlternateValidatorAdapter (interface)	validate(), isAvailable(), toolIdentifier()	Contract voor externe validators (@since 3.0.0)
VeraPdfCliAdapter	implementeert de adapter	Verpakt de veraPDF CLI (@since 3.0.0)
ArlingtonValidatorAdapter	implementeert de adapter	Verpakt het Arlington PDF model (@since 3.0.0)
AsyncValidatorAdapter	implementeert de adapter	Async-geschikte validator-wrapper (@since 3.0.0)
CliOutput	write(), writeln(), error()	Testbare stdout/stderr-writer (@since 2.3.0)
BinaryFinder	padresolutie voor externe hulpprogramma’s	Vindt hulpprogramma’s op de host (@since 2.5.0)

Voor de volledige PHPDoc-tabel voer je composer docs:generate-api-php -- --module=Cli uit.

Codevoorbeeld — Snelstart

Bron: examples/33-validate-conformance.php. Selecteer een validator-adapter en controleer de beschikbaarheid voordat je die gebruikt:

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

Codevoorbeeld — Productie

Voer de verificatie uit via de validators die aanwezig zijn. Behandel een ontbrekend hulpprogramma als een overgeslagen controle, niet als een fout.

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

Randgevallen en valkuilen

• Een niet-beschikbare validator retourneert isAvailable() === false en gooit geen uitzondering. „Geen validator beschikbaar” is geen geslaagde controle; behandel dit als een afzonderlijke toestand, zoals het productievoorbeeld doet.
• De adapters voeren externe binaries uit. Hun oordeel is het genormaliseerde oordeel van het externe hulpprogramma, geen onafhankelijke herimplementatie. Houd de hulpprogramma’s up-to-date.
• De execute() van een handler retourneert een proces-exitcode. Een code die niet nul is, betekent een fout. Geef die door vanuit je wrapper in plaats van die te negeren.
• BinaryFinder bepaalt het pad naar een hulpprogramma op de host. Een andere host kan een andere versie van het hulpprogramma vinden. Leg de omgeving vast voor reproduceerbare verificatie.
• Het reproduceerbaarheidsprofiel is structural: rapporten op verificatieniveau bevatten tijdstempels en versies van hulpprogramma’s, waardoor die velden per run verschillen.

Prestaties

De overhead van de handlers is verwaarloosbaar. De processen van externe validators bepalen het grootste deel van de kosten, en grote documenten kunnen traag zijn. Met AsyncValidatorAdapter kun je die latentie overlappen. De performance_budget van 1500 ms wall / 64 MB piek is de engine-referentie, geen limiet voor een externe validator. Benchmarkuitvoer heeft een deterministische structuur, maar bevat noodzakelijkerwijs timinggegevens.

Beveiligingsnotities

De adapters starten externe processen voor een PDF-pad. Behandel de PDF als niet-vertrouwde invoer en voer de verificatie uit in een afgeschermde omgeving. Externe validators verwerken vijandige gegevens. Valideer en canonicaliseer elk bestandspad voordat je het aan een handler doorgeeft, zodat path traversal geen onbedoeld bestand kan bereiken. Geef geen niet-opgeschoonde gebruikersinvoer door als commandoargumenten. De adapters bouwen procesargumenten op, geen shell-strings. Het invoerbestand zelf blijft onder controle van een aanvaller. Zie het dreigingsmodel van de engine in /modules/core/security/.

Conformiteit

Deze module doet zelf geen normatieve uitspraak over de PDF-specificatie. De module orkestreert de conformiteitsverificatie door deze te delegeren aan referentievalidators: veraPDF voor PDF/A en PDF/UA, en het Arlington PDF model voor de structurele regels van ISO 32000-2. Het externe hulpprogramma levert het gezaghebbende conformiteitsoordeel. Deze module normaliseert dat oordeel en rapporteert het. End-to-end-conformiteit en de golden baselines worden beschreven in /modules/core/conformance/.

Zie ook

• Inspect-module — programmatische introspectie die via de CLI wordt aangeboden.
• Conformiteitsoverzicht — het verificatiemodel en de golden suites.
• Compliance-module — de ComplianceFlavour-profielen die door de validators worden gecontroleerd.
• Beveiligingsmodel van de engine