CLI: procedury obsługi poleceń i adaptery zewnętrznych walidatorów

W skrócie

Moduł interfejsu wiersza poleceń (CLI) udostępnia zestaw poleceń silnika służących do diagnostyki i sprawdzania zgodności. Obejmuje procedury obsługi poleceń benchmark, diff, init, verify i capabilities oraz adaptery, które udostępniają zewnętrzne walidatory formatu Portable Document Format (PDF), w tym veraPDF i model Arlington PDF, przez jeden wspólny interfejs. Jedno polecenie verify może uruchomić dowolny adapter.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Każde polecenie jest obsługiwane przez klasę, której metoda execute() zwraca kod wyjścia procesu. BenchmarkHandler uruchamia scenariusze testów wydajności. DiffHandler porównuje dokumenty. InitHandler tworzy szkielet projektu. VerifyHandler uruchamia weryfikację zgodności. CapabilitiesHandler raportuje obsługę środowiska uruchomieniowego. CliOutput to lekka warstwa zapisu do stdout/stderr współdzielona przez procedury obsługi, dzięki czemu dane wyjściowe pozostają testowalne i nie są powiązane ze zmiennymi globalnymi. BinaryFinder wyznacza ścieżkę zewnętrznego narzędzia na hoście (@since 2.5.0).

Warstwa walidacji jest kluczową granicą architektoniczną. AlternateValidatorAdapter to interfejs implementowany przez adapter zewnętrznego walidatora. validate() przyjmuje ścieżkę do pliku PDF oraz ComplianceFlavour i zwraca ComplianceValidationResult. isAvailable() informuje, czy narzędzie bazowe jest zainstalowane. toolIdentifier() podaje jego nazwę. VeraPdfCliAdapter, ArlingtonValidatorAdapter oraz AsyncValidatorAdapter implementują ten interfejs. Silnik nie implementuje ponownie walidatorów innych firm. Uruchamia narzędzia referencyjne i normalizuje ich werdykt. Jeśli walidator nie jest zainstalowany, zwraca isAvailable() === false, zamiast przerywać uruchomienie, dzięki czemu weryfikacja jawnie odnotowuje brakujące narzędzie. Adaptery są oznaczone jako @since 3.0.0; podstawowe procedury obsługi mają @since 2.3.0–@since 2.5.0.

Powierzchnia API

Klasa	Kluczowe składowe	Rola
BenchmarkHandler	execute(string $format = 'pretty', ?string $scenario = null): int	Uruchamia scenariusze testów wydajności (@since 2.4.0)
VerifyHandler	execute(): int	Steruje weryfikacją zgodności
DiffHandler / InitHandler	execute(): int	Porównuje dokumenty / tworzy szkielet projektu
CapabilitiesHandler	execute(string $format = 'pretty'): int	Raportuje możliwości środowiska uruchomieniowego (@since 2.3.0)
AlternateValidatorAdapter (interfejs)	validate(), isAvailable(), toolIdentifier()	Kontrakt dla zewnętrznego walidatora (@since 3.0.0)
VeraPdfCliAdapter	implementuje adapter	Opakowuje interfejs CLI veraPDF (@since 3.0.0)
ArlingtonValidatorAdapter	implementuje adapter	Opakowuje model Arlington PDF (@since 3.0.0)
AsyncValidatorAdapter	implementuje adapter	Opakowuje walidator obsługujący tryb asynchroniczny (@since 3.0.0)
CliOutput	write(), writeln(), error()	Testowalna warstwa zapisu do stdout/stderr (@since 2.3.0)
BinaryFinder	ustalanie ścieżki zewnętrznego narzędzia	Lokalizuje narzędzia na hoście (@since 2.5.0)

Aby wygenerować pełną tabelę PHPDoc, uruchom composer docs:generate-api-php -- --module=Cli.

Przykład kodu — szybki start

Źródło: examples/33-validate-conformance.php. Wybierz adapter walidatora i sprawdź jego dostępność przed użyciem:

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

Przykład kodu — środowisko produkcyjne

Uruchamiaj weryfikację przy użyciu dostępnych walidatorów. Brakujące narzędzie traktuj jako pominiętą kontrolę, a nie jako niepowodzenie.

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

Przypadki brzegowe i pułapki

• Niedostępny walidator zwraca isAvailable() === false i nie zgłasza wyjątku. „Brak dostępnego walidatora” nie oznacza pozytywnego wyniku; obsłuż ten przypadek jako odrębny stan, tak jak robi to przykład produkcyjny.
• Adaptery uruchamiają zewnętrzne pliki wykonywalne. Zwracany werdykt jest znormalizowanym werdyktem zewnętrznego narzędzia, a nie wynikiem niezależnej, ponownej implementacji. Aktualizuj narzędzia na bieżąco.
• Metoda execute() w procedurze obsługi zwraca kod wyjścia procesu. Kod różny od zera oznacza niepowodzenie. Propaguj go z opakowania, zamiast odrzucać.
• BinaryFinder wyznacza ścieżkę narzędzia na hoście. Inny host może wskazać inną wersję narzędzia. Użyj stałego środowiska, aby uzyskać powtarzalną weryfikację.
• Profil powtarzalności to structural: raporty weryfikacji zawierają znaczniki czasu i wersje narzędzi, dlatego te pola różnią się między uruchomieniami.

Wydajność

Narzut procedury obsługi jest pomijalnie mały. Procesy zewnętrznych walidatorów dominują w kosztach wykonania, a duże dokumenty mogą być przetwarzane wolno. AsyncValidatorAdapter pozwala wykonywać inne operacje w czasie tego oczekiwania. Wartość performance_budget wynosząca 1500 ms czasu zegarowego / 64 MB szczytowego zużycia pamięci to wartość referencyjna silnika, a nie limit dla zewnętrznego walidatora. Wynik testu wydajności ma deterministyczną strukturę, ale z konieczności zawiera dane o czasach wykonania.

Uwagi dotyczące bezpieczeństwa

Adaptery uruchamiają zewnętrzne procesy dla ścieżki pliku PDF. Traktuj plik PDF jako niezaufane dane wejściowe i uruchamiaj weryfikację w ograniczonym środowisku. Zewnętrzne walidatory analizują wrogie dane. Sprawdzaj poprawność i kanonikalizuj każdą ścieżkę pliku przed przekazaniem jej do procedury obsługi, aby przejście przez katalogi nie umożliwiło dostępu do niezamierzonego pliku. Nie przekazuj nieoczyszczonych danych użytkownika jako argumentów poleceń. Adaptery budują argumenty procesu, a nie ciągi powłoki. Sam plik wejściowy pozostaje kontrolowany przez atakującego. Zobacz model zagrożeń silnika w /modules/core/security/.

Zgodność

Ten moduł nie formułuje własnych normatywnych deklaracji względem specyfikacji PDF. Koordynuje on weryfikację zgodności, delegując ją do walidatorów referencyjnych: veraPDF dla PDF/A i PDF/UA oraz model Arlington PDF dla reguł strukturalnych ISO 32000-2. Zewnętrzne narzędzie dostarcza miarodajny werdykt zgodności. Ten moduł normalizuje i raportuje ten werdykt. Kompleksowa zgodność oraz wzorcowe punkty odniesienia są opisane w /modules/core/conformance/.

Zobacz także

• Moduł Inspect — programowa introspekcja udostępniana przez CLI.
• Przegląd zgodności — model weryfikacji i wzorcowe zestawy testów.
• Moduł Compliance — profile ComplianceFlavour sprawdzane przez walidatory.
• Model bezpieczeństwa silnika