Output Pipeline — Riferimento approfondito

In breve

Questa pagina è il riferimento approfondito per la superficie pubblica di NextPDF\Pro\OutputPipeline. Copre la costruzione e la validazione del manifest, l’ordine di esecuzione topologico, la semantica di retry e timeout, il comportamento di resume e il gate fail-closed delle capability dei Pack. Indica parametri, valori predefiniti e modalità di errore per ogni simbolo pubblico. Per indicazioni sul workflow, leggere prima la pagina della funzionalità Output Pipeline.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

L’executor e sette dei dieci tipi di step non prevedono alcun flag per funzionalità. Tre tipi di step richiedono inoltre una capability di un Pack:

Tipo di step	Valore nel manifest	Capability richiesta	Pack
Redazione	redact	pack.privacy.redact	Privacy Pack
Estrazione	extract	pack.intelligence.extract	Intelligence Pack
Overlay OCR	ocr_overlay	pack.intelligence.searchable_pdf	Intelligence Pack

Il gate viene applicato in fase di esecuzione, fail-closed, prima che lo step raggiunga il proprio resolver. Uno step gated privo di licenza produce un risultato di step Failed che riporta il codice SPEC-LIC-001 e la capability richiesta; il resolver non viene mai invocato. Una pipeline senza un capability resolver iniettato rifiuta ogni step gated.

Superficie API pubblica

composer require nextpdf/pro:^3

Il metapackage nextpdf/premium installa il codice di nextpdf/pro; questo modulo risiede nel namespace NextPDF\Pro\OutputPipeline.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	Collega il registro dei resolver integrati e la sorgente di entitlement opzionale	PipelineExecutor	Nulla dichiarato	Un capability resolver null rifiuta ogni step gated dei Pack
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	Esegue gli step in ordine topologico e aggrega i risultati	PipelineResult	Nulla dichiarato; i fallimenti dei resolver vengono catturati come risultati di step Failed	Progettato per essere eseguito all’interno di un job worker asincrono
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	Valida il grafo degli step in fase di costruzione	PipelineManifest	InvalidArgumentException per lista di step vuota, ID di step duplicati, dipendenze sconosciute, cicli, mismatch del tipo di output o step di resume mancante; OverflowException oltre 10 000 step	Tutta la validazione si completa prima di qualsiasi esecuzione
PipelineManifest::topologicalOrder	nessuno	Ordina gli step con le dipendenze prima dei dipendenti	list<PipelineStep>	Nulla dichiarato	Deterministico per un dato manifest
PipelineManifest::getStep	string $stepId	Ricerca lineare per ID di step	?PipelineStep	Nulla dichiarato	null per un ID sconosciuto
PipelineManifest::rootSteps	nessuno	Restituisce gli step privi di dipendenze	list<PipelineStep>	Nulla dichiarato	Gli step root vengono eseguiti per primi
PipelineManifestBuilder::create	string $manifestId	Avvia un nuovo builder	self	Nulla dichiarato	Il costruttore è privato; questo è l’unico punto di ingresso
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	Aggiunge uno step; un tipo di output null viene dedotto dal tipo di step	self	Nulla dichiarato	La validazione è rinviata a build()
PipelineManifestBuilder::stopOnError	bool $stop = true	Imposta l’arresto al primo fallimento	self	Nulla dichiarato	Valore predefinito true
PipelineManifestBuilder::maxRetries	int $retries	Imposta il limite massimo di retry per step	self	Nulla dichiarato	Valore predefinito 0 (nessun retry)
PipelineManifestBuilder::timeout	int $timeoutMs	Imposta il timeout globale della pipeline	self	Nulla dichiarato	0 disabilita il timeout
PipelineManifestBuilder::resumeFrom	string $stepId	Imposta il punto di resume	self	Nulla dichiarato	Lo step deve esistere al momento di build()
PipelineManifestBuilder::build	nessuno	Costruisce il manifest validato	PipelineManifest	Come PipelineManifest::__construct	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	Opzioni di esecuzione immutabili	PipelineOptions	Nulla dichiarato	Value object readonly
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	Definizione di step immutabile	PipelineStep	Nulla dichiarato	La costruzione diretta imposta come predefinito il tipo di output PDF per ogni tipo
PipelineStep::isRoot	nessuno	True quando lo step non ha dipendenze	bool	Nulla dichiarato	—
PipelineStepType (enum)	—	Dieci case string-backed: generate, merge, split, inspect, compress, sign, convert, più i gated redact, extract, ocr_overlay	—	—	Un case per ciascuna operazione integrata
PipelineStepType::requiresPack	nessuno	True per Redact, Extract e OcrOverlay	bool	Nulla dichiarato	Tutti gli altri case restituiscono false
PipelineStepType::requiredCapability	nessuno	Mappa i case gated ai rispettivi codici di capability	?string	Nulla dichiarato	null per i case non gated
PipelineStatus (enum)	—	Cinque case: pending, running, completed, failed, cancelled	—	—	Condiviso dai risultati di pipeline e di step
PipelineStatus::isTerminal	nessuno	True per Completed, Failed e Cancelled	bool	Nulla dichiarato	Pending e Running non sono terminali
StepOutputType (enum)	—	Tre case: pdf, json, metadata	—	—	Guida la validazione degli edge in fase di build
StepOutputType::forStepType	PipelineStepType $stepType	Tipo di output predefinito per un tipo di step	self	Nulla dichiarato	Inspect ed Extract mappano su JSON; tutti gli altri tipi mappano su PDF
StepOutputType::isCompatibleWith	self $expectedInput	True per una corrispondenza dello stesso tipo o per un output PDF	bool	Nulla dichiarato	Helper; PDF è l’input universale
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	Contesto in-memory per singola esecuzione	PipelineContext	Nulla dichiarato	Nessun TTL, scadenza, persistenza o backing store
PipelineContext::setStepResult / ::getStepResult	string $stepId (+ StepResult in set)	Registra o legge un risultato di step	void / ?StepResult	Nulla dichiarato	null per uno step non ancora eseguito
PipelineContext::setStepOutput / ::getStepOutput	string $stepId (+ mixed in set)	Memorizza o legge un output intermedio	void / mixed	Nulla dichiarato	null per un output mancante
PipelineContext::hasStepResult	string $stepId	Indica se uno step è già stato eseguito	bool	Nulla dichiarato	Supporta le verifiche di resume
PipelineContext::allStepResults	nessuno	Tutti i risultati registrati finora	array<string, StepResult>	Nulla dichiarato	Indicizzato per ID di step
PipelineContext::isResume	nessuno	Indica se l’esecuzione riprende da uno step	bool	Nulla dichiarato	—
PipelineResult::isSuccess	nessuno	True solo per lo stato complessivo Completed	bool	Nulla dichiarato	Il risultato è prodotto dall’executor
PipelineResult::getStepResult	string $stepId	Trova un risultato di step per ID	?StepResult	Nulla dichiarato	null per step saltati o sconosciuti
PipelineResult::failedSteps	nessuno	Filtra i risultati di step falliti	list<StepResult>	Nulla dichiarato	Lista vuota in caso di successo completo
StepResult::isSuccess	nessuno	True solo per lo stato di step Completed	bool	Nulla dichiarato	Riporta stepId, type, status, durationMs, error, output
CapabilityResolverInterface::hasCapability	string $capability	Test affermativo di entitlement per un singolo codice di capability	bool	Non deve sollevare eccezioni	Deny-by-omission: false per codici sconosciuti, scaduti o non mappati

Firme dei punti di ingresso

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;
}

Contratto di comportamento

Validazione del manifest

La validazione avviene nel costruttore di PipelineManifest, prima di qualsiasi esecuzione. Nell’ordine: la lista degli step deve essere non vuota; il numero di step è limitato a 10 000, convertendo catene di dipendenze deliberatamente profonde in un OverflowException catturabile anziché in un esaurimento nativo dello stack; gli ID degli step devono essere univoci; ogni riferimento dependsOn deve risolversi; il grafo delle dipendenze deve essere aciclico; i tipi di output devono essere compatibili; uno step di resume dichiarato deve esistere. Ogni violazione solleva InvalidArgumentException con un messaggio specifico.

Il controllo del tipo di output si applica agli step il cui tipo mappa su output PDF: ogni dipendenza di uno step di questo tipo deve a sua volta produrre output PDF. Gli edge di dipendenza verso tipi di step che producono JSON (inspect, extract) non sono sottoposti a controllo di tipo in questa release.

Ordine di esecuzione, resume e timeout

execute($manifest, $variables) costruisce un nuovo PipelineContext, calcola l’ordinamento topologico ed esegue gli step sequenzialmente in quell’ordine. Con un punto di resume impostato, gli step precedenti vengono saltati finché non si raggiunge lo step indicato. I predecessori saltati non vengono rieseguiti e i loro output non vengono ripristinati: il contesto è per singola esecuzione e in-memory, quindi uno step ripreso che legge l’output di un predecessore saltato osserva null.

Il timeout globale, quando positivo, viene valutato tra uno step e l’altro, prima dell’avvio di ciascuno step. Alla scadenza lo stato della pipeline diventa Failed e gli step rimanenti non vengono avviati. Uno step già in esecuzione non viene mai interrotto a metà esecuzione, quindi un singolo step lungo può superare il budget.

Retry e cattura dei fallimenti

Ogni step riceve al massimo maxRetries + 1 tentativi. Un tentativo riuscito ritorna immediatamente. Qualsiasi tentativo fallito — un risultato Failed dal resolver o un Throwable sollevato — viene ritentato finché restano tentativi; viene restituito il risultato dell’ultimo tentativo. Un Throwable sollevato all’interno di un resolver viene degradato a un risultato di step Failed che riporta il messaggio dell’eccezione, oppure Unknown error quando il messaggio è vuoto. execute() restituisce pertanto sempre un PipelineResult; non propaga mai un fallimento del resolver.

Un tipo di step privo di un resolver registrato produce un risultato di step Failed con un messaggio esplicito; l’esecuzione non viene interrotta. Con stopOnError a true (il valore predefinito), l’esecuzione si arresta al primo step fallito e lo stato della pipeline è Failed. Con il valore false, l’esecuzione prosegue e lo stato finale è Failed se un qualsiasi step è fallito, altrimenti Completed.

Gate delle capability dei Pack

Prima di qualsiasi dispatch al resolver, ogni step gated dei Pack (Redact, Extract, OcrOverlay) viene verificato rispetto al CapabilityResolverInterface iniettato. Il gate è fail-closed: un resolver mancante, una risposta false o un codice di capability non mappato rifiutano tutti lo step. Il rifiuto produce un risultato di step Failed il cui errore riporta il codice SPEC-LIC-001, il tipo di step e la capability richiesta. Un rifiuto gated non consuma alcun tentativo di retry e riporta una durata di 0.0. Le implementazioni del resolver devono restituire true solo per un entitlement effettivamente posseduto e non devono sollevare eccezioni.

Aggregazione dei risultati

PipelineResult riporta l’ID del manifest, lo stato complessivo, i risultati per ciascuno step in ordine di esecuzione, la durata totale in millisecondi e il numero totale, completato e fallito degli step. stepsTotal conta ogni step del manifest, inclusi gli step saltati dal resume o non raggiunti dopo un arresto; stepsCompleted e stepsFailed contano solo gli step eseguiti.

Casi limite e modalità di errore

• L’executor è progettato per l’esecuzione asincrona all’interno di un job worker. L’uso inline blocca il chiamante per l’intera durata della pipeline.
• Il timeout globale è una verifica tra uno step e l’altro. Un singolo step lungo può superare il budget; nessuno step viene interrotto a metà esecuzione.
• Il resume salta gli step solo all’interno della stessa esecuzione. Non ripristina output da alcun archivio; il resume cross-run con output in cache non è implementato.
• Costruire PipelineStep direttamente imposta come predefinito il tipo di output PDF per ogni tipo di step. Usare il builder, oppure passare esplicitamente il tipo di output, affinché gli step inspect ed extract dichiarino output JSON e la validazione degli edge resti significativa.
• Un’eccezione di resolver con messaggio vuoto viene normalizzata in Unknown error nel risultato dello step.
• I risultati di step Failed prodotti dal gate o da un resolver mancante riportano una durata di 0.0.
• PipelineResult::getStepResult() restituisce null sia per ID sconosciuti sia per step saltati dal resume o da un arresto; distinguere tramite stepsTotal rispetto alla lunghezza della lista dei risultati.
• Questo modulo non esegue alcuna operazione crittografica e non definisce alcun comportamento specifico per FIPS. La postura FIPS per lo step sign è governata dal modulo di firma, non dalla pipeline.

Conformità

La pipeline non svolge alcun lavoro di conformità di formato in proprio. La conformità di ciascun artefatto prodotto è di competenza del modulo dietro lo step in esecuzione — firma, ottimizzazione, conversione e così via — ed è documentata nelle pagine di riferimento di tali moduli. Questa pagina non asserisce alcun identificatore di clausola esterno; ogni affermazione è fondata sul codice sorgente del prodotto. NextPDF non avanza alcuna rivendicazione di certificazione.

Note di sviluppo

• Il codice sorgente del modulo riporta @since 2.2.0; questo riferimento documenta la superficie come rilasciata in nextpdf/pro 3.1.0.
• Tutte le classi sono final; i tipi manifest, options, step e result sono value object readonly. Costruire nuove istanze anziché mutarle.
• StepResolverInterface e StepResolverRegistry sono @internal. I resolver di step sono esclusivamente integrati; gli handler di step personalizzati definiti dall’utente non sono supportati in questa release.
• CapabilityResolverInterface è il punto di estensione pubblico per l’entitlement. Le implementazioni devono essere deny-by-omission e non devono consentire per impostazione predefinita.
• Questo executor PHP è il percorso di validazione del manifest e di esecuzione sequenziale; i deployment di produzione possono effettuare il dispatch tramite il sidecar per l’orchestrazione parallela. Il gate delle capability sul percorso PHP è comunque fail-closed in modo indipendente.
• I dettagli del meccanismo interno restano nella documentazione interna del repository sorgente e sono fuori ambito per questo manuale.

Confine di pubblicazione

Questa pagina documenta esclusivamente il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.

Vedere anche

• Output Pipeline — la pagina della funzionalità per indicazioni sul workflow.
• Output Pipeline — Riferimento approfondito NextPDF Enterprise — orchestrazione batch tra manifest.
• Document — Riferimento approfondito
• Accelerator — Riferimento approfondito