Enterprise édition

Pipeline de sortie — référence détaillée

En un coup d’œil

NextPDF\Enterprise\OutputPipeline exécute de nombreux manifestes de pipeline Pro en un seul lot. BatchPipelineOrchestrator enveloppe le PipelineExecutor Pro avec une coordination par lots : une garde de ressources bornée sur la taille du lot, un délai d’expiration global optionnel pour le lot, une injection de variables par manifeste et une comptabilité agrégée. Une vérification de conformité optionnelle en fin de lot revalide chaque sortie terminée via la passerelle de conformité Enterprise et échoue de façon fermée. Chaque exécution renvoie un BatchPipelineResult qui porte les résultats par manifeste, les décomptes des sorties terminées et échouées, le chronométrage et le rapport de conformité optionnel.

Disponibilité et licence

Cette fonctionnalité est livrée dans NextPDF Enterprise (nextpdf/enterprise) et s’active avec une enveloppe de licence de niveau Enterprise. Un déploiement dépourvu de ce droit ne charge pas les classes de la fonctionnalité. Compare les éditions et obtiens une licence.

Niveau	Surface du pipeline de sortie
Core	Aucune surface de pipeline de sortie.
Pro	Pipeline à manifeste unique (capacité `pro.output.pipeline`).
Enterprise	Orchestration par lots, borne de taille de lot, délai d’expiration de lot, transfert de conformité.

La surface de lots Enterprise ne porte aucun code de capacité distinct par fonctionnalité ; c’est la frontière du paquet qui la contrôle. La capacité Pro à manifeste unique pro.output.pipeline est un prérequis, pas le point de contrôle. Une licence Pro seule ne débloque que le pipeline à manifeste unique sous-jacent, pas cette surface de lots.

composer require nextpdf/enterprise:^3

Surface de l’API publique

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
`BatchPipelineOrchestrator::__construct()`	`PipelineExecutor $executor`, `BatchPipelineConfig $config`, `?ComplianceGateway $complianceGateway`, `ComplianceProfile $complianceProfile`	Config par défaut ; pas de passerelle ; profil `ComplianceProfile::PdfA4`	—	Rien	Injecte une passerelle quand la vérification de conformité est activée ; sans elle, chaque manifeste vérifié est signalé comme échoué.
`BatchPipelineOrchestrator::executeBatch()`	`list<PipelineManifest> $manifests`, `array<string, array<string, mixed>> $variablesMap = []`	Exécute les manifestes dans l’ordre de soumission ; les variables sont résolues par identifiant de manifeste	`BatchPipelineResult`	`OverflowException` quand le lot dépasse 10,000 manifestes ; exceptions de passerelle quand la vérification de conformité est activée (voir Cas limites)	Les `Throwable` du résolveur ne s’échappent jamais ; l’exécuteur Pro les rétrograde en résultats d’étape échoués.
`BatchPipelineConfig::__construct()`	`int $maxConcurrency = 4`, `int $timeoutMs = 0`, `bool $complianceCheckOnComplete = false`	Concurrence 4 ; pas de délai d’expiration ; pas de vérification de conformité	—	Rien	Objet valeur en lecture seule. `timeoutMs = 0` désactive le délai d’expiration du lot.
`BatchPipelineResult::__construct()`	`list<PipelineResult> $results`, `int $totalManifests`, `int $completedCount`, `int $failedCount`, `float $durationMs`, `?array $complianceReport = null`	Agrégat sur les valeurs `PipelineResult` par manifeste	—	Rien	Lecture seule. `complianceReport` reste `null` sauf si la vérification a été exécutée.
`BatchPipelineResult::allSucceeded()`	—	Teste `failedCount === 0`	`bool`	Rien	Renvoie true pour un lot tronqué par délai d’expiration sans aucun échec ; voir Cas limites.
`BatchPipelineResult::successRate()`	—	`completedCount / totalManifests`	`float`	Rien	Renvoie `1.0` pour un lot vide.
`BatchPipelineResult::hasComplianceReport()`	—	Teste `complianceReport !== null`	`bool`	Rien	—

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,
) {}

Contrat de comportement

executeBatch() vérifie d’abord la taille du lot par rapport à un plafond de 10,000 manifestes. Un lot au-dessus du plafond lève OverflowException avant que le moindre manifeste ne s’exécute ; rien ne se dégrade silencieusement.

Les manifestes s’exécutent ensuite dans l’ordre de soumission via le PipelineExecutor Pro. Chaque manifeste reçoit l’entrée de variables indexée par son identifiant dans $variablesMap ; un manifeste sans entrée reçoit une carte de variables vide. Un manifeste compte comme terminé quand le statut de son PipelineResult est Completed ; tout autre statut terminal compte comme échoué. Les exceptions du résolveur ne s’échappent pas : l’exécuteur Pro convertit chaque Throwable du résolveur en un résultat d’étape échoué, si bien que executeBatch() agrège toujours les résultats au lieu d’avorter en plein lot sur une erreur d’étape.

Quand timeoutMs est supérieur à zéro, le temps écoulé est vérifié avant le démarrage de chaque manifeste. Une fois le budget épuisé, les manifestes restants sont ignorés : ils ne produisent aucun PipelineResult et ne comptent ni comme terminés ni comme échoués. totalManifests rapporte toujours le nombre soumis.

Quand complianceCheckOnComplete est activé, l’orchestrateur valide le PDF final de chaque manifeste terminé par rapport au ComplianceProfile configuré via le ComplianceGateway injecté. La vérification échoue de façon fermée :

Aucune passerelle injectée : chaque manifeste vérifié est signalé comme échoué, puisque la conformité n’a jamais été validée.
Aucune sortie PDF résolvable à partir des sorties d’étape du manifeste : échec.
La passerelle ne renvoie aucun résultat (indisponibilité du sidecar en mode optionnel) : échec. L’absence de résultat positif ne vaut pas réussite.
La passerelle signale une quelconque non-conformité : échec.

Le PDF final est résolu en parcourant les sorties d’étape d’un manifeste terminé, de la dernière étape en premier, à la recherche d’une valeur chaîne directe commençant par l’en-tête %PDF. Les sorties d’étape n’imbriquent jamais de chaînes d’octets PDF dans des sous-tableaux ; seules les valeurs de sortie directes sont inspectées. Les manifestes qui ne se sont pas terminés sont ignorés, pas vérifiés.

Le rapport de conformité est un tableau avec les clés profile, checked, passed, failed et failures ; chaque entrée d’échec porte manifestId et reason. Le rapport s’attache à BatchPipelineResult::$complianceReport et est accessible via hasComplianceReport().

Le transfert de conformité est une aide à la revalidation, pas un contrôle d’autorisation. Il ne fait que rapporter des constats.

Cas limites et modes de défaillance

Plus de 10,000 manifestes : OverflowException avant le démarrage de toute exécution.
timeoutMs = 0 signifie aucun délai d’expiration de lot. Définis une valeur finie en production.
Troncature par délai d’expiration : les manifestes ignorés n’apparaissent dans aucun décompte, donc completedCount + failedCount peut être inférieur à totalManifests. allSucceeded() ne teste que failedCount === 0 et peut renvoyer true pour un lot tronqué. Compare count($result->results) à totalManifests pour détecter une troncature.
successRate() renvoie 1.0 pour un lot vide (zéro manifeste soumis).
Les identifiants de manifeste ne sont pas dédupliqués au niveau du lot. Deux manifestes partageant un identifiant s’exécutent tous les deux et résolvent la même entrée de variables.
Les erreurs structurelles de manifeste (liste d’étapes vide, identifiants d’étape en double, dépendance inconnue, cycle de dépendances, incompatibilité de type de sortie, étape de reprise manquante) lèvent InvalidArgumentException à la construction du manifeste, avant même que executeBatch() ne soit appelé.
Avec la vérification de conformité activée, ComplianceGateway::validate() peut lever ComplianceSidecarUnavailableException (sidecar indisponible en mode requis) ou InvalidArgumentException (aucun validateur enregistré pour l’outil du profil). L’une ou l’autre exception s’échappe de executeBatch() après l’exécution mais avant la construction du résultat, si bien que les résultats par manifeste sont perdus pour l’appelant. En mode optionnel, la passerelle renvoie null à la place, et le manifeste est enregistré comme un échec de conformité.
Une étape de transfert de conformité intégrée au pipeline échoue quand aucune sortie d’étape en amont ne contient d’octets PDF reconnaissables ; elle ne réussit jamais silencieusement.
Ce module n’effectue aucune opération cryptographique ; le mode FIPS n’est pas applicable.

Conformité

Aucune conformité à des normes n’est revendiquée pour ce module ; c’est une couche d’orchestration. La vérification de conformité optionnelle s’en remet à la passerelle de conformité Enterprise et à ses validateurs externes, qui portent leurs propres références. Le profil par défaut est ComplianceProfile::PdfA4 ; d’autres profils de passerelle couvrent d’autres cibles PDF/A, PDF/UA et PAdES.

Un rapport de conformité énonce les constats du validateur par rapport au profil sélectionné. Il ne certifie pas un document, ne garantit pas une suffisance réglementaire et ne constitue pas un avis juridique. Juger si une sortie satisfait tes obligations relève de ta responsabilité.

Notes de développement

Dans les déploiements de production, la répartition parallèle des workers et la contre-pression sont gérées par un sidecar d’exécution distinct. L’orchestrateur PHP fournit la coordination par lots et la logique de transfert de conformité, et il est invoqué par le worker de tâches, pas directement par les gestionnaires de requêtes.
Le chemin de repli PHP exécute les manifestes séquentiellement. maxConcurrency borne les rappels de workers concurrents dans le déploiement piloté par le sidecar ; son dimensionnement par rapport au pool de workers PHP relève de la responsabilité de l’opérateur.
Le résolveur de l’étape de transfert de conformité intégrée au pipeline est un type interne enregistré pour les étapes de type inspection. Active la validation de fin de lot via BatchPipelineConfig plutôt que de construire directement des étapes de pipeline pour cela.
Construis les instances PipelineManifest tôt. Leur validation structurelle s’exécute dans le constructeur, si bien que les graphes invalides échouent rapidement et ne consomment jamais de budget de lot.

Périmètre de publication

Cette page ne documente que le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins de namespace internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.