Zgodność: kierowanie ConformanceMode i granica walidacji

W skrócie

NextPDF\Conformance to jedyny dyskryminator wskazujący modułowi zapisującemu, który kontrakt International Organization for Standardization (ISO) ma spełniać plik w formacie Portable Document Format (PDF). Biblioteka emituje struktury zdefiniowane przez ten kontrakt. Nie certyfikuje jednak — i nie może certyfikować — powstałego pliku jako zgodnego. Zgodność może potwierdzić wyłącznie zewnętrzny walidator.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Moduł Conformance udostępnia dwa publiczne typy. ConformanceMode to wyliczenie z wartością bazową, które określa docelowy kontrakt (Plain, PdfUa1, PdfUa2, PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f). ConformancePolicy to niezmienny obiekt wartości łączący tryb z niezależnymi przełącznikami rygoru.

Tryb jest jedynym źródłem prawdy dla wyjściowych bramek modułu zapisującego. Zanim to wyliczenie powstało, silnik wnioskował o tym, czy dokument został oznaczony zgodnie ze specyfikacją, na podstawie rozproszonych flag. ConformanceMode::isTagged(), isAccessibility(), isArchival(), pdfaPart(), pdfaConformanceLetter() oraz requiresPdf17() — każda z tych metod zwraca typowaną odpowiedź, którą moduł zapisujący odczytuje bezpośrednio. Dzięki temu katalog, /MarkInfo, pochodzenie nagłówka pliku oraz znaczniki pdfaid w Extensible Metadata Platform (XMP) pozostają spójne z zadeklarowanym zamiarem.

Granicę wsparcia należy traktować dosłownie. NextPDF Core emituje struktury definiowane przez te normy. ISO 19005-4:2020 §6.7.3 określa schemat identyfikacji, w którym zapisuje się, który wariant PDF/A deklaruje plik. ISO 19005-4:2020 stwierdza, że zgodność ustala się w sposób określony w jej Klauzuli 5: względem wymagań normatywnych, przez narzędzie sprawdzające, a nie przez bibliotekę generującą. ISO 14289-2:2024 §6 ujmuje zgodność jako właściwość, którą spełnia plik. Ustawienie trybu NextPDF jest niezbędnym wejściem do utworzenia zgodnego pliku. Samo w sobie nie oznacza jednak zgodności.

Obowiązuje tu ta sama dyscyplina „Zweryfikowane względem Deklarowane” co w macierzy wsparcia Cascading Style Sheets (CSS). Możliwość jest Zweryfikowana tylko wtedy, gdy ma zarówno przechodzący test lub przebieg oracle, jak i przywołaną klauzulę. Wszystko inne pozostaje tym, co biblioteka emituje: jest użyteczne, ale nie stanowi gwarancji zgodności. Zgodność dotyczy ostatecznego pliku i walidatora, a nie obietnicy biblioteki. Zweryfikuj wyjście za pomocą veraPDF (zobacz „Zgodność” poniżej).

Druga granica ma znaczenie w scenariuszach archiwalnych. Tworzenie plików PDF/A-4, w tym słownik OutputIntent, osadzony profil International Color Consortium (ICC) oraz schemat rozszerzenia XMP, zapewnia rozszerzenie nextpdf/pro, a nie Core. W instalacji obejmującej wyłącznie Core Document::enablePdfA() zgłasza InvalidConfigException, ponieważ możliwość security.pdfa nie jest zarejestrowana. Core nadal posiada dyskryminator ConformanceMode, dzięki czemu introspekcja oraz oznaczona ścieżka PDF/Universal Accessibility (PDF/UA-2) działają, ale samodzielnie nie tworzy pliku PDF/A-4.

Powierzchnia API

Typ	Rodzaj	Kluczowe składowe
NextPDF\Conformance\ConformanceMode	enum: string	Plain, PdfUa1, PdfUa2, PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f; isTagged(), isAccessibility(), isArchival(), requiresPdfUa2PageTabs(), pdfaPart(): ?int, pdfaConformanceLetter(): string, requiresPdf17(): bool
NextPDF\Conformance\ConformancePolicy	final readonly class	__construct(ConformanceMode $mode = PdfUa2, bool $strictUa2 = false, bool $rejectUnvalidatedLang = false, …); lax(), strictUa2(), withUax9IsolateSupport(), withoutAstShadowMode(), withBlackPointCompensation(), withStrictOcspProducedAtTolerance(), withAllowStaleOcsp()

ConformancePolicy egzekwuje w konstruktorze jeden niezmiennik: rygorystyczne przełączniki PDF/UA-2 mają zastosowanie tylko wtedy, gdy tryb to PdfUa2, a strictUa2 = true wymusza rejectUnvalidatedLang = true. Niespójne kombinacje zgłaszają InvalidConfigException zamiast po cichu degradować działanie.

Przykład kodu — Szybki start

<?php

declare(strict_types=1);

use NextPDF\Conformance\ConformanceMode;

$mode = ConformanceMode::PdfA4f;

// Introspect the declared contract — these drive writer-side gates.
$mode->pdfaPart();              // 4
$mode->pdfaConformanceLetter(); // 'F'
$mode->requiresPdf17();         // false (PDF/A-4 is PDF 2.0 lineage)
$mode->isArchival();            // true

Przykład kodu — Produkcja

Ścieżką dostarczaną z Core i sprawdzającą kontrakt zgodności od początku do końca jest oznaczona ścieżka PDF/UA-2. Uruchamialny przykład to examples/31-pdfua2-tagged.php. Jest on również celem oracle dla rygorystycznego profilu PDF/UA-2.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

$doc = Document::createStandalone();

// Set the tagged-PDF contract BEFORE writing content so the HTML pipeline
// wires the TaggedContentEmitter at parser-construction time.
$doc->enableTaggedPdf(lang: 'en');

$doc->setTitle('Accessible report');
// … write content …

$doc->save(__DIR__ . '/out/report-ua2.pdf');

// The library has now emitted PDF/UA-2 structures. It has NOT asserted
// conformance. Verify the file with the pinned veraPDF oracle:
//
//   php oracle/run.php pdfua.strict
//
// (Requires the veraPDF Docker image — opt-in; see "Conformance" below.)

Przypadki brzegowe i pułapki

• Tworzenie plików PDF/A-4 to funkcja Premium. W instalacji obejmującej wyłącznie Core Document::enablePdfA() zgłasza InvalidConfigException (security.pdfa niedostępne). Core posiada dyskryminator, a nie emisję OutputIntent/ICC/XMP. Zobacz /specifications/pdfa4/.
• Przypadek parasolowy a przypadki wariantowe. PdfA4 to przypadek parasolowy i raportuje puste pdfaConformanceLetter(). ISO 19005-4:2020 §6.7.3 wymaga, aby plik niezgodny ani z PDF/A-4e, ani z PDF/A-4f nie podawał żadnego pdfa:conformance. Używaj PdfA4e / PdfA4f tylko dla wariantów Aneksu B / Aneksu A.
• Rygorystyczny tryb PDF/UA-2 jest opcjonalny. ConformancePolicy::lax() to domyślne ustawienie zachowujące zgodność wsteczną. strictUa2() wymusza /MarkInfo /Marked true oraz odrzucenie Best Current Practice (BCP) 47. Włączenie go w trybie innym niż PdfUa2 zgłasza wyjątek.
• isTagged() uwzględnia warianty. Plain, PdfA2, PdfA3b oraz PdfA4e raportują brak oznaczenia. Moduł zapisujący nie może wnioskować o drzewie struktury wyłącznie na podstawie trybu archiwalnego.
• Przechodzący tryb nie oznacza przechodzącego pliku. Ustawienie PdfA4 nie sprawia, że wyjście staje się prawidłowym plikiem PDF/A-4. Uruchom walidator.

Wydajność

ConformanceMode oraz ConformancePolicy to czyste typy wartości. Rozstrzyganie przypadku wyliczenia oraz rozgałęzienie match działają w czasie O(1), bez alokacji wykraczającej poza niezmienny obiekt polityki. Nie dodają mierzalnego kosztu do ścieżki zapisu. To moduł zapisujący, a nie dyskryminator, dominuje w budżecie modułu (wall_ms: 1500). Oracle veraPDF to krok ciągłej integracji (CI) poza główną ścieżką, a nie część generowania dokumentu.

Uwagi dotyczące bezpieczeństwa

Rygorystyczne przełączniki w ConformancePolicy bramkują zachowania bezpieczeństwa typu fail-closed: securityPkiRfc5280Strict (walidacja ścieżki Request for Comments (RFC) 5280 §6), strictOcspProducedAtTolerance (okno odchylenia RFC 6960 §4.2.2.1) oraz allowStaleOcsp (domyślnie false; odrzucanie odpowiedzi Open Certification Status Protocol (OCSP) pozbawionych nextUpdate). Te domyślne ustawienia są zachowawcze i przejdą w tryb rygorystyczny w przyszłej wersji głównej, zgodnie z udokumentowaną strategią zgodności wstecznej. Zobacz moduł bezpieczeństwa oraz model zagrożeń projektu, aby poznać szczegóły ścieżki podpisu.

Zgodność

NextPDF nie certyfikuje zgodności. Emituje struktury zdefiniowane przez normy wymienione poniżej. O tym, czy plik jest zgodny, rozstrzyga osobny walidator.

Norma	Klauzula	Co robi NextPDF Core	Status
ISO 14289-2:2024 (PDF/UA-2)	§6	Emituje drzewo struktury, /MarkInfo /Marked true (w trybie rygorystycznym), /Lang, XMP pdfuaid przez oznaczoną ścieżkę Core	Zweryfikowany profil: pdfua.strict zwalidowany przez oracle veraPDF (php oracle/run.php pdfua.strict), gdy dostępny jest plik binarny veraPDF (bramka opcjonalna)
ISO 19005-4:2020 (PDF/A-4)	§6.7.3	Emituje dyskryminator pdfaid:part / pdfa:conformance przez ConformanceMode	Deklarowane (emisja dyskryminatora, testowana jednostkowo); tworzenie plików PDF/A-4 jest dostępne wyłącznie w wersji Premium
ISO 32000-2:2020 (PDF 2.0)	§7.5.2	Bazowa struktura catalog/document	Deklarowane (zachowanie silnika bazowego)

Wsparcie to nie zgodność. NextPDF Core emituje struktury identyfikacyjne PDF/UA-2 i PDF/A-4, a dowód implementacyjny znajduje się w tests/Unit/Conformance/. Tylko walidator uruchamiający odpowiedni profil może orzec, że plik jest zgodny z PDF/A-4 lub PDF/UA-2. Zgodnie z ISO 19005-4:2020 Klauzula 5, ustalenie zgodności jest zadaniem walidatora, a nie biblioteki generującej.

Bramkowanie veraPDF jasno komunikuje swoje wymaganie. Oracle (oracle/run.php, oracle/lib/OracleRunner.php) wywołuje przypięty obraz Docker veraPDF. Gdy Docker lub obraz jest nieobecny, narzędzie uruchamiające kończy działanie z kodem 2 (awaria infrastruktury) i niczego nie weryfikuje. Profil pdfua.strict jest zatem opcjonalną bramką zgodności. Potwierdza zgodność tylko na maszynach, na których dostępny jest plik binarny veraPDF. NextPDF nie dostarcza żadnego wbudowanego walidatora i przy jego braku nie deklaruje zgodności.

Cytaty są parafrazowane z korpusu zgodności NextPDF. Pełne, 64-znakowe skróty reference_id zapisano we frontmatterze strony oraz w _normative-evidence-conf.md.

Zobacz także

• Moduł Compliance — walidator PDF/R-1, gramatyka Arlington oraz narzędzia cyklu życia
• Moduł Accessibility — emiter oznaczonej treści PDF/UA-2
• Mapowanie specyfikacji PDF/A-4 — pokrycie funkcji ISO 19005-4 oraz jawny brak pokrycia
• Mapowanie specyfikacji PDF/UA-2 — mapowanie dostępności ISO 14289-2
• Moduł Security — rygorystyczne przełączniki ścieżki podpisu