Pro Edition

Ausgabe-Pipeline

Auf einen Blick

Die Output Pipeline führt ein deklaratives Manifest aus PDF-Schritten in Abhängigkeitsreihenfolge aus, mit Wiederholungen pro Schritt und einer Stop-on-Error-Option. Einige Schritttypen erfordern eine zusätzliche Enterprise-Pack-Capability.

Verfügbarkeit & Lizenzierung

Diese Funktion wird in NextPDF Pro (nextpdf/pro) ausgeliefert und aktiviert sich mit einem Lizenz-Envelope der Pro-Stufe. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und Lizenz erwerben.

Der Pipeline-Executor selbst ist Teil der Pro-Edition. Drei Schritttypen erfordern zusätzlich eine benannte Enterprise-Pack-Capability: Der Schwärzungsschritt erfordert eine Privacy-Pack-Capability, und die Schritte für Extraktion und OCR-Overlay erfordern Intelligence-Pack-Capabilities. Ein nicht lizenzierter gegateter Schritt scheitert bei der Ausführung fail-closed — er liefert ein fehlgeschlagenes Schrittergebnis, und sein Resolver wird nie aufgerufen — statt den gesamten Lauf abzubrechen.

Installation

composer require nextpdf/pro:^3

Der Code befindet sich im Namespace NextPDF\Pro\OutputPipeline.

Konzeptioneller Überblick

PipelineExecutor nimmt ein PipelineManifest entgegen, sortiert die Schritte in topologische Reihenfolge und übergibt jeden Schritt an einen in der StepResolverRegistry registrierten Resolver. Schrittausgaben werden in einem PipelineContext für nachgelagerte Schritte gespeichert. Der Executor erzwingt ein globales Timeout, unterstützt Wiederholungen pro Schritt und kann ab einem benannten Schritt fortsetzen. Er ist darauf ausgelegt, innerhalb eines asynchronen Job-Workers zu laufen, nicht direkt aus einem Request-Handler.

Zu den eingebauten Schritttypen gehören generate, merge, split, inspect, compress, sign und convert. Die Schritttypen redaction, extraction und OCR-overlay sind capability-lizenziert und werden auf Enterprise-Pack-Capabilities abgebildet.

Warum das so funktioniert

Der Executor ist reine Orchestrierung. Er sortiert die Schritte, erzwingt das Lizenz-Gate und übergibt jeden an einen registrierten Resolver, leistet aber selbst keine PDF-Arbeit. Diese Trennung erlaubt es, ein Manifest entweder über diesen sequenziellen PHP-Pfad oder über einen Out-of-Band-Worker auszuführen, der Schritte parallel übergibt, ohne Änderung am aufrufenden Code. Das Design zielt auf einen asynchronen Job-Worker statt auf einen Request-Handler, weil eine mehrstufige Pipeline routinemäßig ein Request-Budget überdauert und eine Queue den Durchsatz durch Hinzufügen von Workern skaliert. Das globale Timeout wird aus demselben Grund zwischen den Schritten geprüft: Ein ganzer Schritt ist die Arbeitseinheit, die an einen Resolver übergeben wird, und der Orchestrator hält sich aus dem Lauf dieses Resolvers heraus. Fehler treten als StepResult-Werte pro Schritt zutage statt als geworfene Ausnahmen, sodass ein fehlgeschlagener Schritt niemals das aggregierte PipelineResult zum Einsturz bringt, das der Worker meldet.

Design-Hintergrund: Hochvolumige Dokumentenerzeugung.

Verhaltensvertrag

execute($manifest, $variables) gibt ein Ergebnis mit Gesamtstatus, Ergebnissen pro Schritt, Dauer und Zählungen abgeschlossener und fehlgeschlagener Schritte zurück.
Schritte laufen in topologischer Reihenfolge; ein fehlender Resolver für einen Schritttyp ergibt einen fehlgeschlagenen Schritt mit einer klaren Meldung.
PipelineOptions::$stopOnError hält die Ausführung beim ersten Fehler an; andernfalls läuft die Ausführung weiter, und der Endstatus spiegelt etwaige Fehler wider.
Das globale Timeout lässt die Pipeline, sofern gesetzt, scheitern, wenn es überschritten wird, bevor der nächste Schritt beginnt.
Wiederholungen pro Schritt sind durch das konfigurierte Maximum begrenzt; nur nicht terminale Fehler werden wiederholt.
Resume-from-step überspringt frühere Schritte, bis der benannte Schritt erreicht ist.
Capability-gegatete Schritttypen scheitern bei der Ausführung fail-closed mit einem Lizenzfehlercode, wenn die erforderliche Pack-Capability fehlt; der Resolver wird nie aufgerufen.

Codebeispiel — Schnellstart

Das Folgende spiegelt die dokumentierte öffentliche API wider. Das Repository liefert für dieses Modul kein ausführbares Beispiel aus.

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

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

Codebeispiel — Produktion

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

Randfälle & Fallstricke

Die Pipeline ist dafür gedacht, asynchron über ein Job-System zu laufen. Inline ausgeführt blockiert sie den Aufrufer für die gesamte Pipeline-Dauer.
Ein Schritttyp ohne registrierten Resolver lässt diesen Schritt scheitern, statt die gesamte Pipeline abzubrechen (sofern Stop-on-Error nicht gesetzt ist).
Das globale Timeout wird zwischen den Schritten geprüft, nicht mitten in einem Schritt; ein lang laufender Schritt kann das Budget überschreiten, bevor die Prüfung greift.

Performance

Die Gesamtdauer ist die Summe der Schrittdauern plus dem Overhead für Wiederholungen. Das globale Timeout begrenzt die Worst-Case-Wall-Clock-Zeit. Es gibt keine veröffentlichte Durchsatzzahl; die Pipeline-Kosten werden von den Schritten dominiert, die Sie einbeziehen. Messen Sie mit repräsentativen Manifesten.

Sicherheitshinweise

Der Executor übergibt Eingabedokumente und Variablen an Schritt-Resolver; behandeln Sie sie als nicht vertrauenswürdig und validieren Sie innerhalb jedes Resolvers. Capability-gegatete Schritte scheitern fail-closed, wenn sie nicht lizenziert sind. Der Executor protokolliert keinen Dokumentinhalt.

Konformität

Der Executor leistet selbst keine Formatkonformitätsarbeit; die Konformität hängt von den einzelnen Schritt-Resolvern ab (generate, merge, split, sign, convert). Der RAG-Korpus war zum Zeitpunkt der Erstellung nicht verfügbar, sodass diese Seite keine externen Klausel-Identifikatoren behauptet.

Hinweis zur Enterprise-Grenze

Enterprise ergänzt die Pack-Capabilities, die die gegateten Schritttypen (redaction, extraction, OCR-overlay) auf Verhaltensebene freischalten. Ohne diese Packs läuft die Pipeline weiterhin jeden nicht gegateten Schritt aus. Die Interna der Packs liegen hier außerhalb des Umfangs.

Core-Fallback / Alternative

Ohne Pro orchestrieren Sie PDF-Operationen imperativ mit den NextPDF-Core-APIs; das deklarative Manifest, die Abhängigkeitsreihenfolge und die Wiederholungen sind Pro-Ergänzungen..

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.