Output Pipeline — Diepe referentie

In het kort

Deze pagina is de diepe referentie voor het openbare oppervlak van NextPDF\Pro\OutputPipeline. Ze behandelt manifestconstructie en -validatie, de topologische uitvoeringsvolgorde, de retry- en time-outsemantiek, het resume-gedrag en de fail-closed pack-capability-gate. Ze benoemt de parameters, defaults en faalmodi voor elk publiek symbool. Lees eerst de capability-pagina van de Output Pipeline voor workflowbegeleiding.

Beschikbaarheid en licentiëring

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

De executor en zeven van de tien steptypen dragen geen per-feature-flag. Drie steptypen vereisen daarnaast een Pack-capability:

Steptype	Manifestwaarde	Vereiste capability	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

De gate wordt tijdens de uitvoering afgedwongen, fail-closed, voordat de step zijn resolver bereikt. Een ongelicentieerde gated step levert een Failed stepresultaat op met de SPEC-LIC-001-code en de vereiste capability; de resolver wordt nooit aangeroepen. Een pijplijn zonder geïnjecteerde capability-resolver wijst elke gated step af.

Publiek API-oppervlak

composer require nextpdf/pro:^3

De nextpdf/premium-metapackage installeert de nextpdf/pro-code; deze module leeft onder de namespace NextPDF\Pro\OutputPipeline.

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	Bindt de ingebouwde resolver registry en de optionele entitlementbron	PipelineExecutor	Niets gedeclareerd	Een null capability-resolver wijst elke pack-gated step af
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	Voert steps uit in topologische volgorde en aggregeert de resultaten	PipelineResult	Niets gedeclareerd; resolver-fouten worden vastgelegd als Failed stepresultaten	Ontworpen om binnen een asynchrone job worker te draaien
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	Valideert de stepgraaf bij constructie	PipelineManifest	InvalidArgumentException bij een lege steplijst, dubbele step-ID’s, onbekende afhankelijkheden, cycli, mismatch van outputtype of een ontbrekende resume-step; OverflowException boven 10 000 steps	Alle validatie wordt voltooid vóór enige uitvoering
PipelineManifest::topologicalOrder	geen	Ordent steps met afhankelijkheden vóór afhankelijken	list<PipelineStep>	Niets gedeclareerd	Deterministisch voor een gegeven manifest
PipelineManifest::getStep	string $stepId	Lineaire lookup op step-ID	?PipelineStep	Niets gedeclareerd	null voor een onbekende ID
PipelineManifest::rootSteps	geen	Retourneert de steps zonder afhankelijkheden	list<PipelineStep>	Niets gedeclareerd	Root-steps draaien eerst
PipelineManifestBuilder::create	string $manifestId	Start een nieuwe builder	self	Niets gedeclareerd	De constructor is private; dit is de enige ingang
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	Voegt een step toe; een null outputtype wordt afgeleid uit het steptype	self	Niets gedeclareerd	Validatie wordt uitgesteld tot build()
PipelineManifestBuilder::stopOnError	bool $stop = true	Stelt halt-bij-eerste-fout in	self	Niets gedeclareerd	Standaard true
PipelineManifestBuilder::maxRetries	int $retries	Stelt het retry-plafond per step in	self	Niets gedeclareerd	Standaard 0 (geen retries)
PipelineManifestBuilder::timeout	int $timeoutMs	Stelt de globale pijplijn-time-out in	self	Niets gedeclareerd	0 schakelt de time-out uit
PipelineManifestBuilder::resumeFrom	string $stepId	Stelt het resume-punt in	self	Niets gedeclareerd	De step moet bestaan op het moment van build()
PipelineManifestBuilder::build	geen	Construeert het gevalideerde manifest	PipelineManifest	Zoals PipelineManifest::__construct	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	Immutable uitvoeringsopties	PipelineOptions	Niets gedeclareerd	Readonly value-object
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	Immutable stepdefinitie	PipelineStep	Niets gedeclareerd	Directe constructie zet het outputtype op PDF voor elk type
PipelineStep::isRoot	geen	True wanneer de step geen afhankelijkheden heeft	bool	Niets gedeclareerd	—
PipelineStepType (enum)	—	Tien string-backed cases: generate, merge, split, inspect, compress, sign, convert, plus de gated redact, extract, ocr_overlay	—	—	Eén case per ingebouwde operatie
PipelineStepType::requiresPack	geen	True voor Redact, Extract en OcrOverlay	bool	Niets gedeclareerd	Alle andere cases retourneren false
PipelineStepType::requiredCapability	geen	Mapt gated cases naar hun capability-codes	?string	Niets gedeclareerd	null voor niet-gated cases
PipelineStatus (enum)	—	Vijf cases: pending, running, completed, failed, cancelled	—	—	Gedeeld door pijplijn- en stepresultaten
PipelineStatus::isTerminal	geen	True voor Completed, Failed en Cancelled	bool	Niets gedeclareerd	Pending en Running zijn niet-terminaal
StepOutputType (enum)	—	Drie cases: pdf, json, metadata	—	—	Stuurt de edge-validatie bij build-time aan
StepOutputType::forStepType	PipelineStepType $stepType	Standaard outputtype voor een steptype	self	Niets gedeclareerd	Inspect en Extract mappen naar JSON; alle andere types mappen naar PDF
StepOutputType::isCompatibleWith	self $expectedInput	True bij een match van hetzelfde type of een PDF-output	bool	Niets gedeclareerd	Helper; PDF is de universele input
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	In-memory context per run	PipelineContext	Niets gedeclareerd	Geen TTL, expiry, persistentie of backing store
PipelineContext::setStepResult / ::getStepResult	string $stepId (+ StepResult bij set)	Legt een stepresultaat vast of leest het	void / ?StepResult	Niets gedeclareerd	null voor een nog niet uitgevoerde step
PipelineContext::setStepOutput / ::getStepOutput	string $stepId (+ mixed bij set)	Slaat een tussentijdse output op of leest die	void / mixed	Niets gedeclareerd	null voor een ontbrekende output
PipelineContext::hasStepResult	string $stepId	Of een step al is uitgevoerd	bool	Niets gedeclareerd	Ondersteunt resume-checks
PipelineContext::allStepResults	geen	Alle tot nu toe vastgelegde resultaten	array<string, StepResult>	Niets gedeclareerd	Gekoppeld op step-ID
PipelineContext::isResume	geen	Of de run hervat vanaf een step	bool	Niets gedeclareerd	—
PipelineResult::isSuccess	geen	True alleen bij een algehele Completed-status	bool	Niets gedeclareerd	Het resultaat wordt geproduceerd door de executor
PipelineResult::getStepResult	string $stepId	Vindt één stepresultaat op ID	?StepResult	Niets gedeclareerd	null voor overgeslagen of onbekende steps
PipelineResult::failedSteps	geen	Filtert de mislukte stepresultaten	list<StepResult>	Niets gedeclareerd	Lege lijst bij volledig succes
StepResult::isSuccess	geen	True alleen bij stepstatus Completed	bool	Niets gedeclareerd	Draagt stepId, type, status, durationMs, error, output
CapabilityResolverInterface::hasCapability	string $capability	Bevestigende entitlementtest voor één capability-code	bool	Mag niet werpen	Deny-by-omission: false voor onbekende, verlopen of niet-gemapte codes

Entry-pointsignaturen

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

Gedragscontract

Manifestvalidatie

Validatie draait in de PipelineManifest-constructor, vóór enige uitvoering. In volgorde: de steplijst moet niet-leeg zijn; het aantal steps is begrensd op 10 000, wat adversarieel diepe afhankelijkheidsketens omzet in een opvangbare OverflowException in plaats van native stack exhaustion; step-ID’s moeten uniek zijn; elke dependsOn-referentie moet oplosbaar zijn; de afhankelijkheidsgraaf moet acyclisch zijn; outputtypen moeten compatibel zijn; een gedeclareerde resume-step moet bestaan. Elke overtreding werpt InvalidArgumentException met een specifieke melding.

De outputtype-controle geldt voor steps waarvan het type naar PDF-output mapt: elke afhankelijkheid van zo’n step moet zelf PDF-output produceren. Afhankelijkheidsedges naar JSON-producerende steptypen (inspect, extract) worden in deze release niet op type gecontroleerd.

Uitvoeringsvolgorde, resume en time-out

execute($manifest, $variables) bouwt een verse PipelineContext, berekent de topologische volgorde en draait de steps sequentieel in die volgorde. Met een ingesteld resume-punt worden eerdere steps overgeslagen totdat de genoemde step is bereikt. Overgeslagen voorgangers worden niet opnieuw uitgevoerd en hun outputs worden niet hersteld: de context is per-run en in-memory, dus een hervatte step die de output van een overgeslagen voorganger leest, ziet null.

De globale time-out wordt, indien positief, tussen steps geëvalueerd, voordat elke step start. Bij verstrijken wordt de pijplijnstatus Failed en starten de resterende steps niet. Een step die al draait, wordt nooit halverwege de uitvoering onderbroken, dus één lange step kan het budget overschrijden.

Retries en foutvastlegging

Elke step krijgt hoogstens maxRetries + 1 pogingen. Een geslaagde poging retourneert onmiddellijk. Elke mislukte poging — een Failed resultaat van de resolver of een geworpen Throwable — wordt opnieuw geprobeerd zolang er pogingen resteren; het resultaat van de laatste poging wordt geretourneerd. Een Throwable die binnen een resolver wordt geworpen, wordt afgezwakt tot een Failed stepresultaat met de exception-melding, of Unknown error wanneer de melding leeg is. execute() retourneert daarom altijd een PipelineResult; het propageert nooit een resolver-fout.

Een steptype zonder geregistreerde resolver levert een Failed stepresultaat op met een expliciete melding; de run wordt niet afgebroken. Met stopOnError op true (de default) stopt de uitvoering bij de eerste mislukte step en is de pijplijnstatus Failed. Met false gaat de uitvoering door en is de uiteindelijke status Failed als een step mislukte, anders Completed.

Pack-capability-gate

Vóór elke resolver-dispatch wordt elke pack-gated step (Redact, Extract, OcrOverlay) getoetst aan de geïnjecteerde CapabilityResolverInterface. De gate is fail-closed: een ontbrekende resolver, een false-antwoord of een niet-gemapte capability-code wijzen de step alle af. Afwijzing produceert een Failed stepresultaat waarvan de error de SPEC-LIC-001-code, het steptype en de vereiste capability draagt. Een gated afwijzing verbruikt geen retry-poging en rapporteert een duur van 0.0. Implementaties van de resolver mogen alleen true retourneren voor een bevestigend gehouden entitlement en mogen niet werpen.

Resultaataggregatie

PipelineResult rapporteert de manifest-ID, de algehele status, de resultaten per step in uitvoeringsvolgorde, de totale duur in milliseconden en de totale, voltooide en mislukte stepaantallen. stepsTotal telt elke step in het manifest, inclusief steps die door resume worden overgeslagen of onbereikt blijven na een halt; stepsCompleted en stepsFailed tellen alleen uitgevoerde steps.

Randgevallen en faalmodi

• De executor is ontworpen voor asynchrone uitvoering binnen een job worker. Inline gebruik blokkeert de caller gedurende de volledige pijplijnduur.
• De globale time-out is een controle tussen steps. Eén lange step kan het budget overschrijden; geen enkele step wordt halverwege onderbroken.
• Resume slaat steps alleen binnen dezelfde uitvoering over. Het herstelt geen outputs uit enige store; cross-run resume met gecachte outputs is niet geïmplementeerd.
• PipelineStep direct construeren zet het outputtype op PDF voor elk steptype. Gebruik de builder, of geef het outputtype expliciet mee, zodat inspect- en extract-steps JSON-output declareren en de edge-validatie zinvol blijft.
• Een resolver-exception met een lege melding wordt in het stepresultaat genormaliseerd tot Unknown error.
• Failed stepresultaten die door de gate of door een ontbrekende resolver worden geproduceerd, rapporteren een duur van 0.0.
• PipelineResult::getStepResult() retourneert null zowel voor onbekende ID’s als voor steps die door resume of een halt zijn overgeslagen; onderscheid ze via stepsTotal versus de lengte van de resultatenlijst.
• Deze module voert geen cryptografische bewerkingen uit en definieert geen FIPS-specifiek gedrag. De FIPS-houding voor de sign-step wordt beheerd door de signing-module, niet door de pijplijn.

Conformiteit

De pijplijn voert geen eigen formaatconformiteitswerk uit. De conformiteit van elk geproduceerd artefact is eigendom van de module achter de uitvoerende step — signing, optimalisatie, conversie enzovoort — en wordt gedocumenteerd op de referentiepagina’s van die modules. Deze pagina claimt geen externe clausule-identifiers; elke uitspraak is gegrond in de productbron. NextPDF doet geen certificeringsclaim.

Ontwikkelnotities

• De modulebron draagt @since 2.2.0; deze referentie documenteert het oppervlak zoals geleverd in nextpdf/pro 3.1.0.
• Alle klassen zijn final; de manifest-, options-, step- en resultaattypen zijn readonly value-objecten. Construeer nieuwe instanties in plaats van te muteren.
• StepResolverInterface en StepResolverRegistry zijn @internal. Stepresolvers zijn alleen ingebouwd; door de gebruiker gedefinieerde custom stephandlers worden in deze release niet ondersteund.
• CapabilityResolverInterface is de publieke entitlement-naad. Implementaties moeten deny-by-omission zijn en mogen niet default-allow zijn.
• Deze PHP-executor is het pad voor manifestvalidatie en sequentiële uitvoering; productiedeployments kunnen via de sidecar dispatchen voor parallelle orkestratie. De capability-gate op het PHP-pad is hoe dan ook onafhankelijk fail-closed.
• Detail over interne mechanismen blijft in de interne documentatie van de bronrepository en valt buiten de scope van deze handleiding.

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 de scope.

Zie ook

• Output Pipeline — de capability-pagina voor workflowbegeleiding.
• Output Pipeline — NextPDF Enterprise diepe referentie — batch-orkestratie over manifesten heen.
• Document — Diepe referentie
• Accelerator — Diepe referentie