跳到內容
NextPDF

Compliance（合規）：PDF/R-1 驗證器、Arlington 文法與生命週期工具

概覽

標題為「概覽」的區段

NextPDF\Compliance 隨附位元組串流驗證器與一套文法交叉檢查，會讀取已完成的 PDF，並回報其偏離規範性契約的位置。驗證器回傳零個發現項，只代表它所實作條款的 已檢查 結果，並非全面性的合格證明。

安裝

標題為「安裝」的區段
Terminal window
composer require nextpdf/core:^3

概念總覽

標題為「概念總覽」的區段

這個模組分為三個部分。

PdfRValidator 會驗證一份候選的 ISO 23504-1:2020（PDF/R-1）位元組串流。它直接作用於原始位元組，而不是 writer 的內部狀態，用來抓出 writer 預計輸出的內容與規格要求之間的偏移；它是最後一道檢查。已實作的條款集為 v5.1.0 叢集：§5 版本識別註解、§6.2.2/§6.2.3 標頭允許清單、§6.2.4 generation-0 與物件串流禁用、§6.5.7 內容串流運算子允許清單（僅限 q、Q、cm、Do）、§6.6.1 影像 XObject 鍵值允許清單、§6.4.3 Info 字典鍵值允許清單，以及 §6.3 Catalog 鍵值允許清單。§6.7 增量更新與 §6.8 加密在初始叢集中明確排除在範圍之外，並在 claims.json 中如此宣告。驗證器不會在遇到第一個發現項時就拋出例外；它會在單一遍歷中收集每一處偏離，讓呼叫端看到完整差異。

PdfRConformancePolicy 是一個不可變政策，用於 PDF/R-1 周邊那些 建議但僅供參考 的範圍。規範性的 §6 底線永遠不能透過設定調整。這個政策只控制 §A.5 實作限制建議、§6.6.1 多重區塊（multi-strip）的不建議用法，以及下游 PDF/A 重新分類所需的 §A.6 XMP 要求。

ArlingtonValidator 以僅回報模式驅動上游 PDF Association 的 Arlington PDF 模型。在目前週期中，它一律僅供參考：validateReportOnly() 永遠不會拋出例外。它會依三種模式降級。當參考檢查器（reference checker）二進位檔存在時，它會剖析結構化的發現項。當只有釘選的文法時，它會輸出一個 info 發現項，以證明文法釘選已載入。當文法不存在時，它會回傳空清單。WaiverRegistry 讓編排器（orchestrator）在保留稽核軌跡的同時，抑制已知可接受的歧異。

這項誠實原則與 CSS 支援矩陣以及一致性（conformance）模組相同。只有在有通過的測試，且引用規範性條款時，某個條款才會標記為 Verified（已驗證）。已實作但缺少專屬通過 fixture 的條款則標記為 Claimed（已聲明）。範圍外的條款會被明確陳述，而非保留模糊空間。零發現項的 PdfRValidator 結果只斷言它實際檢查過的條款；它對 §6.7 或 §6.8 不做任何聲明，因為它並未實作這兩節。

API 介面

標題為「API 介面」的區段
型別種類主要成員
NextPDF\Compliance\Validator\PdfRValidatorfinal classvalidate(string $pdfBytes): list<PdfRValidationFinding>
NextPDF\Compliance\Validator\PdfRValidationFindingfinal readonly classstring $clause（條款）、'error'|'warning'|'info' $severity, string $message（訊息屬性）
NextPDF\Compliance\Profile\PdfRConformancePolicyfinal readonly class__construct(bool $enforceA5ImplementationLimits = true, bool $rejectMultiStripPages = false, bool $requireXmpForA6Compatibility = false); lax(), strictArchival()
NextPDF\Compliance\Validator\ArlingtonValidatorfinal classvalidateReportOnly(string $pdfPath): list<ArlingtonFinding>
NextPDF\Compliance\Validator\WaiverRegistryfinal classisWaived(string $validator, string $ruleId, string $scopeKey): bool

程式碼範例 — 快速上手

標題為「程式碼範例 — 快速上手」的區段
<?php


declare(strict_types=1);


use NextPDF\Compliance\Validator\PdfRValidator;


$validator = new PdfRValidator();
$findings  = $validator->validate(file_get_contents('candidate.pdf'));


if ($findings === []) {
    // Zero divergences from the §6 clauses PdfRValidator implements.
    // This is NOT a PDF/R-1 certificate — §6.7 and §6.8 are not checked.
    echo "No PDF/R-1 §6 divergences detected (implemented clause set).\n";
} else {
    foreach ($findings as $f) {
        echo "[{$f->severity}] §{$f->clause}: {$f->message}\n";
    }
}

程式碼範例 — 正式環境

標題為「程式碼範例 — 正式環境」的區段
<?php


declare(strict_types=1);


use NextPDF\Compliance\Validator\ArlingtonValidator;
use NextPDF\Compliance\Validator\ArlingtonGrammarLoader;
use NextPDF\Compliance\Validator\WaiverRegistry;


$validator = new ArlingtonValidator(
    waivers: new WaiverRegistry(/* loaded waiver entries */),
    grammar: new ArlingtonGrammarLoader(/* pinned submodule path */),
    adapter: null, // grammar-only mode when the reference checker is absent
);


// Advisory by contract — never throws on findings.
$findings = $validator->validateReportOnly('artifact.pdf');


foreach ($findings as $finding) {
    // Each finding pins the Arlington grammar commit SHA for provenance.
    logger()->info('arlington', [
        'rule'       => $finding->ruleId,
        'severity'   => $finding->severity,
        'grammarSha' => $finding->grammarSha,
    ]);
}

邊界情況與陷阱

標題為「邊界情況與陷阱」的區段
  • PdfRValidator 以正規表示式為基礎，並非完整的 parser（剖析器）。 它鎖定 NextPDF\Writer\PdfRWriter 的確定性輸出。它的角色是該 writer 的偏移偵測器，並不是通用的 PDF parser。
  • 零發現項 ≠ 完整的 PDF/R-1 一致性。 §6.7（增量更新）與 §6.8（加密）並未在 v5.1.0 叢集中實作，且在 claims.json 中宣告為範圍之外。請把乾淨的結果視為「在已實作的條款集上沒有偏離」，僅此而已。
  • Arlington 是諮詢性的。 在目前週期中，validateReportOnly() 永遠不會讓建置失敗。CI 會取用這份產物，但不會把它作為閘門。
  • PDF/A ICC 驗證不在這裡。 ISO 19005-4:2020 §6.2.2 的 OutputIntent ICC 驗證位於 Enterprise 版的 PdfAManager（nextpdf/pro），而不在 Core 的 Compliance 模組中。Core 的 PDF/A 介面只有 ConformanceMode 這個區別器。
  • 豁免會保留稽核軌跡。 被豁免的規則會從發現項清單中被抑制，但豁免項目仍會留下記錄，說明 為何 如此處理。

效能

標題為「效能」的區段

PdfRValidator::validate() 是對位元組串流的單一線性遍歷，搭配有界限的正規表示式走訪。成本會隨文件大小擴展，並穩定落在模組預算之內。ArlingtonValidator 在僅文法模式下，產生載入證明發現項的複雜度為 O(grammar-rule-count)。參考檢查器路徑是一個子處理程序，其上限由上游工具決定，而非由 NextPDF 決定。它是一個非同步（out-of-band）的 CI 步驟。

安全性說明

標題為「安全性說明」的區段

這些驗證器會讀取不受信任的 PDF 位元組。PdfRValidator 會在擷取鍵值之前先剝除括號字串與十六進位字面值，因此精心構造的 Creator 字串無法注入假的 /Name 鍵值（ISO 32000-1:2008 §7.3.4.2 跳脫處理）。Arlington 轉接器會以有界限的子處理程序執行上游檢查器。它會把逾時或執行錯誤視為「無發現項」，而不會信任不完整的輸出。關於 PDF 剖析的攻擊面，請參閱本專案的威脅模型。

一致性

標題為「一致性」的區段
標準條款Compliance 模組的作用狀態
ISO 23504-1:2020（PDF/R-1 標準）§6.5.7PdfRValidator 強制執行 {q,Q,cm,Do} 內容串流運算子允許清單Verified（單元測試＋標準設定檔測試＋整合測試皆通過）
ISO 23504-1:2020（PDF/R-1 標準）§6.4.3PdfRValidator 強制執行 Info 字典鍵值允許清單已驗證（有測試支撐）
ISO 23504-1:2020（PDF/R-1 標準）§6.7、§6.8未在 v5.1.0 叢集中實作明確的非涵蓋範圍（在 claims.json 中宣告）
ISO 32000-2:2020（PDF 2.0）§7.5.2Catalog 鍵值允許清單走訪Claimed（正規表示式走訪；結構性）
ISO 19005-4:2020（PDF/A-4 標準）§6.7.3透過一致性模組對識別綱要（identification-schema）的認知交叉參照（見 /specifications/pdfa4/ 一節）

支援不等於一致性。 一次 PdfRValidator 執行若回傳零發現項，只證明輸入沒有偏離 該驗證器所實作的 §6 條款。它並不斷言該檔案是一份符合 PDF/R-1 的檔案：§6.7 與 §6.8 並未受檢。Arlington 交叉檢查是諮詢性的，永遠不會斷言一致性。對於 PDF/A-4，具權威性的驗證器是 veraPDF，以非同步方式執行；關於 veraPDF oracle 及其可選用的閘門，請見 一致性模組。

引用內容均改寫自 NextPDF 合規語料庫。完整的 64 字元 reference_id 摘要記錄於頁面 front-matter 與 _normative-evidence-conf.md 之中。

另請參閱

標題為「另請參閱」的區段