Lewati ke konten
NextPDF

Konformansi: perutean ConformanceMode dan batasan validasi

Sekilas

Bagian berjudul “Sekilas”

NextPDF\Conformance adalah satu-satunya diskriminator yang memberi tahu writer kontrak International Organization for Standardization (ISO) mana yang dituju oleh berkas Portable Document Format (PDF). Pustaka memancarkan struktur yang ditentukan oleh kontrak tersebut. Pustaka tidak menyatakan, dan memang tidak dapat menyatakan, bahwa berkas yang dihasilkan bersifat konforman. Hanya validator eksternal yang dapat menyatakan konformansi.

Pemasangan

Bagian berjudul “Pemasangan”
Terminal window
composer require nextpdf/core:^3

Tinjauan konseptual

Bagian berjudul “Tinjauan konseptual”

Modul Conformance mengekspos dua tipe publik. ConformanceMode adalah enum bertipe (backed enum) yang menamai kontrak sasaran (Plain, PdfUa1, PdfUa2, PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f). ConformancePolicy adalah objek nilai takubah (immutable) yang menggabungkan mode dengan sakelar ketegasan yang independen.

Mode adalah satu-satunya sumber kebenaran bagi gerbang writer di hilir. Sebelum enum ini tersedia, mesin menyimpulkan apakah suatu dokumen ditandai sesuai spesifikasi dari sejumlah flag yang tersebar. ConformanceMode::isTagged(), isAccessibility(), isArchival(), pdfaPart(), pdfaConformanceLetter(), dan requiresPdf17() masing-masing mengembalikan jawaban bertipe yang dibaca langsung oleh writer. Katalog, /MarkInfo, silsilah header berkas, dan penanda pdfaid Extensible Metadata Platform (XMP) tetap selaras dengan intent yang dideklarasikan.

Pahami batas dukungan ini secara harfiah. NextPDF Core memancarkan struktur yang ditentukan standar-standar ini. ISO 19005-4:2020 §6.7.3 menetapkan skema identifikasi yang mencatat varian PDF/A mana yang diklaim sebuah berkas. ISO 19005-4:2020 menyatakan bahwa konformansi ditentukan, sebagaimana dirinci dalam Klausa 5-nya, terhadap persyaratan normatif oleh alat pemeriksa, bukan oleh pustaka pembuat berkas. ISO 14289-2:2024 §6 membingkai kesesuaian sebagai properti yang dipenuhi oleh sebuah berkas. Menetapkan mode NextPDF merupakan masukan yang diperlukan bagi berkas yang konforman. Dengan sendirinya, pengaturan itu bukan hasil konformansi.

Ini mengikuti disiplin Verified-versus-Claimed yang sama seperti matriks dukungan Cascading Style Sheets (CSS). Suatu kapabilitas baru berstatus Verified ketika memiliki uji yang lulus atau jalur oracle, serta klausa yang dikutip. Di luar itu, yang ada adalah sesuatu yang dipancarkan pustaka: berguna, tetapi bukan jaminan konformansi. Konformansi melekat pada berkas akhir dan validator, bukan pada janji pustaka. Validasi keluaran dengan veraPDF (lihat “Konformansi” di bawah).

Batas kedua penting untuk pekerjaan pengarsipan. Penulisan PDF/A-4, termasuk kamus OutputIntent, profil International Color Consortium (ICC) tertanam, dan skema ekstensi XMP, tersedia dalam ekstensi nextpdf/pro, bukan di Core. Pada pemasangan Core-saja, Document::enablePdfA() melempar InvalidConfigException karena kapabilitas security.pdfa tidak terdaftar. Core tetap memiliki diskriminator ConformanceMode, sehingga introspeksi dan jalur bertanda (tagged) PDF/Universal Accessibility (PDF/UA-2) berfungsi, tetapi Core tidak menulis berkas PDF/A-4 dengan sendirinya.

Permukaan API

Bagian berjudul “Permukaan API”
TipeJenisAnggota utama
NextPDF\Conformance\ConformanceModeenum: stringPlain, PdfUa1, PdfUa2, PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f; isTagged(), isAccessibility(), isArchival(), requiresPdfUa2PageTabs(), pdfaPart(): ?int, pdfaConformanceLetter(): string, requiresPdf17(): bool
NextPDF\Conformance\ConformancePolicyfinal readonly class__construct(ConformanceMode $mode = PdfUa2, bool $strictUa2 = false, bool $rejectUnvalidatedLang = false, …); lax(), strictUa2(), withUax9IsolateSupport(), withoutAstShadowMode(), withBlackPointCompensation(), withStrictOcspProducedAtTolerance(), withAllowStaleOcsp()

ConformancePolicy menegakkan satu invarian dalam konstruktornya: sakelar ketat PDF/UA-2 hanya berlaku ketika modenya PdfUa2, dan strictUa2 = true memaksa rejectUnvalidatedLang = true. Kombinasi yang tidak koheren melempar InvalidConfigException, alih-alih diturunkan secara diam-diam.

Contoh kode — Mulai cepat

Bagian berjudul “Contoh kode — Mulai cepat”
<?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

Contoh kode — Produksi

Bagian berjudul “Contoh kode — Produksi”

Jalur yang disediakan Core dan menjalankan kontrak konformansi dari ujung ke ujung adalah rute bertanda (tagged) PDF/UA-2. Contoh yang dapat dijalankan ini adalah examples/31-pdfua2-tagged.php. Contoh ini juga menjadi sasaran oracle untuk profil ketat 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.)

Kasus tepi & jebakan

Bagian berjudul “Kasus tepi & jebakan”
  • Penulisan PDF/A-4 adalah Premium. Pada pemasangan Core-saja, Document::enablePdfA() melempar InvalidConfigException (security.pdfa tidak tersedia). Core memiliki diskriminator, bukan pemancaran OutputIntent/ICC/XMP. Lihat /specifications/pdfa4/.
  • Kasus payung vs varian. PdfA4 adalah kasus payung dan melaporkan pdfaConformanceLetter() kosong. ISO 19005-4:2020 §6.7.3 mengarahkan berkas yang tidak konforman terhadap PDF/A-4e maupun PDF/A-4f untuk tidak menyediakan pdfa:conformance. Gunakan PdfA4e / PdfA4f hanya untuk varian Lampiran B / Lampiran A.
  • PDF/UA-2 ketat bersifat keikutsertaan (opt-in). ConformancePolicy::lax() adalah default yang kompatibel mundur. strictUa2() memaksa /MarkInfo /Marked true dan penolakan terhadap nilai bahasa yang tidak tervalidasi menurut Best Current Practice (BCP) 47. Mengaktifkannya pada mode non-PdfUa2 akan melempar pengecualian.
  • isTagged() sadar-varian. Plain, PdfA2, PdfA3b, dan PdfA4e melaporkan status tak bertanda (untagged). Writer tidak boleh menyimpulkan pohon struktur dari mode pengarsipan saja.
  • Mode yang lulus bukanlah berkas yang lulus. Menetapkan PdfA4 tidak membuat keluaran menjadi berkas PDF/A-4 yang valid. Jalankan validator.

Performa

Bagian berjudul “Performa”

ConformanceMode dan ConformancePolicy adalah tipe nilai murni. Resolusi kasus enum dan dispatch match bersifat O(1), tanpa alokasi di luar objek policy yang takubah. Keduanya tidak menambah biaya terukur pada jalur tulis. Writer, bukan diskriminator, yang mendominasi anggaran modul (wall_ms: 1500). Oracle veraPDF adalah langkah continuous integration (CI) di luar jalur (out-of-band), bukan bagian dari pembuatan dokumen.

Catatan keamanan

Bagian berjudul “Catatan keamanan”

Sakelar ketat pada ConformancePolicy menjadi gerbang bagi perilaku keamanan fail-closed: securityPkiRfc5280Strict (validasi jalur Request for Comments (RFC) 5280 §6), strictOcspProducedAtTolerance (jendela selisih waktu RFC 6960 §4.2.2.1), dan allowStaleOcsp (default-nya false; tolak respons Open Certification Status Protocol (OCSP) yang tidak memiliki nextUpdate). Default bawaan ini bersifat konservatif dan akan beralih menjadi ketat pada rilis mayor mendatang sesuai strategi kompatibilitas mundur yang terdokumentasi. Lihat modul keamanan dan model ancaman proyek untuk detail jalur tanda tangan.

Konformansi

Bagian berjudul “Konformansi”

NextPDF tidak menyatakan konformansi. NextPDF memancarkan struktur yang ditentukan oleh standar-standar di bawah ini. Validator terpisahlah yang memutuskan apakah sebuah berkas konforman.

StandarKlausaApa yang dilakukan NextPDF CoreStatus
ISO 14289-2:2024 (PDF/UA-2)§6Memancarkan pohon struktur, /MarkInfo /Marked true (ketat), /Lang, XMP pdfuaid melalui jalur bertanda CoreProfil terverifikasi: pdfua.strict divalidasi oleh oracle veraPDF (php oracle/run.php pdfua.strict) ketika biner veraPDF tersedia (gerbang keikutsertaan)
ISO 19005-4:2020 (PDF/A-4)§6.7.3Memancarkan diskriminator pdfaid:part / pdfa:conformance melalui ConformanceModeDiklaim (pemancaran diskriminator, telah diuji unit); penulisan berkas PDF/A-4 hanya tersedia di Premium
ISO 32000-2:2020 (PDF 2.0)§7.5.2Struktur dasar catalog/documentDiklaim (perilaku mesin dasar)

Dukungan bukanlah konformansi. NextPDF Core memancarkan struktur identifikasi PDF/UA-2 dan PDF/A-4, dengan bukti implementasi di tests/Unit/Conformance/. Hanya validator yang menjalankan profil yang sesuai yang dapat menegaskan bahwa sebuah berkas konforman terhadap PDF/A-4 atau PDF/UA-2. Sesuai ISO 19005-4:2020 Klausa 5, penentuan konformansi adalah tugas validator, bukan tugas pustaka pembuat berkas.

Penggerbangan veraPDF menyatakan persyaratannya secara jelas. Oracle (oracle/run.php, oracle/lib/OracleRunner.php) memanggil citra Docker veraPDF yang dipatok. Ketika Docker atau citra tersebut tidak ada, runner keluar dengan kode 2 (kegagalan infrastruktur) dan tidak memverifikasi apa pun. Oleh karena itu, profil pdfua.strict adalah gerbang konformansi keikutsertaan. Profil ini membuktikan konformansi hanya pada mesin yang memiliki biner veraPDF. NextPDF tidak menyertakan validator tertanam dan tidak membuat klaim konformansi tanpa ketersediaannya.

Kutipan diparafrasekan dari korpus kepatuhan NextPDF. Digest reference_id 64 karakter penuh dicatat dalam frontmatter halaman dan di _normative-evidence-conf.md.

Lihat juga

Bagian berjudul “Lihat juga”