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

En un coup d’œil

Cette page est la référence détaillée de la surface publique de NextPDF\Pro\OutputPipeline. Elle couvre la construction et la validation du manifeste, l’ordre d’exécution topologique, la sémantique des nouvelles tentatives et du délai d’expiration, le comportement de reprise et la barrière de capacité de Pack fail-closed. Elle précise les paramètres, les valeurs par défaut et les modes de défaillance de chaque symbole public. Lis d’abord la page de capacité Pipeline de sortie pour des conseils sur le flux de travail.

Disponibilité et licence

Cette capacité est fournie avec NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de cette autorisation ne charge pas les classes de la capacité. Compare les éditions et obtiens une licence.

L’exécuteur et sept des dix types d’étapes ne portent aucun indicateur par fonctionnalité. Trois types d’étapes requièrent en plus une capacité de Pack :

Type d’étape	Valeur du manifeste	Capacité requise	Pack
Redact	redact	pack.privacy.redact	Privacy Pack
Extract	extract	pack.intelligence.extract	Intelligence Pack
OCR overlay	ocr_overlay	pack.intelligence.searchable_pdf	Intelligence Pack

La barrière est appliquée au moment de l’exécution, fail-closed, avant que l’étape n’atteigne son résolveur. Une étape sous barrière sans licence produit un résultat d’étape Failed portant le code SPEC-LIC-001 et la capacité requise ; le résolveur n’est jamais invoqué. Un pipeline sans résolveur de capacité injecté rejette toutes les étapes sous barrière.

Surface de l’API publique

composer require nextpdf/pro:^3

Le métapaquet nextpdf/premium installe le code nextpdf/pro ; ce module réside sous l’espace de noms NextPDF\Pro\OutputPipeline.

Symbole	Paramètres	Comportement par défaut	Retour	Lève ou échoue avec	Notes
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	Lie le registre de résolveurs intégré et la source d’autorisation optionnelle	PipelineExecutor	Rien de déclaré	Un résolveur de capacité null rejette toutes les étapes sous barrière de Pack
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	Exécute les étapes dans l’ordre topologique et agrège les résultats	PipelineResult	Rien de déclaré ; les échecs de résolveur sont capturés comme résultats d’étape Failed	Conçu pour s’exécuter dans un worker de tâches asynchrone
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	Valide le graphe d’étapes à la construction	PipelineManifest	InvalidArgumentException en cas de liste d’étapes vide, d’identifiants d’étape en double, de dépendances inconnues, de cycles, d’incompatibilité de type de sortie ou d’étape de reprise manquante ; OverflowException au-delà de 10 000 étapes	Toute la validation s’achève avant toute exécution
PipelineManifest::topologicalOrder	aucun	Ordonne les étapes en plaçant les dépendances avant les dépendants	list<PipelineStep>	Rien de déclaré	Déterministe pour un manifeste donné
PipelineManifest::getStep	string $stepId	Recherche linéaire par identifiant d’étape	?PipelineStep	Rien de déclaré	null pour un identifiant inconnu
PipelineManifest::rootSteps	aucun	Renvoie les étapes sans dépendances	list<PipelineStep>	Rien de déclaré	Les étapes racines s’exécutent en premier
PipelineManifestBuilder::create	string $manifestId	Démarre un nouveau builder	self	Rien de déclaré	Le constructeur est privé ; c’est le seul point d’entrée
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	Ajoute une étape ; un type de sortie null est déduit du type d’étape	self	Rien de déclaré	La validation est reportée à build()
PipelineManifestBuilder::stopOnError	bool $stop = true	Définit l’arrêt à la première défaillance	self	Rien de déclaré	Vaut true par défaut
PipelineManifestBuilder::maxRetries	int $retries	Définit le plafond de nouvelles tentatives par étape	self	Rien de déclaré	Vaut 0 par défaut (aucune nouvelle tentative)
PipelineManifestBuilder::timeout	int $timeoutMs	Définit le délai d’expiration global du pipeline	self	Rien de déclaré	0 désactive le délai d’expiration
PipelineManifestBuilder::resumeFrom	string $stepId	Définit le point de reprise	self	Rien de déclaré	L’étape doit exister au moment du build()
PipelineManifestBuilder::build	aucun	Construit le manifeste validé	PipelineManifest	Comme PipelineManifest::__construct	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	Options d’exécution immuables	PipelineOptions	Rien de déclaré	Objet-valeur en lecture seule
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	Définition d’étape immuable	PipelineStep	Rien de déclaré	La construction directe fixe le type de sortie à PDF par défaut pour tous les types
PipelineStep::isRoot	aucun	True lorsque l’étape n’a aucune dépendance	bool	Rien de déclaré	—
PipelineStepType (enum)	—	Dix cas à valeur de chaîne : generate, merge, split, inspect, compress, sign, convert, plus les cas sous barrière redact, extract, ocr_overlay	—	—	Un cas par opération intégrée
PipelineStepType::requiresPack	aucun	True pour Redact, Extract et OcrOverlay	bool	Rien de déclaré	Tous les autres cas renvoient false
PipelineStepType::requiredCapability	aucun	Associe les cas sous barrière à leurs codes de capacité	?string	Rien de déclaré	null pour les cas non soumis à barrière
PipelineStatus (enum)	—	Cinq cas : pending, running, completed, failed, cancelled	—	—	Partagé par les résultats de pipeline et d’étape
PipelineStatus::isTerminal	aucun	True pour Completed, Failed et Cancelled	bool	Rien de déclaré	Pending et Running ne sont pas terminaux
StepOutputType (enum)	—	Trois cas : pdf, json, metadata	—	—	Pilote la validation des arêtes à la construction
StepOutputType::forStepType	PipelineStepType $stepType	Type de sortie par défaut pour un type d’étape	self	Rien de déclaré	Inspect et Extract correspondent à JSON ; tous les autres types correspondent à PDF
StepOutputType::isCompatibleWith	self $expectedInput	True pour une correspondance de même type ou une sortie PDF	bool	Rien de déclaré	Utilitaire ; PDF est l’entrée universelle
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	Contexte en mémoire propre à chaque exécution	PipelineContext	Rien de déclaré	Aucun TTL, expiration, persistance ni magasin de stockage
PipelineContext::setStepResult / ::getStepResult	string $stepId (+ StepResult à l’écriture)	Enregistre ou lit un résultat d’étape	void / ?StepResult	Rien de déclaré	null pour une étape pas encore exécutée
PipelineContext::setStepOutput / ::getStepOutput	string $stepId (+ mixed à l’écriture)	Stocke ou lit une sortie intermédiaire	void / mixed	Rien de déclaré	null pour une sortie absente
PipelineContext::hasStepResult	string $stepId	Indique si une étape a déjà été exécutée	bool	Rien de déclaré	Prend en charge les vérifications de reprise
PipelineContext::allStepResults	aucun	Tous les résultats enregistrés jusqu’à présent	array<string, StepResult>	Rien de déclaré	Indexé par identifiant d’étape
PipelineContext::isResume	aucun	Indique si l’exécution reprend à partir d’une étape	bool	Rien de déclaré	—
PipelineResult::isSuccess	aucun	True uniquement pour un statut global Completed	bool	Rien de déclaré	Le résultat est produit par l’exécuteur
PipelineResult::getStepResult	string $stepId	Trouve un résultat d’étape par identifiant	?StepResult	Rien de déclaré	null pour les étapes ignorées ou inconnues
PipelineResult::failedSteps	aucun	Filtre les résultats d’étape en échec	list<StepResult>	Rien de déclaré	Liste vide en cas de réussite totale
StepResult::isSuccess	aucun	True uniquement pour un statut d’étape Completed	bool	Rien de déclaré	Porte stepId, type, status, durationMs, error, output
CapabilityResolverInterface::hasCapability	string $capability	Test d’autorisation affirmatif pour un code de capacité	bool	Ne doit pas lever d’exception	Refus par omission : false pour les codes inconnus, expirés ou non mappés

Signatures des points d’entrée

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

Contrat de comportement

Validation du manifeste

La validation s’exécute dans le constructeur de PipelineManifest, avant toute exécution. Dans l’ordre : la liste d’étapes doit être non vide ; le nombre d’étapes est plafonné à 10 000, ce qui convertit les chaînes de dépendances profondes de manière adverse en une OverflowException capturable au lieu d’un épuisement natif de la pile ; les identifiants d’étape doivent être uniques ; chaque référence dependsOn doit se résoudre ; le graphe de dépendances doit être acyclique ; les types de sortie doivent être compatibles ; une étape de reprise déclarée doit exister. Chaque violation lève une InvalidArgumentException avec un message spécifique.

La vérification du type de sortie s’applique aux étapes dont le type correspond à une sortie PDF : chaque dépendance d’une telle étape doit elle-même produire une sortie PDF. Les arêtes de dépendance vers des types d’étapes produisant du JSON (inspect, extract) ne font pas l’objet d’une vérification de type dans cette version.

Ordre d’exécution, reprise et délai d’expiration

execute($manifest, $variables) construit un nouveau PipelineContext, calcule l’ordre topologique et exécute les étapes séquentiellement dans cet ordre. Lorsqu’un point de reprise est défini, les étapes antérieures sont ignorées jusqu’à ce que l’étape nommée soit atteinte. Les prédécesseurs ignorés ne sont pas ré-exécutés et leurs sorties ne sont pas restaurées : le contexte est propre à chaque exécution et en mémoire, de sorte qu’une étape reprise qui lit la sortie d’un prédécesseur ignoré observe null.

Le délai d’expiration global, lorsqu’il est positif, est évalué entre les étapes, avant le démarrage de chaque étape. À son expiration, le statut du pipeline devient Failed et les étapes restantes ne démarrent pas. Une étape déjà en cours n’est jamais interrompue en cours d’exécution, si bien qu’une étape longue peut dépasser le budget.

Nouvelles tentatives et capture des échecs

Chaque étape reçoit au plus maxRetries + 1 tentatives. Une tentative réussie renvoie immédiatement. Toute tentative en échec — un résultat Failed du résolveur, ou un Throwable levé — fait l’objet d’une nouvelle tentative tant qu’il en reste ; le résultat de la dernière tentative est renvoyé. Un Throwable levé à l’intérieur d’un résolveur est rétrogradé en résultat d’étape Failed portant le message de l’exception, ou Unknown error lorsque le message est vide. execute() renvoie donc toujours un PipelineResult ; il ne propage jamais un échec de résolveur.

Un type d’étape sans résolveur enregistré produit un résultat d’étape Failed avec un message explicite ; l’exécution n’est pas interrompue. Avec stopOnError à true (valeur par défaut), l’exécution s’arrête à la première étape en échec et le statut du pipeline est Failed. Avec cette option à false, l’exécution se poursuit et le statut final est Failed si une étape a échoué, sinon Completed.

Barrière de capacité de Pack

Avant toute distribution à un résolveur, chaque étape sous barrière de Pack (Redact, Extract, OcrOverlay) est vérifiée par rapport au CapabilityResolverInterface injecté. La barrière est fail-closed : un résolveur manquant, une réponse false ou un code de capacité non mappé rejettent tous l’étape. Le rejet produit un résultat d’étape Failed dont l’erreur porte le code SPEC-LIC-001, le type d’étape et la capacité requise. Un rejet sous barrière ne consomme aucune tentative et rapporte une durée de 0.0. Les implémentations du résolveur ne doivent renvoyer true que pour une autorisation détenue de façon affirmative et ne doivent pas lever d’exception.

Agrégation des résultats

PipelineResult rapporte l’identifiant du manifeste, le statut global, les résultats par étape dans l’ordre d’exécution, la durée totale en millisecondes ainsi que les nombres d’étapes totales, terminées et en échec. stepsTotal compte chaque étape du manifeste, y compris les étapes ignorées par la reprise ou non atteintes après un arrêt ; stepsCompleted et stepsFailed ne comptent que les étapes exécutées.

Cas limites et modes de défaillance

• L’exécuteur est conçu pour une exécution asynchrone dans un worker de tâches. Une utilisation en ligne bloque l’appelant pendant toute la durée du pipeline.
• Le délai d’expiration global est une vérification entre les étapes. Une seule étape longue peut dépasser le budget ; aucune étape n’est interrompue en plein vol.
• La reprise n’ignore des étapes qu’au sein d’une même exécution. Elle ne restaure aucune sortie depuis un quelconque magasin ; la reprise inter-exécutions avec sorties mises en cache n’est pas implémentée.
• Construire PipelineStep directement fixe le type de sortie à PDF par défaut pour tous les types d’étape. Utilise le builder, ou passe le type de sortie explicitement, afin que les étapes inspect et extract déclarent une sortie JSON et que la validation des arêtes reste pertinente.
• Une exception de résolveur avec un message vide est normalisée en Unknown error dans le résultat d’étape.
• Les résultats d’étape Failed produits par la barrière ou par un résolveur manquant rapportent une durée de 0.0.
• PipelineResult::getStepResult() renvoie null à la fois pour les identifiants inconnus et pour les étapes ignorées par la reprise ou par un arrêt ; distingue-les via stepsTotal par rapport à la longueur de la liste de résultats.
• Ce module n’effectue aucune opération cryptographique et ne définit aucun comportement spécifique à FIPS. La posture FIPS de l’étape sign est régie par le module de signature, pas par le pipeline.

Conformité

Le pipeline n’effectue aucun travail de conformité de format qui lui soit propre. La conformité de chaque artefact produit relève du module derrière l’étape en cours d’exécution — signature, optimisation, conversion, etc. — et est documentée sur les pages de référence de ces modules. Cette page ne revendique aucun identifiant de clause externe ; chaque affirmation est ancrée dans le code source du produit. NextPDF ne formule aucune revendication de certification.

Notes de développement

• Le code source du module porte @since 2.2.0 ; cette référence documente la surface telle que livrée dans nextpdf/pro 3.1.0.
• Toutes les classes sont final ; les types manifeste, options, étape et résultat sont des objets-valeurs en lecture seule. Construis de nouvelles instances au lieu de muter.
• StepResolverInterface et StepResolverRegistry sont @internal. Les résolveurs d’étape sont exclusivement intégrés ; les gestionnaires d’étape personnalisés définis par l’utilisateur ne sont pas pris en charge dans cette version.
• CapabilityResolverInterface est le point d’extension public pour les autorisations. Les implémentations doivent fonctionner par refus par omission et ne doivent pas autoriser par défaut.
• Cet exécuteur PHP constitue le chemin de validation de manifeste et d’exécution séquentielle ; les déploiements de production peuvent distribuer via le sidecar pour une orchestration parallèle. La barrière de capacité sur le chemin PHP est fail-closed de manière indépendante dans les deux cas.
• Le détail des mécanismes internes reste dans la documentation interne du dépôt source et sort du périmètre de ce manuel.

Périmètre de publication

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

Voir aussi

• Pipeline de sortie — la page de capacité pour des conseils sur le flux de travail.
• Pipeline de sortie — Référence détaillée NextPDF Enterprise — orchestration par lots à travers les manifestes.
• Document — Référence détaillée
• Accelerator — Référence détaillée