Zgodność: walidator PDF/R-1, gramatyka Arlington i narzędzia cyklu życia

W skrócie

Moduł NextPDF\Compliance udostępnia walidatory strumienia bajtów i kontrolę krzyżową gramatyki, które odczytują gotowy plik Portable Document Format (PDF) i raportują miejsca, w których odbiega on od kontraktu normatywnego. Gdy walidator nie zwraca żadnych ustaleń, wynik jest sprawdzony względem klauzul zaimplementowanych przez ten walidator. Nie jest to ogólny certyfikat.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Moduł składa się z trzech części.

PdfRValidator waliduje strumień bajtów kandydujący do zgodności z ISO 23504-1:2020 (PDF/R-1). Działa na surowych bajtach, a nie na wewnętrznym stanie obiektu zapisującego. Wykrywa rozbieżności między tym, co obiekt zapisujący zamierza wyemitować, a wymaganiami specyfikacji, i pełni rolę kontroli końcowej. Zaimplementowany zestaw klauzul to klaster v5.1.0: §5 komentarz identyfikujący wersję, lista dozwolonych nagłówków §6.2.2/§6.2.3, §6.2.4 zakaz generacji 0 i strumieni obiektów, lista dozwolonych operatorów strumienia treści §6.5.7 (tylko q, Q, cm, Do), lista dozwolonych kluczy obrazu XObject §6.6.1, lista dozwolonych kluczy słownika Info §6.4.3 oraz lista dozwolonych kluczy katalogu §6.3. Aktualizacje przyrostowe §6.7 oraz szyfrowanie §6.8 są jednoznacznie poza zakresem początkowego klastra i jako takie zadeklarowane w pliku claims.json. Walidator nie zatrzymuje się na pierwszym ustaleniu. Zbiera wszystkie rozbieżności w jednym przebiegu, dzięki czemu widać pełny obraz różnic.

PdfRConformancePolicy to niezmienna polityka obejmująca zalecane, ale informacyjne obszary wokół PDF/R-1. Normatywny próg §6 nigdy nie jest konfigurowalny. Polityka kontroluje wyłącznie zalecenia dotyczące limitów implementacyjnych §A.5, odradzanie wielopasmowości §6.6.1 oraz wymóg metadanych Extensible Metadata Platform (XMP) §A.6 na potrzeby późniejszej reklasyfikacji do PDF/A.

ArlingtonValidator uruchamia źródłowy model Arlington PDF organizacji PDF Association w trybie wyłącznie raportującym. W bieżącym cyklu ma charakter doradczy: validateReportOnly() nigdy nie zgłasza wyjątku. Stosuje mechanizm awaryjny obejmujący trzy tryby. Gdy plik wykonywalny referencyjnego narzędzia kontrolnego jest dostępny, analizuje ustrukturyzowane ustalenia. Gdy dostępna jest tylko przypięta gramatyka, emituje jedno ustalenie info, które potwierdza wczytanie przypiętej gramatyki. Gdy gramatyka jest niedostępna, zwraca pustą listę. Rejestr WaiverRegistry pozwala orkiestratorowi tłumić znane akceptowalne rozbieżności przy jednoczesnym zachowaniu śladu audytowego.

Zasada rzetelności jest zgodna z macierzą obsługi Cascading Style Sheets (CSS) oraz z modułem zgodności. Klauzula jest zweryfikowana tylko wtedy, gdy istnieje przechodzący test i przywołano klauzulę normatywną. Klauzula, która jest zaimplementowana, ale nie ma dedykowanej przechodzącej konfiguracji testowej, jest zadeklarowana. Klauzule poza zakresem są wskazane jednoznacznie. Nie są pozostawione w stanie niejednoznacznym. Wynik PdfRValidator bez ustaleń potwierdza wyłącznie klauzule, które sprawdza. Nie formułuje żadnego stwierdzenia dotyczącego §6.7 ani §6.8, których nie implementuje.

Powierzchnia API

Typ	Rodzaj	Kluczowe składowe
NextPDF\Compliance\Validator\PdfRValidator	final class	validate(string $pdfBytes): list<PdfRValidationFinding>
NextPDF\Compliance\Validator\PdfRValidationFinding	final readonly class	string $clause, 'error'|'warning'|'info' $severity, string $message
NextPDF\Compliance\Profile\PdfRConformancePolicy	final readonly class	__construct(bool $enforceA5ImplementationLimits = true, bool $rejectMultiStripPages = false, bool $requireXmpForA6Compatibility = false); lax(), strictArchival()
NextPDF\Compliance\Validator\ArlingtonValidator	final class	validateReportOnly(string $pdfPath): list<ArlingtonFinding>
NextPDF\Compliance\Validator\WaiverRegistry	final class	isWaived(string $validator, string $ruleId, string $scopeKey): bool

Przykład kodu — szybki start

<?php

declare(strict_types=1);

use NextPDF\Compliance\Validator\PdfRValidator;

$validator = new PdfRValidator();
$findings  = $validator->validate(file_get_contents('candidate.pdf'));

if ($findings === []) {
    // Zero divergences from the §6 clauses PdfRValidator implements.
    // This is NOT a PDF/R-1 certificate — §6.7 and §6.8 are not checked.
    echo "No PDF/R-1 §6 divergences detected (implemented clause set).\n";
} else {
    foreach ($findings as $f) {
        echo "[{$f->severity}] §{$f->clause}: {$f->message}\n";
    }
}

Przykład kodu — produkcja

<?php

declare(strict_types=1);

use NextPDF\Compliance\Validator\ArlingtonValidator;
use NextPDF\Compliance\Validator\ArlingtonGrammarLoader;
use NextPDF\Compliance\Validator\WaiverRegistry;

$validator = new ArlingtonValidator(
    waivers: new WaiverRegistry(/* loaded waiver entries */),
    grammar: new ArlingtonGrammarLoader(/* pinned submodule path */),
    adapter: null, // grammar-only mode when the reference checker is absent
);

// Advisory by contract — never throws on findings.
$findings = $validator->validateReportOnly('artifact.pdf');

foreach ($findings as $finding) {
    // Each finding pins the Arlington grammar commit SHA for provenance.
    logger()->info('arlington', [
        'rule'       => $finding->ruleId,
        'severity'   => $finding->severity,
        'grammarSha' => $finding->grammarSha,
    ]);
}

Przypadki brzegowe i pułapki

• PdfRValidator opiera się na wyrażeniach regularnych, a nie na pełnym parserze. Jest ukierunkowany na deterministyczne dane wyjściowe NextPDF\Writer\PdfRWriter. Używaj go jako detektora rozbieżności dla tego obiektu zapisującego, a nie jako ogólnego parsera PDF.
• Zero ustaleń ≠ pełna zgodność z PDF/R-1. §6.7 (aktualizacje przyrostowe) oraz §6.8 (szyfrowanie) nie są zaimplementowane w klastrze v5.1.0 i są zadeklarowane jako poza zakresem w pliku claims.json. Czysty wynik traktuj jako „brak rozbieżności w zaimplementowanym zestawie klauzul” i nic więcej.
• Arlington ma charakter doradczy. W bieżącym cyklu validateReportOnly() nigdy nie powoduje niepowodzenia kompilacji. Ciągła integracja (CI) korzysta z artefaktu, ale nie uzależnia od niego przejścia.
• Walidacja PDF/A International Color Consortium (ICC) nie znajduje się tutaj. Walidacja ICC OutputIntent §6.2.2 normy ISO 19005-4:2020 znajduje się w komponencie Enterprise PdfAManager (nextpdf/pro), a nie w module Compliance pakietu Core. Zakres PDF/A w pakiecie Core obejmuje wyłącznie dyskryminator ConformanceMode.
• Zwolnienia zachowują ślad audytowy. Reguła objęta zwolnieniem jest tłumiona na liście ustaleń, ale wpis zwolnienia pozostaje zapisem dlaczego.

Wydajność

PdfRValidator::validate() wykonuje pojedynczy liniowy przebieg z ograniczonymi przejściami wyrażeń regularnych po strumieniu bajtów. Koszt skaluje się wraz z rozmiarem dokumentu i wyraźnie mieści się w granicach budżetu modułu. W trybie wyłącznie gramatycznym ArlingtonValidator ma złożoność O(liczba reguł gramatyki) dla ustalenia potwierdzającego wczytanie. Ścieżka referencyjnego narzędzia kontrolnego działa jako podproces i jest ograniczona przez narzędzie źródłowe, a nie przez NextPDF. Jest to krok CI wykonywany poza głównym pasmem.

Uwagi dotyczące bezpieczeństwa

Te walidatory odczytują niezaufane bajty PDF. PdfRValidator usuwa literały nawiasowe oraz szesnastkowe przed ekstrakcją kluczy, dzięki czemu spreparowany łańcuch Creator nie może wstrzyknąć fałszywego klucza /Name (obsługa znaków ucieczki ISO 32000-1:2008 §7.3.4.2). Adapter Arlington uruchamia źródłowe narzędzie kontrolne jako ograniczony podproces. Przekroczenie limitu czasu lub błąd wykonania traktuje jako „brak ustaleń”, zamiast ufać częściowym danym wyjściowym. Powierzchnia ataku związana z parsowaniem PDF jest opisana w modelu zagrożeń projektu.

Zgodność

Norma	Klauzula	Co robi moduł Compliance	Status
ISO 23504-1:2020 (PDF/R-1)	§6.5.7	PdfRValidator egzekwuje listę dozwolonych operatorów strumienia treści {q,Q,cm,Do}	Zweryfikowane (przechodzą testy jednostkowe, profilu norm i integracyjne)
ISO 23504-1:2020 (PDF/R-1)	§6.4.3	PdfRValidator egzekwuje listę dozwolonych kluczy słownika Info	Zweryfikowane (poparte testami)
ISO 23504-1:2020 (PDF/R-1)	§6.7, §6.8	Nie zaimplementowano w klastrze v5.1.0	Jawny brak pokrycia (zadeklarowany w claims.json)
ISO 32000-2:2020 (PDF 2.0)	§7.5.2	Sprawdzenie listy dozwolonych kluczy katalogu	Zadeklarowane (przejście wyrażeniem regularnym; strukturalne)
ISO 19005-4:2020 (PDF/A-4)	§6.7.3	Świadomość schematu identyfikacji za pośrednictwem modułu Conformance	Odniesienie krzyżowe (zobacz /specifications/pdfa4/)

Obsługa to nie zgodność. Uruchomienie PdfRValidator, które nie zwraca żadnych ustaleń, dowodzi jedynie, że dane wejściowe nie odbiegają od klauzul §6, które ten walidator implementuje. Nie potwierdza, że plik jest plikiem zgodnym z PDF/R-1: §6.7 i §6.8 nie są sprawdzane. Kontrola krzyżowa Arlington ma charakter doradczy i nigdy nie potwierdza zgodności. Dla PDF/A-4 miarodajnym walidatorem jest veraPDF, który działa poza głównym pasmem. Wyrocznia veraPDF oraz jej opcjonalne bramkowanie są opisane w module zgodności.

Cytaty są sparafrazowane z korpusu zgodności NextPDF. Pełne 64-znakowe skróty reference_id są zapisane w nagłówku strony oraz w pliku _normative-evidence-conf.md.

Zobacz także

• Moduł Conformance — routing ConformanceMode oraz wyrocznia veraPDF
• Moduł Audit — ślad audytowy i powierzchnia poświadczeń
• Mapowanie specyfikacji PDF/A-4 — pokrycie i brak pokrycia ISO 19005-4
• Moduł Security — model zagrożeń parsowania PDF