Inspect: การตรวจสอบภายในและพรีไฟลต์ PDF

ภาพรวมโดยสังเขป

โมดูล Inspect อ่านไฟล์ Portable Document Format (PDF) ที่มีอยู่แล้วและรายงานสิ่งที่อยู่ในไฟล์นั้น ได้แก่ คะแนนความซับซ้อน การตรวจสอบฟอนต์และรูปภาพ คำใบ้ด้านความสอดคล้อง และแฟล็กความเสี่ยง นโยบายพรีไฟลต์จะแปลงรายงานเป็นผลตัดสิน pass/fail เพื่อให้คุณสามารถกั้นเอกสารก่อนเข้าสู่ไปป์ไลน์ได้

Stability: experimental การตรวจสอบภายในยังอยู่ระหว่างการพัฒนา รูปแบบของ InspectResult ชุดแฟล็กความเสี่ยง และเส้นทางการตรวจสอบแบบเร่งความเร็วซึ่งเป็นตัวเลือกเสริม อาจมีการเปลี่ยนแปลงระหว่างเวอร์ชันย่อย ใช้สำหรับการวินิจฉัยและ การกั้นเอกสาร ในตอนนี้อย่าพึ่งพารูปแบบผลลัพธ์ของโมดูลนี้เป็นสัญญาระยะยาว

การติดตั้ง

composer require nextpdf/core:^3

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

ใช้ Inspector เป็นจุดเริ่มต้น คลาสนี้นำ InspectorInterface ไปใช้และเปิดเผยเมท็อดเดียวคือ inspect(string $pdfData, InspectConfig $config = new InspectConfig()): InspectResult เมท็อดนี้เป็นแบบอ่านอย่างเดียว โดยแยกวิเคราะห์ PDF และอธิบายลักษณะของ PDF โดยไม่แก้ไขเอกสาร

InspectResult คือรายงานแบบมีโครงสร้าง รายงานนี้ประกอบด้วยคะแนนความซับซ้อน การตรวจสอบต่าง ๆ คำใบ้ และชุดของ RiskFlag ใช้ hasRisks() / hasRisk(RiskFlag $flag) เพื่อแยกการทำงานตามความเสี่ยงที่เฉพาะเจาะจง แทนการแยกวิเคราะห์ข้อความอิสระ ComplexityScore เปิดเผยคะแนนที่เป็นตัวเลขและแถบระดับ category() FontAuditEntry และ ImageAuditEntry อธิบายทรัพยากรที่ฝังอยู่ ComplianceHint ทำเครื่องหมายปัญหาด้านความสอดคล้องที่มีแนวโน้มจะเกิดขึ้น InspectIssue บันทึกข้อค้นพบที่เฉพาะเจาะจง InspectDepth กำหนดความลึกของการตรวจสอบ และ toSpectrumDepth() จับคู่ความลึกนั้นกับเส้นทางแบบเร่งความเร็วเมื่อมี Spectrum sidecar พร้อมใช้งาน การตรวจสอบทำงานได้โดยไม่ต้องมี sidecar โดย sidecar เปลี่ยนเฉพาะประสิทธิภาพ ไม่ใช่สัญญา InspectResponseParser สร้าง InspectResult จากการตอบกลับแบบดิบ (เช่น การตอบกลับของเส้นทางแบบเร่งความเร็ว) พร้อม trace ID ซึ่งเป็นตัวเลือกเสริม

PreflightPolicy คือเลเยอร์การตัดสิน evaluate(InspectResult $result) ใช้นโยบายที่กำหนดค่าไว้กับผลลัพธ์และคืนค่าผลของนโยบาย ทั้งโมดูลเป็น @since 2.2.0

พื้นผิว API

ชนิด	สมาชิกหลัก	บทบาท
Inspector	inspect(string $pdfData, InspectConfig $config): InspectResult	ตัวตรวจสอบ PDF แบบอ่านอย่างเดียว (@since 2.2.0)
InspectResult	hasRisks(), hasRisk(RiskFlag), ตัวเข้าถึง score/audit	รายงานการตรวจสอบแบบมีโครงสร้าง (@since 2.2.0)
ComplexityScore	category()	คะแนนความซับซ้อนที่เป็นตัวเลข + แถบระดับ (@since 2.2.0)
FontAuditEntry / ImageAuditEntry	ตัวเข้าถึงทรัพยากร	การตรวจสอบทรัพยากรที่ฝังอยู่ (@since 2.2.0)
ComplianceHint / InspectIssue	ตัวเข้าถึงข้อค้นพบ	คำใบ้และข้อค้นพบด้านความสอดคล้อง (@since 2.2.0)
InspectDepth (enum)	toSpectrumDepth()	ความลึกของการตรวจสอบ → เส้นทางแบบเร่งความเร็ว (@since 2.2.0)
PreflightPolicy	evaluate(InspectResult): array, toArray()	ผลตัดสินพรีไฟลต์แบบ Pass/fail (@since 2.2.0)
InspectResponseParser	parse(array, InspectConfig, ?string $traceId): InspectResult	สร้างผลลัพธ์จากการตอบกลับแบบดิบ (@since 2.2.0)

รัน composer docs:generate-api-php -- --module=Inspect เพื่อสร้างตาราง PHPDoc ฉบับสมบูรณ์

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

แหล่งที่มา: examples/34-inspect-layout-boxes.php สาธิตการอ่านเรขาคณิตของหน้า ตัวอย่างนี้ตรวจสอบโปรไฟล์ความเสี่ยงของ PDF ใด ๆ:

<?php

declare(strict_types=1);

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

use NextPDF\Inspect\Inspector;

$result = (new Inspector())->inspect(file_get_contents('/srv/in/incoming.pdf'));

if ($result->hasRisks()) {
    echo "Complexity: {$result->complexityScore()->category()}; risks present.\n";
}

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

กั้น PDF ขาเข้าด้วยนโยบายพรีไฟลต์ และปฏิเสธเมื่อพบความเสี่ยงใด ๆ

<?php

declare(strict_types=1);

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

use NextPDF\Inspect\Inspector;
use NextPDF\Inspect\PreflightPolicy;
use Psr\Log\LoggerInterface;

final readonly class IngestPreflight
{
    public function __construct(
        private Inspector $inspector,
        private PreflightPolicy $policy,
        private LoggerInterface $logger,
    ) {}

    public function accept(string $pdfData): bool
    {
        $result = $this->inspector->inspect($pdfData);
        $verdict = $this->policy->evaluate($result);

        if ($verdict !== []) {
            $this->logger->warning('PDF rejected at preflight.', ['findings' => $verdict]);

            return false;
        }

        return true;
    }
}

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

• inspect() เป็นแบบอ่านอย่างเดียว จะไม่แก้ไขหรือซ่อมแซมอินพุตใด ๆ อย่าคาดหวังว่าจะคืนค่าเอกสารที่ “แก้ไขแล้ว”
• hasRisk(RiskFlag) คือการตรวจสอบที่แม่นยำ การแยกการทำงานด้วย hasRisks() เพียงอย่างเดียวจะปฏิบัติต่อทุกความเสี่ยงเหมือนกันทั้งหมด โดยทั่วไปคุณต้องใช้แฟล็กที่เฉพาะเจาะจง
• InspectDepth ควบคุมต้นทุน การตรวจสอบเชิงลึกของ PDF ขนาดใหญ่จะช้ากว่าอย่างมีนัยสำคัญ ใช้ความลึกที่ตื้นที่สุดซึ่งยังตอบคำถามของคุณได้
• เส้นทางที่เร่งความเร็วด้วย Spectrum เปลี่ยนประสิทธิภาพ ไม่ใช่สัญญาของผลลัพธ์ ให้เขียนโค้ดเทียบกับ InspectResult ไม่ใช่รูปแบบการตอบกลับแบบเร่งความเร็ว
• PreflightPolicy::evaluate() คืนค่าข้อค้นพบโดยไม่โยนข้อยกเว้น ผลลัพธ์ว่างหมายถึงผ่าน ให้ดำเนินการตามค่าที่คืนกลับมา

ประสิทธิภาพ

ต้นทุนการตรวจสอบเพิ่มขึ้นตามขนาดเอกสารและ InspectDepth ที่เลือก การตรวจสอบแบบตื้นทำได้รวดเร็ว ส่วนการตรวจสอบเชิงลึกของ PDF ขนาดใหญ่อาจเข้าใกล้งบประมาณ เส้นทาง Spectrum จะถ่ายโอนงานแยกวิเคราะห์ที่หนักหน่วงออกไปเมื่อพร้อมใช้งาน performance_budget ที่ 1500 ms wall / 64 MB peak อธิบายปริมาณงานอ้างอิง โปรไฟล์การทำซ้ำได้คือ structural: ผลลัพธ์อาจมี trace ID และข้อมูลเวลา การรันสองครั้งจึงอาจต่างกันในฟิลด์เหล่านั้น ขณะที่ข้อค้นพบยังคงเสถียรสำหรับอินพุตเดียวกัน

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

Inspector::inspect() แยกวิเคราะห์ไบต์ PDF ที่ไม่น่าเชื่อถือ ซึ่งเป็นวัตถุประสงค์ของเมท็อดนี้ ดังนั้นให้ปฏิบัติต่ออินพุตเสมือนเป็นภัยคุกคามเสมอ สำหรับเอกสารที่ผู้ใช้ส่งมา ให้รันการตรวจสอบในเวิร์กเกอร์ที่จำกัดทรัพยากร และจำกัดขนาดอินพุตที่ต้นทาง PDF ที่ตั้งใจทำให้ซับซ้อนเป็นช่องทางโจมตีแบบปฏิเสธบริการได้ ไม่ว่าจะใช้ความลึกระดับใด ผลลัพธ์อธิบายเอกสาร แต่ไม่ได้ทำความสะอาดเอกสาร การตัดสินว่า “ความเสี่ยงต่ำ” เป็นฮิวริสติก ไม่ใช่การรับประกันความปลอดภัย ปฏิบัติต่อสตริงและเมทาดาทาที่สกัดออกมาเสมือนว่าไม่น่าเชื่อถือ ดูแบบจำลองภัยคุกคามของเอนจินใน /modules/core/security/

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

โมดูลนี้รายงานคำใบ้ด้านความสอดคล้อง โดยไม่ได้ให้การตัดสินความสอดคล้องที่เชื่อถือได้ ComplianceHint ทำเครื่องหมายปัญหาที่มีแนวโน้มจะเกิดขึ้นแบบฮิวริสติก สำหรับ PDF/A, PDF/UA และ International Organization for Standardization (ISO) 32000-2 การตัดสินความสอดคล้องที่เชื่อถือได้มาจากตัวตรวจสอบอ้างอิงที่ขับเคลื่อนโดย /modules/core/cli/ รวมถึงชุดออราเคิลและชุดทดสอบโกลเดนที่อธิบายไว้ใน /modules/core/conformance/ อย่าถือว่าผลลัพธ์ Inspect ที่สะอาดเป็นการรับรองความสอดคล้อง

ดูเพิ่มเติม

• โมดูล Cli — ขับเคลื่อนตัวตรวจสอบภายนอกที่เชื่อถือได้
• ภาพรวมความสอดคล้อง — ผลตัดสินที่เชื่อถือได้และชุดทดสอบโกลเดน
• โมดูล Accelerator — เส้นทางการตรวจสอบแบบเร่งความเร็วซึ่งเป็นตัวเลือกเสริม
• แบบจำลองความปลอดภัยของเอนจิน