Cli: ตัวจัดการคำสั่งและอะแดปเตอร์สำหรับ external-validator

ภาพรวมโดยสรุป

โมดูล command-line interface (CLI) จัดเตรียมพื้นผิวคำสั่งสำหรับการวินิจฉัยและการตรวจสอบความสอดคล้องของเอนจิน โดยมีตัวจัดการสำหรับคำสั่ง benchmark, diff, init, verify และ capabilities พร้อมอะแดปเตอร์ที่ห่อหุ้มตัวตรวจสอบ Portable Document Format (PDF) ภายนอก เช่น veraPDF และโมเดล Arlington PDF ไว้หลังอินเทอร์เฟซเดียว คำสั่ง verify เพียงคำสั่งเดียวจึงเรียกใช้อะแดปเตอร์ใดก็ได้

การติดตั้ง

composer require nextpdf/core:^3

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

แต่ละคำสั่งใช้คลาสตัวจัดการ โดยเมท็อด execute() จะคืนค่ารหัสสถานะการออกของโพรเซส BenchmarkHandler เรียกใช้สถานการณ์ benchmark DiffHandler เปรียบเทียบเอกสาร InitHandler สร้างโครงร่างเริ่มต้นของโปรเจกต์ VerifyHandler เรียกใช้การตรวจสอบความสอดคล้อง และ CapabilitiesHandler รายงานการรองรับของรันไทม์ CliOutput เป็นตัวเขียน stdout/stderr แบบบางที่ตัวจัดการต่าง ๆ ใช้ร่วมกัน เพื่อให้เอาต์พุตยังคงทดสอบได้แทนที่จะผูกติดกับ globals ส่วน BinaryFinder ค้นหาและแปลงพาทของเครื่องมือภายนอกบนโฮสต์ (@since 2.5.0)

พื้นผิวการตรวจสอบความถูกต้องเป็นขอบเขตเชิงสถาปัตยกรรมที่สำคัญ AlternateValidatorAdapter คืออินเทอร์เฟซที่ตัวตรวจสอบภายนอกอิมพลีเมนต์ validate() รับพาท PDF และ ComplianceFlavour แล้วคืนค่า ComplianceValidationResult ส่วน isAvailable() รายงานว่าเครื่องมือเบื้องหลังได้รับการติดตั้งหรือไม่ และ toolIdentifier() ระบุชื่อของเครื่องมือนั้น VeraPdfCliAdapter, ArlingtonValidatorAdapter และ AsyncValidatorAdapter อิมพลีเมนต์อินเทอร์เฟซนี้ เอนจินไม่ได้อิมพลีเมนต์ตัวตรวจสอบของบุคคลที่สามขึ้นใหม่ แต่เรียกใช้เครื่องมืออ้างอิงและทำให้ผลตัดสินของเครื่องมือเหล่านั้นอยู่ในรูปแบบมาตรฐาน ตัวตรวจสอบที่ไม่ได้ติดตั้งจะรายงาน isAvailable() === false แทนที่จะทำให้การรันล้มเหลว การตรวจสอบจึงบันทึกเครื่องมือที่ขาดหายไว้อย่างชัดเจน อะแดปเตอร์เป็น @since 3.0.0 ส่วนตัวจัดการหลักอยู่ในช่วง @since 2.3.0–@since 2.5.0 ตามแต่ละตัว

พื้นผิว API

คลาส	สมาชิกสำคัญ	บทบาท
BenchmarkHandler	execute(string $format = 'pretty', ?string $scenario = null): int	เรียกใช้สถานการณ์ benchmark (@since 2.4.0)
VerifyHandler	execute(): int	ขับเคลื่อนการตรวจสอบความสอดคล้อง
DiffHandler / InitHandler	execute(): int	การเปรียบเทียบเอกสาร / การสร้างโครงร่างโปรเจกต์
CapabilitiesHandler	execute(string $format = 'pretty'): int	รายงานความสามารถของรันไทม์ (@since 2.3.0)
AlternateValidatorAdapter (อินเทอร์เฟซ)	validate(), isAvailable(), toolIdentifier()	สัญญาของ external-validator (@since 3.0.0)
VeraPdfCliAdapter	อิมพลีเมนต์อะแดปเตอร์	ห่อหุ้ม veraPDF CLI (@since 3.0.0)
ArlingtonValidatorAdapter	อิมพลีเมนต์อะแดปเตอร์	ห่อหุ้มโมเดล Arlington PDF (@since 3.0.0)
AsyncValidatorAdapter	อิมพลีเมนต์อะแดปเตอร์	ตัวห่อหุ้มตัวตรวจสอบที่รองรับการทำงานแบบ async (@since 3.0.0)
CliOutput	write(), writeln(), error()	ตัวเขียน stdout/stderr ที่ทดสอบได้ (@since 2.3.0)
BinaryFinder	การค้นหาและแปลงพาทของเครื่องมือภายนอก	ค้นหาเครื่องมือบนโฮสต์ (@since 2.5.0)

หากต้องการตาราง PHPDoc ฉบับเต็ม ให้รัน composer docs:generate-api-php -- --module=Cli ในเทอร์มินัล

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

แหล่งที่มา: examples/33-validate-conformance.php เลือกอะแดปเตอร์ตัวตรวจสอบและตรวจสอบความพร้อมใช้งานก่อนใช้งาน:

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Cli\VeraPdfCliAdapter;
use NextPDF\Compliance\ComplianceFlavour;

$validator = new VeraPdfCliAdapter(/* binary path / process factory */);

if (!$validator->isAvailable()) {
    fwrite(STDERR, "veraPDF is not installed; conformance verification skipped.\n");
    exit(2);
}

$result = $validator->validate('/srv/out/report.pdf', ComplianceFlavour::PdfA4);
echo $result->isCompliant() ? "PASS\n" : "FAIL\n";

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

รันการตรวจสอบผ่านตัวตรวจสอบใดก็ตามที่มีอยู่ และถือว่าเครื่องมือที่ไม่มีอยู่เป็นการตรวจที่ถูกข้าม ไม่ใช่ความล้มเหลว

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Cli\AlternateValidatorAdapter;
use NextPDF\Compliance\ComplianceFlavour;
use Psr\Log\LoggerInterface;

final readonly class ConformanceGate
{
    /** @param list<AlternateValidatorAdapter> $validators */
    public function __construct(
        private array $validators,
        private LoggerInterface $logger,
    ) {}

    public function verify(string $pdfPath, ComplianceFlavour $flavour): bool
    {
        $ran = false;

        foreach ($this->validators as $validator) {
            if (!$validator->isAvailable()) {
                $this->logger->info('Validator absent; skipped.', ['tool' => $validator->toolIdentifier()]);
                continue;
            }

            $ran = true;

            if (!$validator->validate($pdfPath, $flavour)->isCompliant()) {
                $this->logger->error('Conformance failed.', ['tool' => $validator->toolIdentifier()]);

                return false;
            }
        }

        // No validator available is not a pass — surface it.
        return $ran;
    }
}

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

• ตัวตรวจสอบที่ไม่พร้อมใช้งานจะคืนค่า isAvailable() === false และไม่ throw “No validator available” ไม่ได้หมายความว่าผ่าน ให้จัดการเป็นสถานะแยกต่างหากเช่นเดียวกับตัวอย่างการใช้งานจริง
• อะแดปเตอร์เรียกใช้ไบนารีภายนอก ผลตัดสินของอะแดปเตอร์คือผลตัดสินของเครื่องมือภายนอกที่ถูกทำให้อยู่ในรูปแบบมาตรฐาน ไม่ใช่การอิมพลีเมนต์ขึ้นใหม่โดยอิสระ ให้ใช้เครื่องมือเวอร์ชันปัจจุบันเสมอ
• เมท็อด execute() ของตัวจัดการคืนค่ารหัสสถานะการออกของโพรเซส รหัสที่ไม่ใช่ศูนย์คือความล้มเหลว ให้ส่งต่อรหัสนั้นจาก wrapper ของคุณแทนที่จะละทิ้ง
• BinaryFinder ค้นหาและแปลงพาทของเครื่องมือบนโฮสต์ โฮสต์ที่ต่างกันอาจค้นหาได้เวอร์ชันของเครื่องมือที่ต่างกัน ตรึงสภาพแวดล้อมไว้เพื่อให้การตรวจสอบทำซ้ำได้
• โปรไฟล์การทำซ้ำได้คือ structural: รายงานการตรวจสอบมี timestamp และเวอร์ชันของเครื่องมือ ดังนั้นฟิลด์เหล่านั้นจึงอาจต่างกันในแต่ละการรัน

ประสิทธิภาพ

โอเวอร์เฮดของตัวจัดการน้อยมากจนแทบไม่มีนัยสำคัญ โพรเซสของตัวตรวจสอบภายนอกเป็นต้นทุนหลัก และเอกสารขนาดใหญ่อาจใช้เวลานาน AsyncValidatorAdapter ช่วยให้คุณซ้อนทับเวลาแฝงดังกล่าวได้ performance_budget ที่ 1500 ms wall / 64 MB peak เป็นค่าอ้างอิงของเอนจิน ไม่ใช่ขีดจำกัดสำหรับตัวตรวจสอบภายนอก เอาต์พุตของ benchmark มีโครงสร้างที่กำหนดได้แน่นอน แต่จำเป็นต้องมีข้อมูลเวลาด้วย

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

อะแดปเตอร์เปิดโพรเซสภายนอกสำหรับพาท PDF ให้ถือว่า PDF เป็นอินพุตที่ไม่น่าเชื่อถือ และรันการตรวจสอบในสภาพแวดล้อมที่ถูกจำกัด ตัวตรวจสอบภายนอกจะแยกวิเคราะห์ข้อมูลที่อาจเป็นอันตราย ตรวจสอบความถูกต้องและทำให้พาทไฟล์ใด ๆ อยู่ในรูปแบบบัญญัติก่อนส่งให้ตัวจัดการ เพื่อป้องกันไม่ให้ path traversal เข้าถึงไฟล์ที่ไม่ได้ตั้งใจ อย่าส่งอินพุตจากผู้ใช้ที่ยังไม่ผ่านการกรองเป็นอาร์กิวเมนต์ของคำสั่ง อะแดปเตอร์สร้างอาร์กิวเมนต์ของโพรเซส ไม่ใช่สตริงเชลล์ แต่ตัวไฟล์อินพุตเองยังคงอยู่ภายใต้การควบคุมของผู้โจมตี ดูแบบจำลองภัยคุกคามของเอนจินได้ที่ /modules/core/security/ ในเอกสาร

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

โมดูลนี้ไม่ได้กล่าวอ้างเชิงบรรทัดฐานตามข้อกำหนด PDF ด้วยตนเอง แต่ จัดการประสานงาน การตรวจสอบความสอดคล้องด้วยการมอบหมายให้ตัวตรวจสอบอ้างอิง: veraPDF สำหรับ PDF/A และ PDF/UA และโมเดล Arlington PDF สำหรับกฎเชิงโครงสร้างของ ISO 32000-2 เครื่องมือภายนอกเป็นผู้ให้ผลตัดสินความสอดคล้องที่มีอำนาจชี้ขาด โมดูลนี้ทำให้ผลตัดสินนั้นอยู่ในรูปแบบมาตรฐานและรายงานออกมา ความสอดคล้องแบบครบวงจรและ golden baselines อธิบายไว้ที่ /modules/core/conformance/ ในเอกสาร

ดูเพิ่มเติม

• โมดูล Inspect — การสำรวจโครงสร้างเชิงโปรแกรมที่เปิดเผยผ่าน CLI
• ภาพรวมความสอดคล้อง — แบบจำลองการตรวจสอบและชุด golden
• โมดูล Compliance — โปรไฟล์ ComplianceFlavour ที่ตัวตรวจสอบใช้ในการตรวจ
• แบบจำลองความปลอดภัยของเอนจิน