Validasi konformitas: pra-pemeriksaan in-process dan oracle eksternal

Sekilas pandang

Gunakan resep ini untuk menjalankan validator konformitas pure-PHP in-process dari NextPDF sebagai pra-pemeriksaan struktural yang cepat, lalu serahkan keputusan konformitas yang otoritatif kepada validator independen. Pemeriksaan in-process diperlukan, tetapi belum mencukupi: hasil yang bersih adalah fakta struktural, bukan putusan konformitas. Resep ini menggunakan examples/33-validate-conformance.php bersama harness tests/Cookbook/Php/ValidateConformanceRecipeTest.php.

Instalasi

composer require nextpdf/core:^3

Validator in-process tidak membutuhkan toolchain eksternal. Untuk langkah gerbang yang otoritatif, Anda memerlukan validator eksternal pada PATH. Contoh ini menggunakan veraPDF. Anda tidak memerlukan paket Pro atau Enterprise.

Tinjauan konseptual

NextPDF menyertakan validator in-process di bawah \NextPDF\Compliance\Validator. Validator ini memverifikasi invarian normatif tertentu tanpa memulai proses eksternal:

• PdfRValidator — menjalankan pemeriksaan byte-stream ISO 23504-1 (PDF/R-1) §5/§6: allowlist header berkas, objek generation-0, allowlist operator konten halaman §6.5.7 (hanya q/Q/cm/Do), dan allowlist kunci Info-dict §6.4.3. Validator ini mengembalikan PdfRValidationFinding[] yang datar; daftar kosong berarti setiap pemeriksaan §6 yang dijadikan gerbang telah lolos.
• ArlingtonValidator — menjalankan grammar Arlington yang dapat dibaca mesin dari PDF Association dalam mode report-only. Validator ini tidak pernah menjadi gerbang build, dan mencatat SHA commit grammar yang di-pin pada setiap temuan agar konsumen audit dapat mengorelasikannya dengan snapshot upstream yang diketahui.

Cakupan pemeriksaan ini sengaja dibatasi. Pemeriksaan ini menangkap penyimpangan antara kontrak emisi dan spesifikasi, tetapi tidak menetapkan konformitas ISO untuk profil seperti PDF/A-4 atau PDF/UA-2. Validator independenlah yang menentukan hal itu, dan putusannya menjadi gerbang build (ISO 19005-4 §6.7.3 menyatakan ini secara eksplisit untuk PDF/A). Resep ini menjaga batas tersebut tetap jelas: ia menjalankan pra-pemeriksaan secara in-process, lalu mencetak dan menjalankan perintah oracle eksternal yang menentukan keputusan.

Diagram di bawah menunjukkan gerbang dua tahap. Alur ini mengikuti satu aturan: hanya putusan oracle eksternal yang boleh dilaporkan sebagai konformitas.

Diagram

Permukaan API

Permukaan API dihasilkan dari PHPDoc. Gunakan titik masuk utama berikut:

• \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 untuk byte mentah)

Contoh kode — Quick 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";

Contoh kode — Production

Dalam lingkungan produksi, perlakukan validator in-process sebagai gerbang ringan yang gagal cepat saat ada penyimpangan struktural yang jelas. Kemudian jalankan oracle eksternal sebagai sumber keputusan konformitas yang otoritatif. Hanya putusan oracle yang boleh dilaporkan sebagai konformitas.

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

Jalankan contoh dengan php examples/33-validate-conformance.php. Contoh ini membuat PDF biasa dan mencetak temuan in-process. PDF biasa memang diharapkan menghasilkan temuan PDF/R-1; justru hasil itulah inti pembelajarannya. Setelah itu, contoh mencetak perintah oracle eksternal yang otoritatif.

Kasus tepi & jebakan

• Perlu, bukan mencukupi. Daftar temuan PdfRValidator yang kosong berarti pemeriksaan §6 yang dijadikan gerbang telah lolos, tidak lebih dari itu. Itu bukan klaim konformitas PDF/A-4 atau PDF/UA-2. Jangan pernah melaporkan konformitas hanya berdasarkan hasil in-process saja.
• PDF biasa gagal PDF/R-1 sesuai desain. PDF/R-1 adalah profil raster khusus gambar; PDF teks biasa secara sah menghasilkan temuan §6.5.7 dan §6.4.3. Contoh ini sengaja menunjukkan hal tersebut untuk menegaskan poin: keluaran in-process adalah fakta struktural, bukan putusan.
• Arlington bersifat report-only. ArlingtonValidator::validateReportOnly() tidak pernah melempar eksepsi dan tidak pernah menjadi gerbang. Dalam mode grammar-only, ia menghasilkan satu temuan info yang membuktikan SHA grammar yang di-pin telah dimuat; ia mengembalikan daftar kosong ketika grammar belum dimaterialisasi. Jangan membangun gerbang lulus/gagal (pass/fail) di atasnya — ini adalah artefak untuk pemeriksaan silang.
• Byte vs. berkas. PdfRValidator::validate() menerima string byte mentah (OutputDestination::String); oracle eksternal memerlukan path berkas. Simpan berkas dengan save() untuk langkah oracle.
• Masukan kosong. Meneruskan string kosong atau string tanpa header ke PdfRValidator::validate() mengembalikan temuan error §6.2.2 alih-alih melempar eksepsi. Periksa daftar temuan; jangan menganggap eksepsi akan muncul.

Performa

Validator in-process menggunakan pemindaian regular expression dan byte sekali lintas terhadap PDF. Validator ini cepat dengan alokasi memori rendah untuk dokumen pada umumnya, dan tetap berada dalam anggaran 2000 ms / 128 MB. Jika digunakan, oracle eksternal mendominasi wall time, tetapi ia berjalan di luar proses. Profil reprodusibilitas semantik berlaku. Nilai contoh ini terletak pada perilaku validasinya yang dapat diamati, dan harness memeriksa perilaku tersebut melalui perbandingan abstract syntax tree (AST) struktural plus metadata.

Catatan keamanan

Residensi data & mitigasi PII

Validator membaca byte dokumen di dalam proses, dan tidak ada yang keluar dari proses. Namun, oracle eksternal menerima berkas tersebut. Jika Anda menjalankan validator yang di-host, konten dokumen keluar dari batas kendali Anda. Untuk konten sensitif, utamakan biner validator lokal, atau lakukan redaksi sebelum validasi.

Telemetri aman & pembersihan log

Temuan dapat mengutip path objek dan fragmen operator. Contoh ini menulis temuan ke STDERR dan satu baris progres tetap ke STDOUT. Untuk dokumen sensitif, jauhkan log temuan dari sink bersama. Jangan pernah mencatat byte mentah PDF ke log.

Model ancaman

Hasil in-process yang bersih bukanlah sinyal integritas atau keaslian. Produsen yang berniat jahat dapat merancang berkas yang lolos pemeriksaan in-process yang terbatas tetapi gagal pada validator penuh, atau yang well-formed namun menyesatkan. Perlakukan hasil lulus in-process sebagai filter cepat, jangan pernah sebagai dasar kepercayaan.

Perilaku mode FIPS

Resep ini tidak melakukan operasi kriptografi apa pun. Mode Federal Information Processing Standards (FIPS) tidak mengubah perilakunya. Tidak ada penandatanganan, enkripsi, atau digest terhadap materi kepercayaan.

Konformitas

Pernyataan	Spesifikasi	Klausul	reference_id
Konten halaman PDF/R-1 hanya menggunakan allowlist operator q/Q/cm/Do.	ISO 23504-1	§6.5.7
Halaman PDF/R-1 berisi konten raster khusus gambar.	ISO 23504-1	§6.5.5
PDF/R-1 membatasi kunci document information dictionary.	ISO 23504-1	§6.4.4
Grammar Arlington adalah pemeriksaan silang object-model yang dapat dibaca mesin.	Arlington PDF Model	grammar
Validator, bukan produsen, yang menentukan konformitas.	ISO 19005-4	§6.7.3

Validator in-process dari NextPDF memverifikasi invarian normatif tertentu. Dukungan bukanlah konformitas; validasi bukanlah sertifikasi. Hasil in-process yang bersih tidak menetapkan konformitas ISO; validator independen (misalnya veraPDF) yang menentukan hal itu. Gunakan putusannya sebagai gerbang build.

Lihat juga

• Modul Compliance
• Halaman utama konformitas
• Menghasilkan keluaran PDF/A-4
• Menghasilkan structure tree PDF/UA-2 yang ber-tag