Pro édition

Pipeline de sortie

En bref

L’Output Pipeline exécute un manifeste déclaratif d’étapes PDF dans l’ordre des dépendances, avec des reprises par étape et une option d’arrêt sur erreur. Certains types d’étapes nécessitent une capacité Enterprise Pack supplémentaire.

Disponibilité et licence

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

L’exécuteur de pipeline lui-même fait partie de l’édition Pro. Trois types d’étapes nécessitent en outre une capacité Enterprise Pack nommée : l’étape de caviardage nécessite une capacité Privacy Pack, et les étapes d’extraction et de superposition OCR nécessitent des capacités Intelligence Pack. Une étape restreinte non licenciée échoue de manière verrouillée à l’exécution — elle produit un résultat d’étape en échec et son résolveur n’est jamais invoqué — plutôt que d’interrompre toute l’exécution.

Installer

composer require nextpdf/pro:^3

Le code se trouve sous l’espace de noms NextPDF\Pro\OutputPipeline.

Vue d’ensemble conceptuelle

PipelineExecutor prend un PipelineManifest, trie les étapes en ordre topologique et dépêche chaque étape vers un résolveur enregistré dans le StepResolverRegistry. Les sorties d’étapes sont stockées dans un PipelineContext pour les étapes en aval. L’exécuteur impose un délai d’expiration global, prend en charge les reprises par étape et peut reprendre à partir d’une étape nommée. Il est conçu pour s’exécuter à l’intérieur d’un worker de tâches asynchrone, et non directement depuis un gestionnaire de requête.

Les types d’étapes intégrés incluent generate, merge, split, inspect, compress, sign et convert. Les types d’étapes de caviardage, d’extraction et de superposition OCR sont restreints par capacité et correspondent à des capacités Enterprise Pack.

Pourquoi ce fonctionnement

L’exécuteur n’est que de l’orchestration. Il trie les étapes, applique le verrou de licence et dépêche chacune vers un résolveur enregistré, mais n’effectue lui-même aucun travail PDF. Cette séparation permet à un même manifeste de s’exécuter soit via ce chemin PHP séquentiel, soit via un worker hors bande qui dépêche les étapes en parallèle, sans modifier le code appelant. La conception vise un worker de tâches asynchrone plutôt qu’un gestionnaire de requête, car un pipeline multi-étapes dépasse régulièrement le budget d’une requête, et une file d’attente met à l’échelle le débit en ajoutant des workers. Le délai d’expiration global est vérifié entre les étapes pour la même raison : une étape entière est l’unité de travail confiée à un résolveur, et l’orchestrateur reste en dehors de l’exécution de ce résolveur. Les échecs se manifestent sous forme de valeurs StepResult par étape plutôt que d’exceptions levées, de sorte qu’une étape en échec ne fait jamais s’effondrer le PipelineResult agrégé que le worker rapporte.

Contexte de conception : Génération de documents en grand volume.

Contrat de comportement

execute($manifest, $variables) renvoie un résultat avec le statut global, les résultats par étape, la durée et le nombre d’étapes terminées et échouées.
Les étapes s’exécutent en ordre topologique ; un résolveur manquant pour un type d’étape produit une étape échouée avec un message clair.
PipelineOptions::$stopOnError arrête l’exécution au premier échec ; sinon l’exécution continue et le statut final reflète tout échec.
Le délai d’expiration global, lorsqu’il est défini, fait échouer le pipeline s’il est dépassé avant le démarrage de l’étape suivante.
Les reprises par étape sont bornées par le maximum configuré ; seuls les échecs non terminaux sont réessayés.
La reprise à partir d’une étape saute les étapes antérieures jusqu’à atteindre l’étape nommée.
Les types d’étapes restreints par capacité échouent de manière verrouillée à l’exécution avec un code d’erreur de licence lorsque la capacité Pack requise est absente ; le résolveur n’est jamais invoqué.

Exemple de code — Démarrage rapide

Ce qui suit reflète l’API publique documentée. Le dépôt ne livre pas d’exemple exécutable pour ce module.

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

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

Exemple de code — Production

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

Cas limites & pièges

Le pipeline est destiné à s’exécuter de manière asynchrone via un système de tâches. L’exécuter en ligne bloque l’appelant pendant toute la durée du pipeline.
Un type d’étape sans résolveur enregistré fait échouer cette étape plutôt que d’abandonner tout le pipeline (sauf si l’arrêt sur erreur est défini).
Le délai d’expiration global est vérifié entre les étapes, et non en cours d’étape ; une étape de longue durée peut dépasser le budget avant que la vérification ne se déclenche.

Performance

La durée totale est la somme des durées d’étapes plus la surcharge des reprises. Le délai d’expiration global borne le temps d’horloge dans le pire des cas. Il n’existe pas de chiffre de débit publié ; le coût du pipeline est dominé par les étapes que tu inclus. Mesure avec des manifestes représentatifs.

Notes de sécurité

L’exécuteur transmet les documents d’entrée et les variables aux résolveurs d’étapes ; traite-les comme non fiables et valide-les dans chaque résolveur. Les étapes restreintes par capacité échouent de manière verrouillée lorsqu’elles ne sont pas licenciées. L’exécuteur ne journalise aucun contenu de document.

Conformité

L’exécuteur n’effectue lui-même aucun travail de conformité de format ; la conformité dépend des résolveurs d’étapes individuels (generate, merge, split, sign, convert). Le corpus RAG était indisponible au moment de la rédaction, si bien que cette page n’affirme aucun identifiant de clause externe.

Note sur la frontière Enterprise

Enterprise ajoute les capacités Pack qui déverrouillent les types d’étapes restreints (caviardage, extraction, superposition OCR) au niveau du comportement. Sans ces Packs, le pipeline exécute quand même chaque étape non restreinte. Les rouages internes des Packs sortent du périmètre ici.

Repli / alternative dans le Core

Sans Pro, orchestre les opérations PDF de manière impérative avec les API NextPDF Core ; le manifeste déclaratif, l’ordonnancement par dépendances et les reprises sont des ajouts Pro..

Frontière de publication

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