Output Pipeline — 深入參考

速覽

本頁是 NextPDF\Pro\OutputPipeline 公開介面的深入參考。內容涵蓋 manifest 的建構與驗證、拓樸執行順序、重試與逾時語意、resume 行為，以及 fail-closed 的 Pack 能力閘門。它針對每一個公開符號說明參數、預設值與失敗模式。請先閱讀 Output Pipeline 功能頁面 以取得工作流程指引。

供應與授權

此功能隨 NextPDF Pro（nextpdf/pro）出貨，並在具備 Pro 層級授權封套時啟用。缺少該授權的部署不會載入此功能的類別。比較版本並取得授權。

執行器與十種步驟型別中的七種不帶任何個別功能旗標。另有三種步驟型別需要 Pack 能力：

步驟型別	Manifest 值	所需能力	Pack
Redact	redact	pack.privacy.redact	Privacy Pack
Extract	extract	pack.intelligence.extract	Intelligence Pack
OCR overlay	ocr_overlay	pack.intelligence.searchable_pdf	Intelligence Pack

閘門在執行期強制執行，採 fail-closed，發生在步驟抵達其 resolver 之前。未授權的閘控步驟會產生一個攜帶 SPEC-LIC-001 代碼與所需能力的 Failed 步驟結果；resolver 永遠不會被呼叫。未注入 capability resolver 的管線會拒絕每一個閘控步驟。

公開 API 介面

composer require nextpdf/pro:^3

nextpdf/premium metapackage 會安裝 nextpdf/pro 程式碼；此模組位於 NextPDF\Pro\OutputPipeline 命名空間之下。

符號	參數	預設行為	回傳	拋出或失敗於	備註
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	綁定內建的 resolver registry 與可選的授權來源	PipelineExecutor	未宣告	null 的 capability resolver 會拒絕每一個受 Pack 閘控的步驟
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	依拓樸順序執行步驟並彙整結果	PipelineResult	未宣告；resolver 失敗會被擷取為 Failed 步驟結果	設計用於在非同步的 job worker 內執行
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	在建構時驗證步驟圖	PipelineManifest	空步驟清單、重複的步驟 ID、未知的相依、循環、輸出型別不符，或缺少 resume 步驟時拋出 InvalidArgumentException；超過 10 000 個步驟時拋出 OverflowException	所有驗證在任何執行之前完成
PipelineManifest::topologicalOrder	無	將相依步驟排在依賴者之前	list<PipelineStep>	未宣告	對於同一份 manifest 具決定性
PipelineManifest::getStep	string $stepId	依步驟 ID 進行線性查找	?PipelineStep	未宣告	未知 ID 回傳 null
PipelineManifest::rootSteps	無	回傳沒有相依的步驟	list<PipelineStep>	未宣告	根步驟最先執行
PipelineManifestBuilder::create	string $manifestId	開始一個新的 builder	self	未宣告	建構子為 private；此為唯一入口
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	附加一個步驟；null 的輸出型別會由步驟型別推得	self	未宣告	驗證延後到 build()
PipelineManifestBuilder::stopOnError	bool $stop = true	設定「首次失敗即停止」	self	未宣告	預設為 true
PipelineManifestBuilder::maxRetries	int $retries	設定每個步驟的重試上限	self	未宣告	預設為 0（不重試）
PipelineManifestBuilder::timeout	int $timeoutMs	設定全域管線逾時	self	未宣告	0 會停用逾時
PipelineManifestBuilder::resumeFrom	string $stepId	設定 resume 起點	self	未宣告	該步驟必須在 build() 時存在
PipelineManifestBuilder::build	無	建構經過驗證的 manifest	PipelineManifest	同 PipelineManifest::__construct	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	不可變的執行選項	PipelineOptions	未宣告	Readonly 值物件
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	不可變的步驟定義	PipelineStep	未宣告	直接建構會將每一種型別的輸出型別都預設為 PDF
PipelineStep::isRoot	無	當步驟沒有相依時為 True	bool	未宣告	—
PipelineStepType (enum)	—	十個以字串為底的 case：generate、merge、split、inspect、compress、sign、convert，加上受閘控的 redact、extract、ocr_overlay	—	—	每個內建操作對應一個 case
PipelineStepType::requiresPack	無	對 Redact、Extract 與 OcrOverlay 為 True	bool	未宣告	其他所有 case 回傳 false
PipelineStepType::requiredCapability	無	將受閘控的 case 對應到其能力代碼	?string	未宣告	非閘控的 case 回傳 null
PipelineStatus (enum)	—	五個 case：pending、running、completed、failed、cancelled	—	—	由管線與步驟結果共用
PipelineStatus::isTerminal	無	對 Completed、Failed 與 Cancelled 為 True	bool	未宣告	Pending 與 Running 為非終結
StepOutputType (enum)	—	三個 case：pdf、json、metadata	—	—	驅動建構期的邊驗證
StepOutputType::forStepType	PipelineStepType $stepType	某步驟型別的預設輸出型別	self	未宣告	Inspect 與 Extract 對應到 JSON；其他所有型別對應到 PDF
StepOutputType::isCompatibleWith	self $expectedInput	同型別相符或 PDF 輸出時為 True	bool	未宣告	輔助方法；PDF 是通用輸入
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	每次執行的記憶體內 context	PipelineContext	未宣告	無 TTL、過期、持久化或後端儲存
PipelineContext::setStepResult / ::getStepResult	string $stepId (+ StepResult on set)	記錄或讀取一個步驟結果	void / ?StepResult	未宣告	尚未執行的步驟回傳 null
PipelineContext::setStepOutput / ::getStepOutput	string $stepId (+ mixed on set)	儲存或讀取一個中間輸出	void / mixed	未宣告	缺少輸出時回傳 null
PipelineContext::hasStepResult	string $stepId	某步驟是否已執行	bool	未宣告	支援 resume 檢查
PipelineContext::allStepResults	無	目前為止記錄的所有結果	array<string, StepResult>	未宣告	以步驟 ID 為鍵
PipelineContext::isResume	無	該次執行是否從某步驟 resume	bool	未宣告	—
PipelineResult::isSuccess	無	只有整體狀態為 Completed 時才為 True	bool	未宣告	結果由執行器產生
PipelineResult::getStepResult	string $stepId	依 ID 尋找一個步驟結果	?StepResult	未宣告	被略過或未知的步驟回傳 null
PipelineResult::failedSteps	無	篩選出失敗的步驟結果	list<StepResult>	未宣告	完全成功時為空清單
StepResult::isSuccess	無	只有步驟狀態為 Completed 時才為 True	bool	未宣告	攜帶 stepId、type、status、durationMs、error、output
CapabilityResolverInterface::hasCapability	string $capability	對單一能力代碼進行肯定式的授權測試	bool	不得拋出	預設拒絕（deny-by-omission）：未知、過期或未對應的代碼回傳 false

進入點簽章

final class PipelineExecutor
{
    public function __construct(
        private readonly StepResolverRegistry $registry,
        private readonly ?CapabilityResolverInterface $capabilityResolver = null,
    )

    public function execute(PipelineManifest $manifest, array $variables = []): PipelineResult
}

final class PipelineManifestBuilder
{
    public static function create(string $manifestId): self

    public function addStep(
        string $id,
        PipelineStepType $type,
        array $parameters = [],
        array $dependsOn = [],
        ?StepOutputType $outputType = null,
    ): self

    public function stopOnError(bool $stop = true): self

    public function maxRetries(int $retries): self

    public function timeout(int $timeoutMs): self

    public function resumeFrom(string $stepId): self

    public function build(): PipelineManifest
}

interface CapabilityResolverInterface
{
    public function hasCapability(string $capability): bool;
}

行為合約

Manifest 驗證

驗證在 PipelineManifest 建構子中執行，發生在任何執行之前。依序為：步驟清單不得為空；步驟數量上限為 10 000，將惡意設計的極深相依鏈轉換為可攔截的 OverflowException，而非原生的堆疊耗盡；步驟 ID 必須唯一；每一個 dependsOn 參照都必須能解析；相依圖必須無循環；輸出型別必須相容；宣告的 resume 步驟必須存在。每一項違規都會以特定訊息拋出 InvalidArgumentException。

輸出型別檢查套用於型別對應到 PDF 輸出的步驟：這類步驟的每一個相依本身都必須產生 PDF 輸出。指向產生 JSON 之步驟型別（inspect、extract）的相依邊，在此版本中不做型別檢查。

執行順序、resume 與逾時

execute($manifest, $variables) 會建立一個全新的 PipelineContext、計算拓樸順序，並依該順序循序執行步驟。設定 resume 起點後，較早的步驟會被略過，直到抵達具名步驟為止。被略過的前置步驟不會重新執行，其輸出也不會被還原：context 是每次執行且僅存於記憶體，因此 resume 的步驟若讀取被略過前置步驟的輸出，會觀察到 null。

全域逾時為正值時，會在步驟之間、每個步驟開始前進行評估。逾時發生時，管線狀態變為 Failed，其餘步驟不會啟動。已在執行中的步驟永遠不會在執行途中被中斷，因此單一長時間步驟可能超出預算。

重試與失敗擷取

每個步驟至多獲得 maxRetries + 1 次嘗試。成功的嘗試會立即回傳。任何失敗的嘗試——resolver 回傳的 Failed 結果，或拋出的 Throwable——只要還有嘗試次數就會重試；回傳最後一次嘗試的結果。resolver 內拋出的 Throwable 會被降級為一個攜帶例外訊息的 Failed 步驟結果，訊息為空時則為 Unknown error。因此 execute() 一律回傳 PipelineResult；它永遠不會將 resolver 失敗向外傳播。

沒有註冊 resolver 的步驟型別會產生一個帶明確訊息的 Failed 步驟結果；整個執行不會中止。當 stopOnError 為 true（預設）時，執行會在第一個失敗步驟停止，管線狀態為 Failed。為 false 時，執行會繼續，只要有任何步驟失敗，最終狀態即為 Failed，否則為 Completed。

Pack 能力閘門

在任何 resolver 派發之前，每一個受 Pack 閘控的步驟（Redact、Extract、OcrOverlay）都會對照注入的 CapabilityResolverInterface 進行檢查。閘門採 fail-closed：缺少 resolver、回答為 false，或未對應的能力代碼，都會拒絕該步驟。拒絕會產生一個 Failed 步驟結果，其錯誤攜帶 SPEC-LIC-001 代碼、步驟型別與所需能力。閘控拒絕不消耗任何重試次數，並回報 0.0 的執行時間。resolver 的實作只有在確實持有授權時才可回傳 true，且不得拋出。

結果彙整

PipelineResult 會回報 manifest ID、整體狀態、依執行順序排列的每步驟結果、以毫秒為單位的總執行時間，以及步驟的總數、已完成數與失敗數。stepsTotal 會計入 manifest 中的每一個步驟，包含被 resume 略過或在停止後未觸及的步驟；stepsCompleted 與 stepsFailed 只計入已執行的步驟。

邊界案例與失敗模式

• 執行器設計用於在 job worker 內以非同步方式執行。內嵌使用會讓呼叫端在整個管線執行期間被阻塞。
• 全域逾時是一個步驟之間的檢查。單一長時間步驟可能超出預算；沒有任何步驟會在執行途中被中斷。
• Resume 只在同一次執行內略過步驟。它不會從任何儲存還原輸出；帶快取輸出的跨執行 resume 尚未實作。
• 直接建構 PipelineStep 會將每一種步驟型別的輸出型別都預設為 PDF。請使用 builder，或明確傳入輸出型別，讓 inspect 與 extract 步驟宣告 JSON 輸出，使邊驗證維持有意義。
• 訊息為空的 resolver 例外，在步驟結果中會被正規化為 Unknown error。
• 由閘門或缺少 resolver 所產生的 Failed 步驟結果會回報 0.0 的執行時間。
• PipelineResult::getStepResult() 對於未知 ID 以及被 resume 或停止略過的步驟都會回傳 null；可透過 stepsTotal 與結果清單長度的差異來區分。
• 此模組不執行任何密碼學運算，也未定義任何 FIPS 專屬行為。sign 步驟的 FIPS 態勢由簽署模組管轄，而非由管線管轄。

一致性

管線本身不進行任何格式一致性工作。每一個產出物的一致性，由執行步驟背後的模組——簽署、最佳化、轉換等等——負責，並記錄於那些模組的參考頁面上。本頁不主張任何外部條款識別碼；每一項陳述皆以產品原始碼為依據。NextPDF 不作任何認證主張。

開發註記

• 模組原始碼標註 @since 2.2.0；本參考記錄的是 nextpdf/pro 3.1.0 出貨時的介面。
• 所有類別皆為 final；manifest、options、step 與 result 型別都是 readonly 值物件。請建構新實例，而非變更既有實例。
• StepResolverInterface 與 StepResolverRegistry 為 @internal。步驟 resolver 僅限內建；此版本不支援使用者自訂的步驟處理器。
• CapabilityResolverInterface 是公開的授權接縫。實作必須採預設拒絕（deny-by-omission），且不得預設允許。
• 此 PHP 執行器是 manifest 驗證與循序執行的路徑；正式環境部署可透過 sidecar 派發以進行平行協作。無論如何，PHP 路徑上的能力閘門都是獨立地 fail-closed。
• 內部機制細節保留在原始碼儲存庫的內部文件中，不在本手冊範圍內。

出版界線

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

另請參閱

• Output Pipeline — 提供工作流程指引的功能頁面。
• Output Pipeline — NextPDF Enterprise 深入參考 — 跨 manifest 的批次協作。
• Document — 深入參考
• Accelerator — 深入參考