ตรวจสอบความสอดคล้อง: การตรวจสอบเบื้องต้นในกระบวนการควบคู่กับ oracle ภายนอก

ภาพรวมแบบย่อ

ใช้สูตรนี้เพื่อรัน conformance validator แบบ pure-PHP ในกระบวนการของ NextPDF เพื่อเป็นการตรวจสอบโครงสร้างเบื้องต้นที่รวดเร็ว จากนั้นส่งการตัดสินความสอดคล้องที่มีอำนาจชี้ขาดให้ validator อิสระ การตรวจสอบในกระบวนการเป็นสิ่งจำเป็นแต่ยังไม่เพียงพอ: ผลลัพธ์ที่สะอาดเป็นข้อเท็จจริงเชิงโครงสร้าง ไม่ใช่คำตัดสินความสอดคล้อง สูตรนี้อ้างอิง examples/33-validate-conformance.php และ harness tests/Cookbook/Php/ValidateConformanceRecipeTest.php ที่เกี่ยวข้อง

การติดตั้ง

composer require nextpdf/core:^3

validator ในกระบวนการไม่ต้องใช้ toolchain ภายนอก สำหรับขั้นตอนเกตที่มีอำนาจชี้ขาด คุณต้องมี validator ภายนอกอยู่ใน PATH ตัวอย่างนี้ใช้ veraPDF คุณไม่จำเป็นต้องมีแพ็กเกจ Pro หรือ Enterprise

ภาพรวมเชิงแนวคิด

NextPDF มี validator ในกระบวนการอยู่ภายใต้ \NextPDF\Compliance\Validator validator เหล่านี้ตรวจสอบ normative invariant ที่เจาะจงโดยไม่ต้องเรียกใช้กระบวนการภายนอก:

• PdfRValidator — รันการตรวจสอบ byte-stream ตาม ISO 23504-1 (PDF/R-1) §5/§6 ได้แก่ allowlist ของ file-header, วัตถุ generation-0, allowlist ของตัวดำเนินการเนื้อหาหน้าตาม §6.5.7 (q/Q/cm/Do เท่านั้น) และ allowlist ของคีย์ Info-dict ตาม §6.4.3 โดยคืนค่า PdfRValidationFinding[] แบบแบนราบ รายการว่างหมายความว่าการตรวจสอบ §6 ที่เป็นเกตทุกข้อผ่าน
• ArlingtonValidator — รัน Arlington grammar ที่อ่านได้ด้วยเครื่องของ PDF Association ในโหมด report-only โดยไม่ใช้เป็นเกตของบิลด์ และจะบันทึก commit SHA ของ grammar ที่ปักหมุดไว้ในทุก finding เพื่อให้ผู้ใช้ข้อมูล audit เทียบกับ snapshot ต้นทางที่ทราบอยู่แล้วได้

การตรวจสอบเหล่านี้ถูกกำหนดขอบเขตไว้โดยเจตนา จะตรวจจับความคลาดเคลื่อนระหว่าง emission contract กับ spec ได้ แต่จะไม่สถาปนาความสอดคล้องตาม ISO สำหรับโปรไฟล์เช่น PDF/A-4 หรือ PDF/UA-2 validator อิสระเป็นผู้ตัดสินเรื่องนั้น และคำตัดสินของ validator คือเกตของบิลด์ (ISO 19005-4 §6.7.3 ระบุเรื่องนี้ไว้อย่างชัดเจนสำหรับ PDF/A) สูตรนี้รักษาขอบเขตให้ชัดเจน: รันการตรวจสอบเบื้องต้นในกระบวนการ จากนั้นพิมพ์และรันคำสั่ง external-oracle ที่เป็นผู้ตัดสิน

แผนภาพด้านล่างแสดงเกตแบบสองขั้นตอน โดยมีกฎหนึ่งข้อกำกับกระแสงาน: เฉพาะคำตัดสินของ external oracle เท่านั้นที่อาจรายงานเป็นความสอดคล้องได้

Diagram

พื้นผิว API

พื้นผิว API สร้างจาก PHPDoc โดยมีจุดเข้าใช้งานหลักดังนี้:

• \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 สำหรับไบต์ดิบ)

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

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

ตัวอย่างโค้ด — โปรดักชัน

ในโปรดักชัน ให้ปฏิบัติต่อ validator ในกระบวนการเป็นเกตต้นทุนต่ำที่ล้มเหลวอย่างรวดเร็วเมื่อพบความคลาดเคลื่อนเชิงโครงสร้างที่ชัดเจน จากนั้นรัน external oracle เป็นการตัดสินความสอดคล้องที่มีอำนาจชี้ขาด เฉพาะคำตัดสินของ oracle เท่านั้นที่อาจรายงานเป็นความสอดคล้องได้

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

รันตัวอย่างด้วย php examples/33-validate-conformance.php คำสั่งนี้จะสร้าง PDF ธรรมดาขึ้นมาและพิมพ์ finding ในกระบวนการ คาดว่า PDF ธรรมดาจะก่อให้เกิด PDF/R-1 finding นั่นคือประเด็นที่ตั้งใจให้เห็น จากนั้นตัวอย่างจะพิมพ์คำสั่ง external-oracle ที่มีอำนาจชี้ขาด

กรณีขอบและข้อควรระวัง

• จำเป็นแต่ไม่เพียงพอ รายการ finding ของ PdfRValidator ที่ว่างเปล่าหมายความว่าการตรวจสอบ §6 ที่เป็นเกตผ่านเท่านั้น ไม่ใช่การอ้างความสอดคล้องของ PDF/A-4 หรือ PDF/UA-2 อย่ารายงานความสอดคล้องจากผลลัพธ์ในกระบวนการเพียงอย่างเดียว
• PDF ธรรมดาไม่ผ่าน PDF/R-1 ตามการออกแบบ PDF/R-1 เป็นโปรไฟล์แรสเตอร์ที่เป็นภาพเท่านั้น PDF ที่เป็นข้อความธรรมดาจึงก่อให้เกิด finding ตาม §6.5.7 และ §6.4.3 ได้อย่างถูกต้อง ตัวอย่างนี้ตั้งใจแสดงกรณีนี้เพื่อย้ำประเด็น: ผลลัพธ์ในกระบวนการเป็นข้อเท็จจริงเชิงโครงสร้าง ไม่ใช่คำตัดสิน
• Arlington เป็นแบบ report-only ArlingtonValidator::validateReportOnly() จะไม่ throw และไม่เป็นเกต ในโหมด grammar-only จะปล่อย info finding หนึ่งรายการที่พิสูจน์ว่า grammar SHA ที่ปักหมุดไว้ถูกโหลด และจะคืนรายการว่างเมื่อ grammar ไม่ได้ถูกทำให้เป็นรูปธรรม อย่าสร้างเกต pass/fail บนสิ่งนี้ — เป็นอาร์ติแฟกต์สำหรับการตรวจสอบไขว้
• ไบต์เทียบกับไฟล์ PdfRValidator::validate() รับสตริงไบต์ดิบ (OutputDestination::String) ส่วน external oracle ต้องการพาธไฟล์ บันทึกไฟล์ด้วย save() สำหรับขั้นตอน oracle
• อินพุตว่างเปล่า การส่งสตริงว่างหรือไม่มีส่วนหัวให้แก่ PdfRValidator::validate() จะคืน finding ข้อผิดพลาด §6.2.2 แทนที่จะ throw ตรวจสอบรายการ finding อย่าสมมติว่าจะมี exception

ประสิทธิภาพ

validator ในกระบวนการใช้การสแกนด้วย regular-expression และการสแกนระดับไบต์แบบผ่านครั้งเดียวบน PDF จึงรวดเร็วและใช้การจัดสรรหน่วยความจำต่ำสำหรับเอกสารทั่วไป และอยู่ภายในงบประมาณ 2000 ms / 128 MB เมื่อมี external oracle เวลานาฬิกาส่วนใหญ่จะอยู่ที่ oracle แต่รันอยู่นอกกระบวนการ โปรไฟล์การทำซ้ำเชิงความหมาย (semantic reproducibility) มีผลบังคับใช้ จุดสำคัญของตัวอย่างนี้คือพฤติกรรมการตรวจสอบที่สังเกตได้ และ harness จะตรวจสอบพฤติกรรมนั้นผ่านการเปรียบเทียบ abstract syntax tree (AST) เชิงโครงสร้างพร้อมเมทาดาทา

หมายเหตุด้านความปลอดภัย

การเก็บข้อมูลไว้ในขอบเขตและการลดความเสี่ยง PII

validator อ่านไบต์ของเอกสารในกระบวนการ และไม่มีข้อมูลใดออกจากกระบวนการ อย่างไรก็ตาม external oracle จะได้รับไฟล์ หากคุณรัน validator แบบโฮสต์ เนื้อหาเอกสารจะออกนอกขอบเขตการควบคุมของคุณ สำหรับเนื้อหาที่ละเอียดอ่อน ควรใช้ไบนารี validator ในเครื่อง หรือเซ็นเซอร์ก่อนการตรวจสอบ

เทเลเมทรีที่ปลอดภัยและการกรองล้างบันทึก

finding อาจยกพาธวัตถุและชิ้นส่วนของตัวดำเนินการมาอ้างได้ ตัวอย่างนี้เขียน finding ไปยัง STDERR และบรรทัดความคืบหน้าคงที่ไปยัง STDOUT สำหรับเอกสารที่ละเอียดอ่อน ให้เก็บบันทึก finding ไว้นอก sink ที่ใช้ร่วมกัน อย่าบันทึกไบต์ PDF ดิบเป็นอันขาด

แบบจำลองภัยคุกคาม

ผลลัพธ์ในกระบวนการที่สะอาดไม่ใช่สัญญาณของความสมบูรณ์หรือความถูกต้องแท้จริง ผู้ผลิตที่มุ่งร้ายสามารถประดิษฐ์ไฟล์ที่ผ่านการตรวจสอบในกระบวนการที่กำหนดขอบเขตไว้แต่ไม่ผ่าน validator เต็มรูปแบบ หรือไฟล์ที่มีรูปแบบถูกต้องแต่ทำให้เข้าใจผิดได้ ให้ถือว่าการผ่านในกระบวนการเป็นตัวกรองที่รวดเร็ว อย่าถือเป็นหลักฐานของความน่าเชื่อถือเป็นอันขาด

พฤติกรรมในโหมด FIPS

สูตรนี้ไม่ดำเนินการเข้ารหัสลับใดๆ โหมด Federal Information Processing Standards (FIPS) ไม่เปลี่ยนแปลงพฤติกรรมของสูตรนี้ ไม่มีการลงนาม การเข้ารหัสลับ หรือการสรุปย่อ (digest) ของวัสดุความน่าเชื่อถือเกิดขึ้น

ความสอดคล้อง

ข้อระบุ	มาตรฐาน (Spec)	ข้อกำหนด	รหัสอ้างอิง (reference_id)
เนื้อหาหน้า PDF/R-1 ใช้เฉพาะ allowlist ตัวดำเนินการ q/Q/cm/Do เท่านั้น	ISO 23504-1	§6.5.7
หน้า PDF/R-1 เป็นเนื้อหาแรสเตอร์ที่เป็นภาพเท่านั้น	ISO 23504-1	§6.5.5
PDF/R-1 จำกัดคีย์ของพจนานุกรมข้อมูลเอกสาร	ISO 23504-1	§6.4.4
Arlington grammar คือการตรวจสอบไขว้ของ object-model ที่อ่านได้ด้วยเครื่อง	Arlington PDF Model	grammar
validator เป็นผู้ตัดสินความสอดคล้อง ไม่ใช่ผู้ผลิต	ISO 19005-4	§6.7.3

validator ในกระบวนการของ NextPDF ตรวจสอบ normative invariant ที่เจาะจง การรองรับไม่ใช่ความสอดคล้อง การตรวจสอบไม่ใช่การรับรอง ผลลัพธ์ในกระบวนการที่สะอาดไม่ได้สถาปนาความสอดคล้องตาม ISO validator อิสระ (เช่น veraPDF) เป็นผู้ตัดสินเรื่องนั้น ให้ใช้คำตัดสินของ validator เป็นเกตของบิลด์

ดูเพิ่มเติม

• โมดูล Compliance
• หน้าหลักความสอดคล้อง
• สร้างเอาต์พุต PDF/A-4
• ส่งออก structure tree ของ PDF/UA-2 ที่มี tag