Enterprise 版本

Output Pipeline — 深入參考

概覽

NextPDF\Enterprise\OutputPipeline 會把許多 Pro 管線清單當成一個批次執行。BatchPipelineOrchestrator 以批次協調包裹 Pro 的 PipelineExecutor：一道對批次大小設限的有界資源防護、一個可選的全域批次逾時、逐清單的變數注入，以及彙總帳目。一道可選的批次末端合規檢查，會透過 Enterprise 合規閘道器重新驗證每份已完成的輸出，並採取失敗即關閉。每次執行都會回傳一個 BatchPipelineResult，內含逐清單結果、已完成與失敗的數量、計時，以及那份可選的合規報告。

供應與授權

這項能力隨 NextPDF Enterprise（nextpdf/enterprise）出貨，並以一份 Enterprise 級授權封套啟用。缺少該權利的部署不會載入這項能力的類別。比較版本並取得授權。

版本	Output-pipeline 介面
Core	無 output-pipeline 介面。
Pro	單一清單管線（能力 `pro.output.pipeline`）。
Enterprise	批次協調、批次大小上限、批次逾時、合規交接。

Enterprise 的批次介面沒有獨立的逐功能能力碼；由套件邊界閘控它。Pro 的單一清單能力 pro.output.pipeline 是一項前提，而非閘門。單憑一份 Pro 授權只會解鎖底層的單一清單管線，而非這個批次介面。

composer require nextpdf/enterprise:^3

公開 API 介面

符號	參數	預設行為	回傳	拋出或失敗於	備註
`BatchPipelineOrchestrator::__construct()`	`PipelineExecutor $executor`、`BatchPipelineConfig $config`、`?ComplianceGateway $complianceGateway`、`ComplianceProfile $complianceProfile`	預設設定；無閘道器；設定檔 `ComplianceProfile::PdfA4`	—	無	當啟用合規檢查時請注入一個閘道器；缺少閘道器時，每份受檢清單都會被回報為失敗。
`BatchPipelineOrchestrator::executeBatch()`	`list<PipelineManifest> $manifests`、`array<string, array<string, mixed>> $variablesMap = []`	依提交順序執行清單；變數依清單 ID 解析	`BatchPipelineResult`	當批次超過 10,000 份清單時拋出 `OverflowException`；當啟用合規檢查時拋出閘道器例外（見「邊界案例」）	Resolver 的 `Throwable` 絕不外洩；Pro 執行器會把它們降級為失敗的步驟結果。
`BatchPipelineConfig::__construct()`	`int $maxConcurrency = 4`、`int $timeoutMs = 0`、`bool $complianceCheckOnComplete = false`	並行數 4；無逾時；無合規檢查	—	無	唯讀值物件。`timeoutMs = 0` 會停用批次逾時。
`BatchPipelineResult::__construct()`	`list<PipelineResult> $results`、`int $totalManifests`、`int $completedCount`、`int $failedCount`、`float $durationMs`、`?array $complianceReport = null`	對逐清單的 `PipelineResult` 值做彙總	—	無	唯讀。`complianceReport` 除非檢查有執行，否則維持 `null`。
`BatchPipelineResult::allSucceeded()`	—	檢測 `failedCount === 0`	`bool`	無	對一個因逾時被截斷、且零失敗的批次會回傳 true；見「邊界案例」。
`BatchPipelineResult::successRate()`	—	`completedCount / totalManifests`	`float`	無	對空批次回傳 `1.0`。
`BatchPipelineResult::hasComplianceReport()`	—	檢測 `complianceReport !== null`	`bool`	無	—

public function __construct(
    private readonly PipelineExecutor $executor,
    private readonly BatchPipelineConfig $config = new BatchPipelineConfig(),
    private readonly ?ComplianceGateway $complianceGateway = null,
    private readonly ComplianceProfile $complianceProfile = ComplianceProfile::PdfA4,
) {}

public function executeBatch(
    array $manifests,
    array $variablesMap = [],
): BatchPipelineResult

public function __construct(
    public int $maxConcurrency = 4,
    public int $timeoutMs = 0,
    public bool $complianceCheckOnComplete = false,
) {}

行為合約

executeBatch() 會先把批次大小對 10,000 份清單的上限做斷言。超過上限的批次會在任何清單執行前引發 OverflowException；不會有任何東西默默降級。

清單接著會透過 Pro 的 PipelineExecutor 依提交順序執行。每份清單會收到 $variablesMap 中以其 ID 為鍵的變數項目；沒有對應項目的清單會收到一個空的變數對應表。當一份清單的 PipelineResult 狀態為 Completed 時計為已完成；任何其他終態都計為失敗。Resolver 例外不會外洩：Pro 執行器會把每一個 resolver 的 Throwable 轉換為失敗的步驟結果，因此 executeBatch() 一律彙總結果，而不會在某個步驟出錯時於批次中途中止。

當 timeoutMs 大於零時，會在每份清單開始前檢查已耗用時間。一旦預算耗盡，剩下的清單就會被略過：它們不會產生 PipelineResult，且既不計為已完成也不計為失敗。totalManifests 一律回報提交的數量。

當啟用 complianceCheckOnComplete 時，協調器會透過注入的 ComplianceGateway，對每份已完成清單的最終 PDF 依所設定的 ComplianceProfile 進行驗證。這道檢查採取失敗即關閉：

未注入閘道器：每份受檢清單都回報為失敗，因為合規從未經過驗證。
無法從清單的步驟輸出解析出 PDF 輸出：失敗。
閘道器未回傳結果（可選模式下 sidecar 不可用）：失敗。沒有肯定結果並不等於通過。
閘道器回報任何不符：失敗。

最終 PDF 是這樣解析出來的：掃描一份已完成清單的步驟輸出，從最後一步往前，找出一個以 %PDF 標頭開頭的直接字串值。步驟輸出絕不會把 PDF 位元組字串巢狀嵌在子陣列裡；只檢查直接的輸出值。未完成的清單會被略過，不受檢。

合規報告是一個帶有 profile、checked、passed、failed 與 failures 這些鍵的陣列；每個失敗項目會攜帶 manifestId 與 reason。這份報告會附在 BatchPipelineResult::$complianceReport 上，並可透過 hasComplianceReport() 取得。

合規交接是一項重新驗證輔助，不是授權控制。它只回報 findings。

邊界案例與失敗模式

超過 10,000 份清單：在任何執行開始前拋出 OverflowException。
timeoutMs = 0 代表沒有批次逾時。在正式環境中請設定一個有限值。
逾時截斷：被略過的清單不出現在任何計數中，因此 completedCount + failedCount 可能小於 totalManifests。allSucceeded() 只檢測 failedCount === 0，對被截斷的批次可能回傳 true。比較 count($result->results) 與 totalManifests 以偵測截斷。
successRate() 對空批次（提交零份清單）回傳 1.0。
清單 ID 不會在批次層級去重。兩份共用同一 ID 的清單都會執行，並解析到同一個變數項目。
結構性清單錯誤（空的步驟列表、重複的步驟 ID、未知的相依、相依循環、輸出型別不符、缺少 resume 步驟）會在清單建構時、在 executeBatch() 被呼叫之前引發 InvalidArgumentException。
啟用合規檢查時，ComplianceGateway::validate() 可能拋出 ComplianceSidecarUnavailableException（required 模式下 sidecar 不可用）或 InvalidArgumentException（未為該設定檔的工具註冊驗證器）。任一例外都會在執行之後、但在結果建立之前逸出 executeBatch()，因此逐清單結果對呼叫端會遺失。在 optional 模式下，閘道器改為回傳 null，該清單被記錄為一次合規失敗。
一道管線內的合規交接步驟，會在沒有任何上游步驟輸出含有可辨識的 PDF 位元組時失敗；它絕不會默默通過。
本模組不執行任何密碼學運算；FIPS 模式不適用。

一致性

本模組不主張任何標準一致性；它是一個協調層。可選的合規檢查會延後交由 Enterprise 合規閘道器與其外部驗證器處理，由它們承載自己的參考。預設設定檔是 ComplianceProfile::PdfA4；其他閘道器設定檔涵蓋更多 PDF/A、PDF/UA 與 PAdES 目標。

一份合規報告陳述的是驗證器針對所選設定檔的 findings。它不認證任何文件、不保證法規上的充分性，也不構成法律建議。判斷某個輸出是否符合你的義務，是你的責任。

開發備註

在正式環境部署中，平行的工作者派送與反壓由一個獨立的執行 sidecar 處理。PHP 協調器提供批次協調與合規交接邏輯，並由作業工作者調用，而非由請求處理器直接調用。
PHP 後備路徑會循序執行清單。maxConcurrency 在 sidecar 驅動的部署中限制並行的工作者回呼；相對於 PHP 工作者池為它設定大小，是操作者的責任。
管線內的合規交接步驟解析器，是為 inspect 型步驟註冊的一個內部型別。請透過 BatchPipelineConfig 啟用批次末端驗證，而不要直接為此建構管線步驟。
及早建構 PipelineManifest 實例。它們的結構性驗證會在建構子中執行，因此無效的圖會快速失敗，絕不消耗批次預算。

發佈邊界

本頁僅記載外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔名，以及工單前綴，皆不在範圍內。