Pro editie

Output Pipeline

In het kort

De Output Pipeline draait een declaratief manifest van PDF-stappen in afhankelijkheidsvolgorde, met per-stap retries en een stop-on-error-optie. Sommige staptypen vereisen een aanvullende Enterprise Pack-capaciteit.

Beschikbaarheid en licenties

Deze functie wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een license-envelope op Pro-niveau. Een deployment zonder die entitlement laadt de klassen van de functie niet. Vergelijk edities en vraag een licentie aan.

De pipeline-executor zelf maakt deel uit van de Pro-editie. Drie staptypen vereisen daarnaast een benoemde Enterprise Pack-capaciteit: de redactiestap vereist een Privacy Pack-capaciteit, en de extractie- en OCR-overlay-stappen vereisen Intelligence Pack-capaciteiten. Een niet-gelicentieerde gated stap faalt gesloten tijdens de uitvoering — hij levert een mislukt stapresultaat op en zijn resolver wordt nooit aangeroepen — in plaats van de hele run af te breken.

Installatie

composer require nextpdf/pro:^3

De code bevindt zich onder de namespace NextPDF\Pro\OutputPipeline.

Conceptueel overzicht

PipelineExecutor neemt een PipelineManifest, sorteert stappen in topologische volgorde en dispatcht elke stap naar een resolver die in de StepResolverRegistry is geregistreerd. Stapuitvoer wordt opgeslagen in een PipelineContext voor downstream-stappen. De executor handhaaft een globale time-out, ondersteunt per-stap retries en kan hervatten vanaf een benoemde stap. Het is ontworpen om binnen een asynchrone job-worker te draaien, niet rechtstreeks vanuit een request-handler.

Ingebouwde staptypen omvatten generate, merge, split, inspect, compress, sign en convert. De redactie-, extractie- en OCR-overlay-staptypen zijn capability-gelicentieerd en worden gemapt op Enterprise Pack-capaciteiten.

Waarom het zo werkt

De executor is uitsluitend orkestratie. Hij sorteert stappen, handhaaft de license-gate en dispatcht elke stap naar een geregistreerde resolver, maar voert zelf geen PDF-werk uit. Die scheiding laat één manifest ofwel via dit sequentiële PHP-pad draaien, ofwel via een out-of-band-worker die stappen parallel dispatcht, zonder wijziging aan de aanroepende code. Het ontwerp mikt op een asynchrone job-worker in plaats van een request-handler, omdat een multi-step-pipeline routinematig langer duurt dan een request-budget, en een queue de doorvoer schaalt door workers toe te voegen. De globale time-out wordt om dezelfde reden tussen stappen gecontroleerd: een hele stap is de werkeenheid die aan een resolver wordt overgedragen, en de orkestrator blijft buiten de run van die resolver. Fouten komen naar boven als per-stap StepResult-waarden in plaats van geworpen excepties, zodat één mislukte stap nooit het geaggregeerde PipelineResult dat de worker rapporteert laat instorten.

Ontwerpachtergrond: Documentgeneratie op grote schaal.

Gedragscontract

execute($manifest, $variables) retourneert een resultaat met de overall-status, per-stap-resultaten, duur en tellingen van voltooide en mislukte stappen.
Stappen draaien in topologische volgorde; een ontbrekende resolver voor een staptype levert een mislukte stap op met een duidelijk bericht.
PipelineOptions::$stopOnError stopt de uitvoering bij de eerste mislukking; anders gaat de uitvoering door en weerspiegelt de eindstatus eventuele mislukkingen.
De globale time-out, wanneer ingesteld, laat de pipeline falen als deze wordt overschreden voordat de volgende stap begint.
Per-stap retries worden begrensd door het geconfigureerde maximum; alleen niet-terminale mislukkingen worden opnieuw geprobeerd.
Resume-from-step slaat eerdere stappen over totdat de benoemde stap is bereikt.
Capability-gated staptypen falen gesloten tijdens de uitvoering met een licentiefoutcode wanneer de vereiste Pack-capaciteit afwezig is; de resolver wordt nooit aangeroepen.

Codevoorbeeld — Snelstart

Het volgende weerspiegelt de gedocumenteerde publieke API. De repository levert geen uitvoerbaar voorbeeld voor deze module.

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

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

Codevoorbeeld — Productie

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

Randgevallen en valkuilen

De pipeline is bedoeld om asynchroon via een job-systeem te draaien. Inline draaien blokkeert de caller voor de volledige pipeline-duur.
Een staptype zonder geregistreerde resolver laat die stap falen in plaats van de hele pipeline af te breken (tenzij stop-on-error is ingesteld).
De globale time-out wordt tussen stappen gecontroleerd, niet midden in een stap; een langlopende stap kan het budget overschrijden voordat de controle plaatsvindt.

Prestaties

De totale duur is de som van de stapdurations plus retry-overhead. De globale time-out begrenst de worst-case wandtijd. Er is geen gepubliceerd doorvoercijfer; de pipelinekosten worden gedomineerd door de stappen die je opneemt. Meet met representatieve manifesten.

Beveiligingsnotities

De executor geeft invoerdocumenten en variabelen door aan stap-resolvers; behandel ze als niet-vertrouwd en valideer binnen elke resolver. Capability-gated stappen falen gesloten wanneer ze niet-gelicentieerd zijn. De executor logt geen documentinhoud.

Conformiteit

De executor voert zelf geen formaatconformiteitswerk uit; conformiteit hangt af van de individuele stap-resolvers (generate, merge, split, sign, convert). Het RAG-corpus was tijdens het auteuren niet beschikbaar, dus deze pagina claimt geen externe clausule-identifiers.

Enterprise-grensnotitie

Enterprise voegt de Pack-capaciteiten toe die de gated staptypen (redactie, extractie, OCR-overlay) op gedragsniveau ontgrendelen. Zonder die Packs draait de pipeline nog steeds elke niet-gated stap. Pack-internals vallen hier buiten het bereik.

Core-fallback / alternatief

Zonder Pro orkestreer je PDF-bewerkingen imperatief met NextPDF Core-API’s; het declaratieve manifest, de afhankelijkheidsordening en retries zijn Pro-toevoegingen..

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten het bereik.