Pipeline di output

In breve

La Output Pipeline esegue un manifest dichiarativo di fasi PDF in ordine di dipendenza, con retry per ciascuna fase e un’opzione di arresto in caso di errore. Alcuni tipi di fase richiedono una capability aggiuntiva degli Enterprise Pack.

Disponibilità e licenze

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’esecutore della pipeline in sé fa parte dell’edizione Pro. Tre tipi di fase richiedono in aggiunta una capability denominata degli Enterprise Pack: la fase di oscuramento richiede una capability del Privacy Pack, mentre le fasi di estrazione e di OCR-overlay richiedono capability dell’Intelligence Pack. Una fase soggetta a gate e non licenziata fallisce fail-closed in fase di esecuzione — produce un risultato di fase fallita e il suo resolver non viene mai invocato — anziché interrompere l’intera esecuzione.

Installazione

composer require nextpdf/pro:^3

Il codice risiede sotto il namespace NextPDF\Pro\OutputPipeline.

Panoramica concettuale

PipelineExecutor prende un PipelineManifest, ordina le fasi in ordine topologico e indirizza ciascuna fase a un resolver registrato nello StepResolverRegistry. Gli output delle fasi sono memorizzati in un PipelineContext per le fasi a valle. L’esecutore applica un timeout globale, supporta i retry per ciascuna fase e può riprendere da una fase denominata. È progettato per essere eseguito all’interno di un job worker asincrono, non direttamente da un gestore di richiesta.

I tipi di fase integrati includono generate, merge, split, inspect, compress, sign e convert. I tipi di fase di oscuramento, estrazione e OCR-overlay sono soggetti a licenza per capability e si mappano sulle capability degli Enterprise Pack.

Perché funziona così

L’esecutore si occupa solo di orchestrazione. Ordina le fasi, applica il gate di licenza e indirizza ciascuna a un resolver registrato, ma non esegue di per sé alcun lavoro sul PDF. Questa separazione consente a uno stesso manifest di essere eseguito sia attraverso questo percorso PHP sequenziale sia attraverso un worker fuori banda che indirizza le fasi in parallelo, senza alcuna modifica al codice chiamante. La progettazione mira a un job worker asincrono anziché a un gestore di richiesta, perché una pipeline a più fasi supera abitualmente il budget di una richiesta e una coda scala il throughput aggiungendo worker. Il timeout globale viene verificato tra le fasi per lo stesso motivo: un’intera fase è l’unità di lavoro affidata a un resolver e l’orchestratore resta fuori dall’esecuzione di quel resolver. Le failure emergono come valori StepResult per ciascuna fase anziché come eccezioni sollevate, così una singola fase fallita non fa mai collassare il PipelineResult aggregato riportato dal worker.

Contesto di progettazione: Generazione di documenti ad alto volume.

Contratto di comportamento

• execute($manifest, $variables) restituisce un risultato con lo stato complessivo, i risultati per ciascuna fase, la durata e i conteggi delle fasi completate e fallite.
• Le fasi vengono eseguite in ordine topologico; un resolver mancante per un tipo di fase produce una fase fallita con un messaggio chiaro.
• PipelineOptions::$stopOnError arresta l’esecuzione al primo errore; altrimenti l’esecuzione prosegue e lo stato finale riflette eventuali errori.
• Il timeout globale, quando impostato, fa fallire la pipeline se viene superato prima dell’avvio della fase successiva.
• I retry per ciascuna fase sono limitati dal massimo configurato; vengono ritentate solo le failure non terminali.
• La ripresa da una fase salta le fasi precedenti finché non viene raggiunta la fase denominata.
• I tipi di fase soggetti a gate per capability falliscono fail-closed in fase di esecuzione con un codice di errore di licenza quando la capability del Pack richiesta è assente; il resolver non viene mai invocato.

Esempio di codice — Avvio rapido

Quanto segue rispecchia l’API pubblica documentata. Il repository non include un esempio eseguibile per questo modulo.

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$result = (new PipelineExecutor($stepResolverRegistry))->execute($manifest);

Esempio di codice — Produzione

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$executor = new PipelineExecutor($stepResolverRegistry);

// Invoke from an async job worker, not a request handler.
$result = $executor->execute($manifest, ['customerName' => 'Acme']);

if ($result->status !== \NextPDF\Pro\OutputPipeline\PipelineStatus::Completed) {
    foreach ($result->stepResults as $stepResult) {
        // Inspect per-step error detail.
    }
}

Casi limite e insidie

• La pipeline è destinata a essere eseguita in modo asincrono tramite un sistema di job. Eseguirla in linea blocca il chiamante per l’intera durata della pipeline.
• Un tipo di fase senza resolver registrato fa fallire quella fase anziché interrompere l’intera pipeline (a meno che non sia impostato l’arresto in caso di errore).
• Il timeout globale viene verificato tra le fasi, non a metà fase; una fase di lunga durata può sforare il budget prima che scatti la verifica.

Prestazioni

La durata totale è la somma delle durate delle fasi più l’overhead dei retry. Il timeout globale limita il tempo di esecuzione nel caso peggiore. Non esiste una cifra di throughput pubblicata; il costo della pipeline è dominato dalle fasi che si includono. Misurare con manifest rappresentativi.

Note sulla sicurezza

L’esecutore passa i documenti di input e le variabili ai resolver delle fasi; trattarli come non attendibili e convalidarli all’interno di ciascun resolver. Le fasi soggette a gate per capability falliscono fail-closed quando non licenziate. L’esecutore non registra alcun contenuto del documento.

Conformità

L’esecutore non esegue di per sé alcun lavoro di conformità di formato; la conformità dipende dai singoli resolver delle fasi (generate, merge, split, sign, convert). Il corpus RAG non era disponibile al momento della stesura, quindi questa pagina non asserisce alcun identificatore di clausola esterno.

Nota sul confine Enterprise

Enterprise aggiunge le capability dei Pack che sbloccano i tipi di fase soggetti a gate (oscuramento, estrazione, OCR overlay) a livello di comportamento. Senza quei Pack la pipeline esegue comunque ogni fase non soggetta a gate. I dettagli interni dei Pack sono fuori ambito in questa pagina.

Fallback / alternativa di Core

Senza Pro, orchestrare le operazioni sui PDF in modo imperativo con le API di NextPDF Core; il manifest dichiarativo, l’ordinamento per dipendenza e i retry sono aggiunte di Pro..

Confine di pubblicazione

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

Vedere anche

• Output Pipeline — Riferimento approfondito
• Document
• Merge
• Accelerator