Inspect：PDF 內省與預檢

概覽

Inspect 模組會讀取既有的 PDF，並回報其內容：複雜度分數、字型與影像稽核、一致性提示，以及風險旗標。預檢政策會將這份報告轉為 pass/fail 決策，讓你能在文件進入管線之前先行把關。

穩定度：實驗性。 內省是一個仍在演進的介面。此 InspectResult 的結構、風險旗標集合，以及選用的加速檢測路徑，都可能在次要版本之間變動。請將它用於診斷與把關；現在還不適合把長期契約綁定在其結果結構上。

安裝

composer require nextpdf/core:^3

概念綜覽

Inspector 是進入點。它實作 InspectorInterface，並只對外提供一個方法：inspect(string $pdfData, InspectConfig $config = new InspectConfig()): InspectResult。它是唯讀的 —— 會剖析一份 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()`	通過/不通過的預檢決策（`@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 牆鐘時間/64 MB 尖峰）是參考工作負載。可重現性設定檔為 structural：結果可能附帶 trace id 與計時資訊。兩次執行會在這些欄位上有所不同，但對相同輸入而言，查核結果是穩定的。

安全性須知

Inspector::inspect() 會剖析不受信任的 PDF 位元組，而這正是它的用途；因此請將輸入視為具敵意。對於使用者提供的文件，請在受限的 worker 中執行檢測，並於上游限制輸入大小。不論檢測深度為何，蓄意設計得極為複雜的 PDF 都可能成為阻斷服務的攻擊管道。結果會描述該文件，但並不會對其進行清理 ——「低風險」判定是一種啟發式判斷，並非安全性保證。請將擷取出的字串與中繼資料視為不受信任。請參閱 /modules/core/security/ 中的引擎威脅模型。

一致性

本模組回報的是一致性提示；它並非權威性的一致性判定。ComplianceHint 會以啟發式方式標示可能的問題。權威性的 PDF/A、PDF/UA 與 ISO 32000-2 一致性判定，來自 /modules/core/cli/ 驅動的參考驗證器，以及 /modules/core/conformance/ 中所述的 oracle 與 golden 套件。請勿將乾淨的 Inspect 結果視為一致性認證。

另請參閱

CLI 模組 —— 驅動權威性的外部驗證器。
一致性綜覽 —— 權威性判定與 golden 套件。
Accelerator 模組 —— 選用的加速檢測路徑。
引擎安全性模型