Enterprise Edition

Output-Pipeline — Ausführliche Referenz

Auf einen Blick

NextPDF\Enterprise\OutputPipeline führt viele Pro-Pipeline-Manifeste als einen Batch aus. BatchPipelineOrchestrator umschließt den Pro-PipelineExecutor mit Batch-Koordination: einer Ressourcenbegrenzung für die Batch-Größe, einem optionalen globalen Batch-Timeout, einer Variableninjektion pro Manifest und einer aggregierten Abrechnung. Eine optionale Compliance-Prüfung am Batch-Ende revalidiert jede fertiggestellte Ausgabe über das Enterprise-Compliance-Gateway und schlägt fail-closed fehl. Jeder Lauf liefert ein BatchPipelineResult zurück, das die Ergebnisse pro Manifest, die Anzahl der fertiggestellten und fehlgeschlagenen Manifeste, das Timing und den optionalen Compliance-Bericht enthält.

Verfügbarkeit & Lizenzierung

Diese Funktion ist Teil von NextPDF Enterprise (nextpdf/enterprise) und wird mit einer Lizenzhülle der Enterprise-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und eine Lizenz erhalten.

Stufe	Output-Pipeline-Oberfläche
Core	Keine Output-Pipeline-Oberfläche.
Pro	Pipeline für ein einzelnes Manifest (Fähigkeit `pro.output.pipeline`).
Enterprise	Batch-Orchestrierung, Batch-Größenbegrenzung, Batch-Timeout, Compliance-Übergabe.

Die Enterprise-Batch-Oberfläche trägt keinen eigenen Fähigkeitscode pro Feature; die Paketgrenze reguliert sie. Die Pro-Einzelmanifest-Fähigkeit pro.output.pipeline ist eine Voraussetzung, nicht das Gate. Eine Pro-Lizenz allein schaltet nur die zugrunde liegende Einzelmanifest-Pipeline frei, nicht diese Batch-Oberfläche.

composer require nextpdf/enterprise:^3

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`BatchPipelineOrchestrator::__construct()`	`PipelineExecutor $executor`, `BatchPipelineConfig $config`, `?ComplianceGateway $complianceGateway`, `ComplianceProfile $complianceProfile`	Standardkonfiguration; kein Gateway; Profil `ComplianceProfile::PdfA4`	—	Nichts	Injizieren Sie ein Gateway, wenn die Compliance-Prüfung aktiviert ist; ohne eines wird jedes geprüfte Manifest als fehlgeschlagen gemeldet.
`BatchPipelineOrchestrator::executeBatch()`	`list<PipelineManifest> $manifests`, `array<string, array<string, mixed>> $variablesMap = []`	Führt Manifeste in Einreichungsreihenfolge aus; Variablen werden über die Manifest-ID aufgelöst	`BatchPipelineResult`	`OverflowException`, wenn der Batch 10.000 Manifeste überschreitet; Gateway-Ausnahmen, wenn die Compliance-Prüfung aktiviert ist (siehe Grenzfälle)	Resolver-`Throwable`s entweichen nie; der Pro-Executor stuft sie zu fehlgeschlagenen Schrittergebnissen herab.
`BatchPipelineConfig::__construct()`	`int $maxConcurrency = 4`, `int $timeoutMs = 0`, `bool $complianceCheckOnComplete = false`	Nebenläufigkeit 4; kein Timeout; keine Compliance-Prüfung	—	Nichts	Readonly-Wertobjekt. `timeoutMs = 0` deaktiviert den Batch-Timeout.
`BatchPipelineResult::__construct()`	`list<PipelineResult> $results`, `int $totalManifests`, `int $completedCount`, `int $failedCount`, `float $durationMs`, `?array $complianceReport = null`	Aggregat über `PipelineResult`-Werte pro Manifest	—	Nichts	Readonly. `complianceReport` bleibt `null`, sofern die Prüfung nicht lief.
`BatchPipelineResult::allSucceeded()`	—	Prüft `failedCount === 0`	`bool`	Nichts	Liefert true bei einem timeout-abgeschnittenen Batch ohne Fehler; siehe Grenzfälle.
`BatchPipelineResult::successRate()`	—	`completedCount / totalManifests`	`float`	Nichts	Liefert `1.0` für einen leeren Batch.
`BatchPipelineResult::hasComplianceReport()`	—	Prüft `complianceReport !== null`	`bool`	Nichts	—

public function __construct(
    private readonly PipelineExecutor $executor,
    private readonly BatchPipelineConfig $config = new BatchPipelineConfig(),
    private readonly ?ComplianceGateway $complianceGateway = null,
    private readonly ComplianceProfile $complianceProfile = ComplianceProfile::PdfA4,
) {}

public function executeBatch(
    array $manifests,
    array $variablesMap = [],
): BatchPipelineResult

public function __construct(
    public int $maxConcurrency = 4,
    public int $timeoutMs = 0,
    public bool $complianceCheckOnComplete = false,
) {}

Verhaltensvertrag

executeBatch() prüft zuerst die Batch-Größe gegen eine Obergrenze von 10.000 Manifesten. Ein Batch über der Obergrenze löst OverflowException aus, bevor irgendein Manifest ausgeführt wird; nichts verschlechtert sich stillschweigend.

Anschließend werden die Manifeste in Einreichungsreihenfolge durch den Pro-PipelineExecutor ausgeführt. Jedes Manifest erhält den Variableneintrag, der in $variablesMap mit seiner ID verschlüsselt ist; ein Manifest ohne Eintrag erhält eine leere Variablen-Map. Ein Manifest gilt als fertiggestellt, wenn der Status seines PipelineResult Completed ist; jeder andere Endstatus gilt als fehlgeschlagen. Resolver-Ausnahmen entweichen nicht: Der Pro-Executor wandelt jeden Resolver-Throwable in ein fehlgeschlagenes Schrittergebnis um, sodass executeBatch() stets Ergebnisse aggregiert, anstatt bei einem Schrittfehler mitten im Batch abzubrechen.

Wenn timeoutMs größer als null ist, wird die verstrichene Zeit vor dem Start jedes Manifests geprüft. Sobald das Budget erschöpft ist, werden verbleibende Manifeste übersprungen: Sie erzeugen kein PipelineResult und zählen weder als fertiggestellt noch als fehlgeschlagen. totalManifests meldet stets die eingereichte Anzahl.

Wenn complianceCheckOnComplete aktiviert ist, validiert der Orchestrator das finale PDF jedes fertiggestellten Manifests gegen das konfigurierte ComplianceProfile über das injizierte ComplianceGateway. Die Prüfung schlägt fail-closed fehl:

Kein Gateway injiziert: Jedes geprüfte Manifest wird als fehlgeschlagen gemeldet, da die Compliance nie validiert wurde.
Kein PDF-Output aus den Schrittausgaben des Manifests auflösbar: fehlgeschlagen.
Gateway liefert kein Ergebnis (Nichtverfügbarkeit des Sidecars im optionalen Modus): fehlgeschlagen. Das Fehlen eines positiven Ergebnisses ist kein Bestehen.
Gateway meldet irgendeine Nichtkonformität: fehlgeschlagen.

Das finale PDF wird aufgelöst, indem die Schrittausgaben eines fertiggestellten Manifests, letzter Schritt zuerst, nach einem direkten String-Wert durchsucht werden, der mit dem %PDF-Header beginnt. Schrittausgaben verschachteln PDF-Byte-Strings nie innerhalb von Unterarrays; nur direkte Ausgabewerte werden inspiziert. Manifeste, die nicht fertiggestellt wurden, werden übersprungen, nicht geprüft.

Der Compliance-Bericht ist ein Array mit den Schlüsseln profile, checked, passed, failed und failures; jeder Fehlereintrag trägt manifestId und reason. Der Bericht wird an BatchPipelineResult::$complianceReport angehängt und ist über hasComplianceReport() erreichbar.

Die Compliance-Übergabe ist eine Revalidierungshilfe, keine Autorisierungskontrolle. Sie meldet ausschließlich Befunde.

Grenzfälle & Fehlermodi

Mehr als 10.000 Manifeste: OverflowException, bevor irgendeine Ausführung beginnt.
timeoutMs = 0 bedeutet kein Batch-Timeout. Setzen Sie in der Produktion einen endlichen Wert.
Timeout-Abschneidung: Übersprungene Manifeste erscheinen in keiner Zählung, sodass completedCount + failedCount kleiner sein kann als totalManifests. allSucceeded() prüft nur failedCount === 0 und kann für einen abgeschnittenen Batch true liefern. Vergleichen Sie count($result->results) mit totalManifests, um eine Abschneidung zu erkennen.
successRate() liefert 1.0 für einen leeren Batch (null eingereichte Manifeste).
Manifest-IDs werden auf Batch-Ebene nicht dedupliziert. Zwei Manifeste, die eine ID teilen, werden beide ausgeführt und lösen denselben Variableneintrag auf.
Strukturelle Manifest-Fehler (leere Schrittliste, doppelte Schritt-IDs, unbekannte Abhängigkeit, Abhängigkeitszyklus, Ausgabetyp-Nichtübereinstimmung, fehlender Resume-Schritt) lösen InvalidArgumentException bei der Manifest-Konstruktion aus, bevor executeBatch() jemals aufgerufen wird.
Bei aktivierter Compliance-Prüfung kann ComplianceGateway::validate() ComplianceSidecarUnavailableException (Sidecar im erforderlichen Modus nicht verfügbar) oder InvalidArgumentException (kein Validator für das Tool des Profils registriert) werfen. Beide Ausnahmen entweichen aus executeBatch() nach der Ausführung, aber bevor das Ergebnis aufgebaut ist, sodass die Ergebnisse pro Manifest für den Aufrufer verloren gehen. Im optionalen Modus liefert das Gateway stattdessen null, und das Manifest wird als Compliance-Fehler verzeichnet.
Ein Compliance-Übergabeschritt innerhalb der Pipeline schlägt fehl, wenn keine Ausgabe eines vorgelagerten Schritts erkennbare PDF-Bytes enthält; er besteht nie stillschweigend.
Dieses Modul führt keine kryptografischen Operationen aus; der FIPS-Modus ist nicht anwendbar.

Konformität

Für dieses Modul wird keine Standardkonformität beansprucht; es ist eine Orchestrierungsschicht. Die optionale Compliance-Prüfung verweist auf das Enterprise-Compliance-Gateway und seine externen Validatoren, die ihre eigenen Referenzen tragen. Das Standardprofil ist ComplianceProfile::PdfA4; weitere Gateway-Profile decken zusätzliche PDF/A-, PDF/UA- und PAdES-Ziele ab.

Ein Compliance-Bericht nennt Validator-Befunde gegen das ausgewählte Profil. Er zertifiziert kein Dokument, garantiert keine regulatorische Hinlänglichkeit und stellt keine Rechtsberatung dar. Die Beurteilung, ob eine Ausgabe Ihre Verpflichtungen erfüllt, liegt in Ihrer Verantwortung.

Entwicklungshinweise

In Produktionsbereitstellungen werden die parallele Worker-Verteilung und der Backpressure von einem separaten Ausführungs-Sidecar behandelt. Der PHP-Orchestrator stellt die Batch-Koordination und die Compliance-Übergabelogik bereit und wird vom Job-Worker aufgerufen, nicht direkt von Request-Handlern.
Der PHP-Fallback-Pfad führt Manifeste sequenziell aus. maxConcurrency begrenzt die gleichzeitigen Worker-Callbacks in der sidecar-getriebenen Bereitstellung; die Dimensionierung relativ zum PHP-Worker-Pool liegt in der Verantwortung des Betreibers.
Der Resolver des Compliance-Übergabeschritts innerhalb der Pipeline ist ein interner Typ, der für Inspect-Type-Schritte registriert ist. Aktivieren Sie die Validierung am Batch-Ende über BatchPipelineConfig, statt Pipeline-Schritte dafür direkt zu konstruieren.
Konstruieren Sie PipelineManifest-Instanzen frühzeitig. Ihre strukturelle Validierung läuft im Konstruktor, sodass ungültige Graphen frühzeitig fehlschlagen und nie Batch-Budget verbrauchen.

Publikationsgrenze

Diese Seite dokumentiert nur extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe sind nicht im Umfang enthalten.