Walidacja zgodności: wewnątrzprocesowa kontrola wstępna i zewnętrzna wyrocznia

W skrócie

Użyj tego przepisu, aby uruchomić napisane w czystym PHP wewnątrzprocesowe walidatory zgodności NextPDF jako szybką kontrolę wstępną struktury, a następnie powierzyć miarodajną decyzję o zgodności niezależnemu walidatorowi. Kontrole wewnątrzprocesowe są konieczne, ale niewystarczające: czysty wynik jest faktem strukturalnym, a nie werdyktem zgodności. Przepis wykorzystuje plik examples/33-validate-conformance.php oraz powiązany zestaw testowy tests/Cookbook/Php/ValidateConformanceRecipeTest.php.

Instalacja

composer require nextpdf/core:^3

Walidatory wewnątrzprocesowe nie wymagają żadnych zewnętrznych narzędzi. Na etapie miarodajnej bramki potrzebny jest zewnętrzny walidator dostępny w zmiennej PATH. W przykładzie użyto veraPDF. Nie potrzebujesz pakietu Pro ani Enterprise.

Przegląd koncepcyjny

NextPDF udostępnia walidatory wewnątrzprocesowe w przestrzeni \NextPDF\Compliance\Validator. Weryfikują one określone niezmienniki normatywne bez uruchamiania zewnętrznego procesu:

• PdfRValidator — sprawdza strumień bajtów według ISO 23504-1 (PDF/R-1) §5/§6: listę dozwolonych nagłówków pliku, obiekty generacji 0, listę dozwolonych operatorów treści strony z §6.5.7 (tylko q/Q/cm/Do) oraz listę dozwolonych kluczy słownika Info z §6.4.3. Zwraca płaską tablicę PdfRValidationFinding[]; pusta lista oznacza, że każda kontrola §6 objęta bramką zakończyła się powodzeniem.
• ArlingtonValidator — uruchamia czytelną maszynowo gramatykę Arlington opracowaną przez PDF Association w trybie tylko do raportowania. Nigdy nie blokuje budowania i przy każdym ustaleniu zapisuje przypiętą sumę SHA commitu gramatyki, aby odbiorcy audytu mogli skorelować je ze znanym snapshotem źródłowym.

Te kontrole mają celowo ograniczony zakres. Wychwytują rozbieżności między kontraktem emisji a specyfikacją, ale nie rozstrzygają o zgodności z normą ISO w przypadku profilu takiego jak PDF/A-4 lub PDF/UA-2. Tego rozstrzygnięcia dokonuje niezależny walidator, a jego werdykt stanowi bramkę budowania (ISO 19005-4 §6.7.3 stwierdza to wprost dla PDF/A). Przepis zachowuje wyraźną granicę: uruchamia kontrolę wstępną wewnątrz procesu, a następnie wypisuje i uruchamia polecenie zewnętrznej wyroczni, które rozstrzyga.

Poniższy diagram przedstawia dwuetapową bramkę. W przepływie obowiązuje jedna zasada: jako zgodność można raportować wyłącznie werdykt zewnętrznej wyroczni.

Diagram

Powierzchnia API

Powierzchnia API jest generowana z PHPDoc. Użyj tych głównych punktów wejścia:

• \NextPDF\Compliance\Validator\PdfRValidator::validate(string $pdfBytes): list<PdfRValidationFinding>
• \NextPDF\Compliance\Validator\PdfRValidationFinding (readonly: clause, severity, message)
• \NextPDF\Compliance\Validator\ArlingtonValidator::validateReportOnly(string $pdfPath): list<ArlingtonFinding>
• \NextPDF\Core\Document::output(?string $filename, OutputDestination $dest): string (OutputDestination::String dla surowych bajtów)

Przykład kodu — szybki start

<?php

declare(strict_types=1);

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

use NextPDF\Compliance\Validator\PdfRValidator;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'Document under conformance review.', newLine: true);

$bytes = $doc->output(dest: OutputDestination::String);

$findings = (new PdfRValidator())->validate($bytes);

// A finding list is a structural fact, not a conformance verdict.
echo $findings === []
    ? "No in-process PDF/R-1 findings (necessary, not sufficient).\n"
    : count($findings) . " in-process finding(s); not a conformance verdict.\n";

Przykład kodu — produkcja

W środowisku produkcyjnym traktuj walidator wewnątrzprocesowy jako tanią bramkę, która szybko odrzuca oczywiste rozbieżności strukturalne. Następnie uruchom zewnętrzną wyrocznię, aby uzyskać miarodajną decyzję o zgodności. Jako zgodność raportuj wyłącznie werdykt wyroczni.

examples/33-validate-conformance.php (gate core)

$bytes = $doc->output(dest: OutputDestination::String);
$doc->save($out);

// 1. In-process pre-check — necessary, not sufficient.
$findings = (new PdfRValidator())->validate($bytes);
foreach ($findings as $finding) {
    fwrite(STDERR, sprintf("[%s] §%s — %s\n",
        $finding->severity, $finding->clause, $finding->message));
}

// 2. The authoritative gate — the external validator decides.
$exitCode = 0;
$report = [];
exec('verapdf --flavour 4 ' . escapeshellarg($out), $report, $exitCode);

if ($exitCode !== 0) {
    fwrite(STDERR, "veraPDF FAILED — not reported conforming\n");
    fwrite(STDERR, implode("\n", $report) . "\n");
    exit(1);
}

echo "veraPDF PASS — the validator reports the file conforming\n";

Uruchom przykład poleceniem php examples/33-validate-conformance.php. Tworzy on zwykły plik PDF i wypisuje ustalenia z kontroli wewnątrzprocesowej. Zwykły plik PDF zgodnie z założeniem generuje ustalenia PDF/R-1; ten rezultat stanowi istotę przykładu. Następnie przykład wypisuje miarodajne polecenie zewnętrznej wyroczni.

Przypadki brzegowe i pułapki

• Konieczne, ale niewystarczające. Pusta lista ustaleń PdfRValidator oznacza, że kontrole §6 objęte bramką zakończyły się powodzeniem — nic więcej. Nie jest to deklaracja zgodności z PDF/A-4 ani PDF/UA-2. Nigdy nie raportuj zgodności na podstawie samego wyniku kontroli wewnątrzprocesowej.
• Zwykły plik PDF z założenia nie przechodzi PDF/R-1. PDF/R-1 to profil rastrowy zawierający wyłącznie obrazy; zwykły tekstowy plik PDF zgodnie z oczekiwaniami generuje ustalenia §6.5.7 oraz §6.4.3. Przykład pokazuje to celowo, aby podkreślić tę zasadę: wynik kontroli wewnątrzprocesowej jest faktem strukturalnym, a nie werdyktem.
• Arlington działa tylko do raportowania. ArlingtonValidator::validateReportOnly() nigdy nie zgłasza wyjątku ani nie blokuje. W trybie samej gramatyki emituje jedno ustalenie info potwierdzające wczytanie przypiętej sumy SHA gramatyki; zwraca pustą listę, gdy gramatyka nie została zmaterializowana. Nie opieraj na nim bramki pass/fail — to artefakt kontroli krzyżowej.
• Bajty kontra plik. PdfRValidator::validate() przyjmuje surowy ciąg bajtów (OutputDestination::String); zewnętrzna wyrocznia wymaga ścieżki do pliku. Zapisz plik za pomocą save() na potrzeby kroku z wyrocznią.
• Puste dane wejściowe. Przekazanie pustego ciągu lub ciągu bez nagłówka do PdfRValidator::validate() zwraca ustalenie błędu §6.2.2 zamiast zgłaszać wyjątek. Sprawdź listę ustaleń; nie zakładaj wyjątku.

Wydajność

Walidatory wewnątrzprocesowe wykorzystują jednoprzebiegowe wyrażenia regularne oraz skanowanie bajtów pliku PDF. Są szybkie, zużywają mało pamięci dla typowych dokumentów i mieszczą się w budżecie 2000 ms / 128 MB. Jeśli jest używana, zewnętrzna wyrocznia dominuje pod względem czasu wykonania, ale działa poza procesem. Obowiązuje semantyczny profil odtwarzalności. Wartość przykładu tkwi w jego obserwowalnym zachowaniu walidacyjnym, a zestaw testowy sprawdza to zachowanie poprzez porównanie strukturalnego abstrakcyjnego drzewa składniowego (AST) wraz z metadanymi.

Uwagi dotyczące bezpieczeństwa

Rezydencja danych i ograniczanie ryzyka związanego z PII

Walidatory odczytują bajty dokumentu wewnątrz procesu i żadne dane nie opuszczają procesu. Zewnętrzna wyrocznia otrzymuje jednak plik. Jeśli korzystasz z walidatora hostowanego, treść dokumentu opuszcza twoją granicę. W przypadku treści wrażliwych wybierz lokalny plik wykonywalny walidatora lub usuń z dokumentu dane wrażliwe przed walidacją.

Bezpieczna telemetria i czyszczenie logów

Ustalenia mogą cytować ścieżki obiektów oraz fragmenty operatorów. Przykład zapisuje ustalenia do STDERR, a stały wiersz postępu do STDOUT. W przypadku dokumentów wrażliwych nie umieszczaj logów ustaleń we współdzielonych lokalizacjach docelowych. Nigdy nie loguj surowych bajtów pliku PDF.

Model zagrożeń

Czysty wynik kontroli wewnątrzprocesowej nie jest sygnałem integralności ani autentyczności. Wrogi producent może spreparować plik, który przejdzie ograniczone kontrole wewnątrzprocesowe, lecz nie przejdzie pełnej walidacji, albo który jest poprawnie sformowany, ale wprowadza w błąd. Traktuj pomyślną kontrolę wewnątrzprocesową jako szybki filtr, nigdy jako podstawę zaufania.

Zachowanie w trybie FIPS

Ten przepis nie wykonuje żadnej operacji kryptograficznej. Tryb Federal Information Processing Standards (FIPS) nie zmienia jego zachowania. Nie zachodzi tu żadne podpisywanie, szyfrowanie ani obliczanie skrótu materiału zaufania.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula	reference_id
Treść strony PDF/R-1 używa wyłącznie listy dozwolonych operatorów q/Q/cm/Do.	ISO 23504-1	§6.5.7
Strony PDF/R-1 zawierają wyłącznie rastrową treść obrazową.	ISO 23504-1	§6.5.5
PDF/R-1 ogranicza klucze słownika informacji o dokumencie.	ISO 23504-1	§6.4.4
Gramatyka Arlington jest czytelną maszynowo kontrolą krzyżową modelu obiektowego.	Arlington PDF Model	grammar
O zgodności rozstrzyga walidator, a nie producent.	ISO 19005-4	§6.7.3

Wewnątrzprocesowe walidatory NextPDF weryfikują określone niezmienniki normatywne. Wsparcie nie jest zgodnością; walidacja nie jest certyfikacją. Czysty wynik kontroli wewnątrzprocesowej nie ustala zgodności z normą ISO; tego rozstrzygnięcia dokonuje niezależny walidator (na przykład veraPDF). Użyj jego werdyktu jako bramki budowania.

Zobacz także

• Moduł Compliance
• Strona główna zgodności
• Generowanie pliku PDF/A-4
• Emisja otagowanego drzewa struktury PDF/UA-2