Ausgabe-Pipeline — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die Detailreferenz für die öffentliche Oberfläche von NextPDF\Pro\OutputPipeline. Sie behandelt Manifest-Erstellung und -Validierung, die topologische Ausführungsreihenfolge, die Semantik von Wiederholung und Timeout, das Resume-Verhalten und das fail-closed Pack-Capability-Gate. Sie nennt Parameter, Standardwerte und Fehlermodi für jedes öffentliche Symbol. Lesen Sie zunächst die Capability-Seite der Ausgabe-Pipeline für Workflow-Hinweise.

Verfügbarkeit & Lizenzierung

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

Der Executor und sieben der zehn Schrittarten tragen kein Feature-Flag. Drei Schrittarten erfordern zusätzlich eine Pack-Capability:

Schrittart	Manifest-Wert	Erforderliche Capability	Pack
Redaktion	redact	pack.privacy.redact	Privacy Pack
Extraktion	extract	pack.intelligence.extract	Intelligence Pack
OCR-Overlay	ocr_overlay	pack.intelligence.searchable_pdf	Intelligence Pack

Das Gate wird zur Ausführungszeit erzwungen, fail-closed, bevor der Schritt seinen Resolver erreicht. Ein nicht lizenzierter gegateter Schritt liefert ein fehlgeschlagenes Schrittergebnis mit dem Code SPEC-LIC-001 und der erforderlichen Capability; der Resolver wird nie aufgerufen. Eine Pipeline ohne injizierten Capability-Resolver weist jeden gegateten Schritt ab.

Öffentliche API-Oberfläche

composer require nextpdf/pro:^3

Das Metapaket nextpdf/premium installiert den nextpdf/pro-Code; dieses Modul liegt im Namespace NextPDF\Pro\OutputPipeline.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	Bindet die eingebaute Resolver-Registry und die optionale Berechtigungsquelle	PipelineExecutor	Nichts deklariert	Ein null-Capability-Resolver weist jeden pack-gegateten Schritt ab
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	Führt Schritte in topologischer Reihenfolge aus und aggregiert die Ergebnisse	PipelineResult	Nichts deklariert; Resolver-Fehler werden als fehlgeschlagene Schrittergebnisse erfasst	Für die Ausführung innerhalb eines asynchronen Job-Workers ausgelegt
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	Validiert den Schrittgraphen bei der Konstruktion	PipelineManifest	InvalidArgumentException bei leerer Schrittliste, doppelten Schritt-IDs, unbekannten Abhängigkeiten, Zyklen, Ausgabetyp-Diskrepanz oder einem fehlenden Resume-Schritt; OverflowException oberhalb von 10 000 Schritten	Die gesamte Validierung wird vor jeder Ausführung abgeschlossen
PipelineManifest::topologicalOrder	keine	Ordnet Schritte so, dass Abhängigkeiten vor den abhängigen Schritten stehen	list<PipelineStep>	Nichts deklariert	Deterministisch für ein gegebenes Manifest
PipelineManifest::getStep	string $stepId	Lineare Suche anhand der Schritt-ID	?PipelineStep	Nichts deklariert	null bei unbekannter ID
PipelineManifest::rootSteps	keine	Gibt die Schritte ohne Abhängigkeiten zurück	list<PipelineStep>	Nichts deklariert	Wurzelschritte laufen zuerst
PipelineManifestBuilder::create	string $manifestId	Startet einen neuen Builder	self	Nichts deklariert	Der Konstruktor ist privat; dies ist der einzige Einstiegspunkt
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	Hängt einen Schritt an; ein null-Ausgabetyp wird aus der Schrittart abgeleitet	self	Nichts deklariert	Die Validierung wird auf build() verschoben
PipelineManifestBuilder::stopOnError	bool $stop = true	Legt das Anhalten beim ersten Fehler fest	self	Nichts deklariert	Standard ist true
PipelineManifestBuilder::maxRetries	int $retries	Legt die Obergrenze für Wiederholungen pro Schritt fest	self	Nichts deklariert	Standard ist 0 (keine Wiederholungen)
PipelineManifestBuilder::timeout	int $timeoutMs	Legt das globale Pipeline-Timeout fest	self	Nichts deklariert	0 deaktiviert das Timeout
PipelineManifestBuilder::resumeFrom	string $stepId	Legt den Resume-Punkt fest	self	Nichts deklariert	Der Schritt muss zum Zeitpunkt von build() existieren
PipelineManifestBuilder::build	keine	Konstruiert das validierte Manifest	PipelineManifest	Wie PipelineManifest::__construct	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	Unveränderliche Ausführungsoptionen	PipelineOptions	Nichts deklariert	Readonly-Wertobjekt
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	Unveränderliche Schrittdefinition	PipelineStep	Nichts deklariert	Bei direkter Konstruktion wird der Ausgabetyp für jede Art standardmäßig auf PDF gesetzt
PipelineStep::isRoot	keine	True, wenn der Schritt keine Abhängigkeiten hat	bool	Nichts deklariert	—
PipelineStepType (enum)	—	Zehn string-basierte Fälle: generate, merge, split, inspect, compress, sign, convert sowie die gegateten redact, extract, ocr_overlay	—	—	Ein Fall pro eingebauter Operation
PipelineStepType::requiresPack	keine	True für Redact, Extract und OcrOverlay	bool	Nichts deklariert	Alle anderen Fälle geben false zurück
PipelineStepType::requiredCapability	keine	Ordnet gegateten Fällen ihre Capability-Codes zu	?string	Nichts deklariert	null für nicht gegatete Fälle
PipelineStatus (enum)	—	Fünf Fälle: pending, running, completed, failed, cancelled	—	—	Von Pipeline- und Schrittergebnissen gemeinsam genutzt
PipelineStatus::isTerminal	keine	True für Completed, Failed und Cancelled	bool	Nichts deklariert	Pending und Running sind nicht-terminal
StepOutputType (enum)	—	Drei Fälle: pdf, json, metadata	—	—	Steuert die Kantenvalidierung zur Build-Zeit
StepOutputType::forStepType	PipelineStepType $stepType	Standard-Ausgabetyp für eine Schrittart	self	Nichts deklariert	Inspect und Extract werden auf JSON abgebildet; alle anderen Arten auf PDF
StepOutputType::isCompatibleWith	self $expectedInput	True bei Übereinstimmung des gleichen Typs oder einer PDF-Ausgabe	bool	Nichts deklariert	Hilfsfunktion; PDF ist die universelle Eingabe
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	In-Memory-Kontext pro Durchlauf	PipelineContext	Nichts deklariert	Kein TTL, kein Ablauf, keine Persistenz, kein Backing-Store
PipelineContext::setStepResult / ::getStepResult	string $stepId (+ StepResult beim Setzen)	Erfasst oder liest ein Schrittergebnis	void / ?StepResult	Nichts deklariert	null für einen noch nicht ausgeführten Schritt
PipelineContext::setStepOutput / ::getStepOutput	string $stepId (+ mixed beim Setzen)	Speichert oder liest eine Zwischenausgabe	void / mixed	Nichts deklariert	null bei fehlender Ausgabe
PipelineContext::hasStepResult	string $stepId	Ob ein Schritt bereits ausgeführt wurde	bool	Nichts deklariert	Unterstützt Resume-Prüfungen
PipelineContext::allStepResults	keine	Alle bislang erfassten Ergebnisse	array<string, StepResult>	Nichts deklariert	Nach Schritt-ID indiziert
PipelineContext::isResume	keine	Ob der Lauf ab einem Schritt fortgesetzt wird	bool	Nichts deklariert	—
PipelineResult::isSuccess	keine	True nur beim Gesamtstatus Completed	bool	Nichts deklariert	Das Ergebnis wird vom Executor erzeugt
PipelineResult::getStepResult	string $stepId	Findet ein Schrittergebnis anhand der ID	?StepResult	Nichts deklariert	null für übersprungene oder unbekannte Schritte
PipelineResult::failedSteps	keine	Filtert die fehlgeschlagenen Schrittergebnisse	list<StepResult>	Nichts deklariert	Leere Liste bei vollständigem Erfolg
StepResult::isSuccess	keine	True nur beim Schrittstatus Completed	bool	Nichts deklariert	Trägt stepId, type, status, durationMs, error, output
CapabilityResolverInterface::hasCapability	string $capability	Bejahende Berechtigungsprüfung für einen Capability-Code	bool	Darf nicht werfen	Deny-by-omission: false für unbekannte, abgelaufene oder nicht zugeordnete Codes

Einstiegspunkt-Signaturen

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

Verhaltensvertrag

Manifest-Validierung

Die Validierung läuft im Konstruktor von PipelineManifest, vor jeder Ausführung. Der Reihe nach: Die Schrittliste darf nicht leer sein; die Schrittanzahl ist auf 10 000 begrenzt, wodurch adversariell tiefe Abhängigkeitsketten in eine abfangbare OverflowException statt in eine native Stacküberlastung umgewandelt werden; Schritt-IDs müssen eindeutig sein; jede dependsOn-Referenz muss auflösbar sein; der Abhängigkeitsgraph muss azyklisch sein; Ausgabetypen müssen kompatibel sein; ein deklarierter Resume-Schritt muss existieren. Jede Verletzung löst eine InvalidArgumentException mit einer spezifischen Meldung aus.

Die Ausgabetyp-Prüfung gilt für Schritte, deren Art auf PDF-Ausgabe abgebildet wird: Jede Abhängigkeit eines solchen Schritts muss selbst PDF-Ausgabe erzeugen. Abhängigkeitskanten zu JSON-erzeugenden Schrittarten (inspect, extract) werden in diesem Release nicht typgeprüft.

Ausführungsreihenfolge, Resume und Timeout

execute($manifest, $variables) baut einen frischen PipelineContext auf, berechnet die topologische Reihenfolge und führt die Schritte sequenziell in dieser Reihenfolge aus. Ist ein Resume-Punkt gesetzt, werden frühere Schritte übersprungen, bis der benannte Schritt erreicht ist. Übersprungene Vorgänger werden nicht erneut ausgeführt und ihre Ausgaben nicht wiederhergestellt: Der Kontext gilt pro Durchlauf und liegt im Speicher, sodass ein fortgesetzter Schritt, der die Ausgabe eines übersprungenen Vorgängers liest, null beobachtet.

Das globale Timeout wird, wenn positiv, zwischen den Schritten ausgewertet, bevor jeder Schritt startet. Bei Ablauf wird der Pipeline-Status zu Failed und verbleibende Schritte starten nicht. Ein bereits laufender Schritt wird niemals mitten in der Ausführung unterbrochen, sodass ein langer Schritt das Budget überschreiten kann.

Wiederholungen und Fehlererfassung

Jeder Schritt erhält höchstens maxRetries + 1 Versuche. Ein erfolgreicher Versuch kehrt sofort zurück. Jeder fehlgeschlagene Versuch — ein Failed-Ergebnis des Resolvers oder ein geworfenes Throwable — wird wiederholt, solange Versuche verbleiben; das Ergebnis des letzten Versuchs wird zurückgegeben. Ein innerhalb eines Resolvers ausgelöstes Throwable wird zu einem fehlgeschlagenen Schrittergebnis herabgestuft, das die Ausnahmemeldung trägt, oder Unknown error, wenn die Meldung leer ist. execute() gibt daher immer ein PipelineResult zurück; ein Resolver-Fehler wird niemals propagiert.

Eine Schrittart ohne registrierten Resolver liefert ein fehlgeschlagenes Schrittergebnis mit einer expliziten Meldung; der Lauf wird nicht abgebrochen. Ist stopOnError true (der Standard), hält die Ausführung beim ersten fehlgeschlagenen Schritt an und der Pipeline-Status ist Failed. Ist es false, läuft die Ausführung weiter und der Endstatus ist Failed, wenn irgendein Schritt fehlgeschlagen ist, andernfalls Completed.

Pack-Capability-Gate

Vor jeder Resolver-Weiterleitung wird jeder pack-gegatete Schritt (Redact, Extract, OcrOverlay) gegen den injizierten CapabilityResolverInterface geprüft. Das Gate ist fail-closed: ein fehlender Resolver, eine false-Antwort oder ein nicht zugeordneter Capability-Code weisen den Schritt jeweils ab. Die Ablehnung erzeugt ein fehlgeschlagenes Schrittergebnis, dessen Fehler den Code SPEC-LIC-001, die Schrittart und die erforderliche Capability trägt. Eine gegatete Ablehnung verbraucht keine Wiederholungsversuche und meldet eine Dauer von 0.0. Implementierungen des Resolvers dürfen nur bei einer bejahend gehaltenen Berechtigung true zurückgeben und dürfen nicht werfen.

Ergebnisaggregation

PipelineResult meldet die Manifest-ID, den Gesamtstatus, die Ergebnisse pro Schritt in Ausführungsreihenfolge, die Gesamtdauer in Millisekunden sowie die Gesamtanzahl der Schritte und die Anzahl der abgeschlossenen und fehlgeschlagenen Schritte. stepsTotal zählt jeden Schritt im Manifest, einschließlich durch Resume übersprungener oder nach einem Halt nicht erreichter Schritte; stepsCompleted und stepsFailed zählen nur ausgeführte Schritte.

Sonderfälle & Fehlermodi

• Der Executor ist für die asynchrone Ausführung innerhalb eines Job-Workers ausgelegt. Eine Inline-Verwendung blockiert den Aufrufer für die gesamte Pipeline-Dauer.
• Das globale Timeout ist eine Prüfung zwischen den Schritten. Ein einzelner langer Schritt kann das Budget überschreiten; kein Schritt wird mitten im Lauf unterbrochen.
• Resume überspringt Schritte nur innerhalb derselben Ausführung. Es stellt keine Ausgaben aus einem Store wieder her; ein durchlaufübergreifendes Resume mit zwischengespeicherten Ausgaben ist nicht implementiert.
• Die direkte Konstruktion von PipelineStep setzt den Ausgabetyp für jede Schrittart standardmäßig auf PDF. Verwenden Sie den Builder oder übergeben Sie den Ausgabetyp explizit, damit inspect- und extract-Schritte JSON-Ausgabe deklarieren und die Kantenvalidierung aussagekräftig bleibt.
• Eine Resolver-Ausnahme mit leerer Meldung wird im Schrittergebnis zu Unknown error normalisiert.
• Fehlgeschlagene Schrittergebnisse, die vom Gate oder von einem fehlenden Resolver erzeugt werden, melden eine Dauer von 0.0.
• PipelineResult::getStepResult() gibt sowohl bei unbekannten IDs als auch bei durch Resume oder einen Halt übersprungenen Schritten null zurück; unterscheiden Sie über stepsTotal gegenüber der Länge der Ergebnisliste.
• Dieses Modul führt keine kryptografischen Operationen durch und definiert kein FIPS-spezifisches Verhalten. Die FIPS-Haltung für den sign-Schritt wird vom Signaturmodul bestimmt, nicht von der Pipeline.

Konformität

Die Pipeline führt keine eigene Formatkonformitätsarbeit durch. Die Konformität jedes erzeugten Artefakts liegt beim Modul hinter dem ausführenden Schritt — Signieren, Optimierung, Konvertierung usw. — und ist auf den Referenzseiten dieser Module dokumentiert. Diese Seite behauptet keine externen Klauselbezeichner; jede Aussage ist im Produkt-Quellcode begründet. NextPDF erhebt keinen Zertifizierungsanspruch.

Entwicklungshinweise

• Der Modul-Quellcode trägt @since 2.2.0; diese Referenz dokumentiert die Oberfläche, wie sie in nextpdf/pro 3.1.0 ausgeliefert wird.
• Alle Klassen sind final; die Manifest-, Options-, Schritt- und Ergebnistypen sind readonly Wertobjekte. Konstruieren Sie neue Instanzen, statt zu mutieren.
• StepResolverInterface und StepResolverRegistry sind @internal. Schritt-Resolver sind ausschließlich eingebaut; benutzerdefinierte eigene Schritt-Handler werden in diesem Release nicht unterstützt.
• CapabilityResolverInterface ist die öffentliche Berechtigungsschnittstelle. Implementierungen müssen deny-by-omission sein und dürfen nicht standardmäßig zulassen.
• Dieser PHP-Executor ist der Pfad für Manifest-Validierung und sequenzielle Ausführung; Produktionsbereitstellungen können für die parallele Orchestrierung über den Sidecar weiterleiten. Das Capability-Gate auf dem PHP-Pfad ist in beiden Fällen unabhängig fail-closed.
• Interne Mechanismus-Details verbleiben in der internen Dokumentation des Quell-Repositorys und liegen außerhalb des Umfangs dieses Handbuchs.

Veröffentlichungsgrenze

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

Siehe auch

• Ausgabe-Pipeline — die Capability-Seite für Workflow-Hinweise.
• Ausgabe-Pipeline — NextPDF Enterprise Detailreferenz — Batch-Orchestrierung über Manifeste hinweg.
• Document — Detailreferenz
• Accelerator — Detailreferenz