Pro edition

Output Pipeline

At a glance

The Output Pipeline runs a declarative manifest of PDF steps in dependency order, with per-step retries and a stop-on-error option. Some step types require an additional Enterprise Pack capability.

Availability & licensing

This capability ships in NextPDF Pro (nextpdf/pro) and activates with a Pro-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

The pipeline executor itself is part of the Pro edition. Three step types additionally require a named Enterprise Pack capability: the redaction step requires a Privacy Pack capability, and the extraction and OCR-overlay steps require Intelligence Pack capabilities. An unlicensed gated step fails closed at execution — it yields a failed step result and its resolver is never invoked — rather than aborting the whole run.

Install

composer require nextpdf/pro:^3

The code lives under the NextPDF\Pro\OutputPipeline namespace.

Conceptual overview

PipelineExecutor takes a PipelineManifest, sorts steps into topological order, and dispatches each step to a resolver registered in the StepResolverRegistry. Step outputs are stored in a PipelineContext for downstream steps. The executor enforces a global timeout, supports per-step retries, and can resume from a named step. It is designed to run inside an asynchronous job worker, not directly from a request handler.

Built-in step types include generate, merge, split, inspect, compress, sign, and convert. The redaction, extraction, and OCR-overlay step types are capability-licensed and map to Enterprise Pack capabilities.

Why it works this way

The executor is orchestration only. It sorts steps, enforces the license gate, and dispatches each to a registered resolver, but performs no PDF work itself. That split lets one manifest run either through this sequential PHP path or through an out-of-band worker that dispatches steps in parallel, with no change to calling code. The design targets an asynchronous job worker rather than a request handler, because a multi-step pipeline routinely outlives a request budget, and a queue scales throughput by adding workers. The global timeout is checked between steps for the same reason: a whole step is the unit of work handed to a resolver, and the orchestrator stays out of that resolver’s run. Failures surface as per-step StepResult values rather than thrown exceptions, so one failed step never collapses the aggregate PipelineResult the worker reports.

Design background: High-volume document generation.

Behavior contract

execute($manifest, $variables) returns a result with overall status, per-step results, duration, and counts of completed and failed steps.
Steps run in topological order; a missing resolver for a step type yields a failed step with a clear message.
PipelineOptions::$stopOnError halts execution on the first failure; otherwise execution continues and the final status reflects any failures.
The global timeout, when set, fails the pipeline if exceeded before the next step starts.
Per-step retries are bounded by the configured maximum; only non-terminal failures are retried.
Resume-from-step skips earlier steps until the named step is reached.
Capability-gated step types fail closed at execution with a license error code when the required Pack capability is absent; the resolver is never invoked.

Code sample — Quick start

The following reflects the documented public API. The repository does not ship a runnable example for this module.

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

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

Code sample — Production

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

Edge cases & gotchas

The pipeline is intended to run asynchronously through a job system. Running it inline blocks the caller for the full pipeline duration.
A step type with no registered resolver fails that step rather than aborting the whole pipeline (unless stop-on-error is set).
The global timeout is checked between steps, not mid-step; a long-running step can overrun the budget before the check fires.

Performance

Total duration is the sum of step durations plus retry overhead. The global timeout bounds worst-case wall-clock time. There is no published throughput figure; pipeline cost is dominated by the steps you include. Measure with representative manifests.

Security notes

The executor passes input documents and variables to step resolvers; treat them as untrusted and validate within each resolver. Capability-gated steps fail closed when unlicensed. The executor logs no document content.

Conformance

The executor performs no format conformance work itself; conformance depends on the individual step resolvers (generate, merge, split, sign, convert).

Enterprise boundary note

Enterprise adds the Pack capabilities that unlock the gated step types (redaction, extraction, OCR overlay) at a behavior level. Without those Packs the pipeline still runs every non-gated step. Pack internals are out of scope here.

Core fallback / alternative

Without Pro, orchestrate PDF operations imperatively with NextPDF Core APIs; the declarative manifest, dependency ordering, and retries are Pro additions.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.