跳到內容
NextPDF

Cli：命令處理器與外部驗證器轉接器

概覽

標題為「概覽」的區段

Cli 模組是引擎診斷與符合性工具背後的命令介面。它包含一組命令處理器——benchmark、diff、init、verify、capabilities。它同時提供一組轉接器，在單一介面後方包裝外部 PDF 驗證器（veraPDF、Arlington PDF model）。單一個 verify 命令即可驅動其中任一驗證器。

安裝

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

概念總覽

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

每個命令都是一個處理器類別，並具備會回傳行程結束代碼的 execute()。BenchmarkHandler 執行基準測試情境。DiffHandler 比較文件。InitHandler 建立專案骨架。VerifyHandler 執行符合性驗證。CapabilitiesHandler 回報執行階段支援的功能。CliOutput 是各處理器共用的輕量 stdout/stderr 寫入器，因此輸出可供測試，而不是與全域變數耦合。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 介面

標題為「API 介面」的區段
類別主要成員角色
BenchmarkHandlerexecute(string $format = 'pretty', ?string $scenario = null): int執行基準測試情境（@since 2.4.0）
VerifyHandlerexecute(): int驅動符合性驗證
DiffHandler / InitHandlerexecute(): int文件比對 / 專案骨架
CapabilitiesHandlerexecute(string $format = 'pretty'): int回報執行階段功能（@since 2.3.0）
AlternateValidatorAdapter（介面）validate()、isAvailable()、toolIdentifier()外部驗證器合約（@since 3.0.0）
VeraPdfCliAdapter實作此轉接器包裝 veraPDF CLI（@since 3.0.0）
ArlingtonValidatorAdapter實作此轉接器包裝 Arlington PDF model（@since 3.0.0）
AsyncValidatorAdapter實作此轉接器支援非同步的驗證器包裝（@since 3.0.0）
CliOutputwrite()、writeln()、error()可供測試的 stdout/stderr 寫入器（@since 2.3.0）
BinaryFinder外部工具路徑解析定位主機工具（@since 2.5.0）

執行 composer docs:generate-api-php -- --module=Cli 以取得完整的 PHPDoc 表格。

程式碼範例——快速上手

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

來源：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。它不會擲出例外。「沒有可用的驗證器」並不算通過——請像正式環境範例那樣另行處理。
  • 這些轉接器會執行外部二進位檔。它們的判定是經過正規化的外部工具判定——並非獨立的重新實作。請讓這些工具保持在最新版本。
  • 處理器的 execute() 會回傳行程結束代碼。非零即代表失敗。請從你的包裝程式向上傳遞它，而非將它捨棄。
  • BinaryFinder 會在主機上解析工具路徑。不同主機可能解析出不同的工具版本。請固定環境，以取得可重現的驗證。
  • 可重現性設定檔為 structural：驗證報告包含時間戳記與工具版本，因此兩次執行在這些欄位上會有差異。

效能

標題為「效能」的區段

處理器本身的額外負擔可忽略不計。成本主要來自外部驗證器行程，在大型文件上可能很慢。AsyncValidatorAdapter 的用途就是重疊這段延遲。1500 ms 牆鐘時間 / 64 MB 尖峰的 performance_budget 是引擎的參考值，並非外部驗證器的限制。基準測試輸出在結構上具確定性，但依其性質本就會包含計時資料。

安全性注意事項

標題為「安全性注意事項」的區段

這些轉接器會針對一個 PDF 路徑啟動外部行程。請將該 PDF 視為不受信任的輸入。請在受限制的環境中執行驗證。這些外部驗證器會剖析具敵意的資料。在將任何檔案路徑傳給處理器之前，請先驗證並正規化它，以避免路徑遍歷到非預期的檔案。請勿將未經淨化的使用者輸入當作命令引數傳入。這些轉接器建構的是行程引數，而非 shell 字串。輸入檔案本身仍由攻擊者控制。請參閱 /modules/core/security/ 中的引擎威脅模型。

符合性

標題為「符合性」的區段

本模組本身不主張任何 PDF 規格上的規範性聲明。它透過委派給參考驗證器（以 veraPDF 處理 PDF/A 與 PDF/UA，以 Arlington PDF model 處理 ISO 32000-2 結構規則）來協調符合性驗證。具權威性的符合性判定來自外部工具。本模組負責將其正規化並回報。端對端的符合性與黃金基準描述於 /modules/core/conformance/ 中。

另請參閱

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