Pro edición

Pipeline de salida

De un vistazo

El Output Pipeline ejecuta un manifiesto declarativo de pasos de PDF en orden de dependencia, con reintentos por paso y una opción de detención ante error. Algunos tipos de paso requieren una capacidad adicional de Enterprise Pack.

Disponibilidad y licencias

Esta función se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin esa habilitación no carga las clases de la función. Comparar ediciones y obtener una licencia.

El propio ejecutor del pipeline forma parte de la edición Pro. Tres tipos de paso requieren además una capacidad nombrada de Enterprise Pack: el paso de redacción requiere una capacidad de Privacy Pack, y los pasos de extracción y de superposición de OCR requieren capacidades de Intelligence Pack. Un paso restringido sin licencia falla de forma cerrada durante la ejecución —produce un resultado de paso fallido y su resolvedor nunca se invoca— en lugar de abortar toda la ejecución.

Instalación

composer require nextpdf/pro:^3

El código reside en el espacio de nombres NextPDF\Pro\OutputPipeline.

Panorama conceptual

PipelineExecutor toma un PipelineManifest, ordena los pasos en orden topológico y despacha cada paso a un resolvedor registrado en el StepResolverRegistry. Las salidas de los pasos se almacenan en un PipelineContext para los pasos posteriores. El ejecutor aplica un tiempo de espera global, admite reintentos por paso y puede reanudarse desde un paso con nombre. Está diseñado para ejecutarse dentro de un trabajador de trabajos asíncrono, no directamente desde un manejador de peticiones.

Los tipos de paso integrados incluyen generar, combinar, dividir, inspeccionar, comprimir, firmar y convertir. Los tipos de paso de redacción, extracción y superposición de OCR están licenciados por capacidad y se asignan a capacidades de Enterprise Pack.

Por qué funciona así

El ejecutor es solo orquestación. Ordena los pasos, aplica la restricción de licencia y despacha cada uno a un resolvedor registrado, pero no realiza por sí mismo ningún trabajo de PDF. Esa separación permite que un mismo manifiesto se ejecute ya sea a través de esta ruta secuencial de PHP o a través de un trabajador fuera de banda que despacha los pasos en paralelo, sin cambio alguno en el código llamador. El diseño apunta a un trabajador de trabajos asíncrono en lugar de un manejador de peticiones, porque un pipeline de varios pasos habitualmente sobrevive al presupuesto de una petición, y una cola escala el rendimiento añadiendo trabajadores. El tiempo de espera global se comprueba entre pasos por la misma razón: un paso completo es la unidad de trabajo entregada a un resolvedor, y el orquestador se mantiene al margen de la ejecución de ese resolvedor. Los fallos se manifiestan como valores StepResult por paso en lugar de excepciones lanzadas, de modo que un paso fallido nunca colapsa el PipelineResult agregado que reporta el trabajador.

Contexto de diseño: Generación de documentos de alto volumen.

Contrato de comportamiento

execute($manifest, $variables) devuelve un resultado con el estado global, los resultados por paso, la duración y los recuentos de pasos completados y fallidos.
Los pasos se ejecutan en orden topológico; la falta de un resolvedor para un tipo de paso produce un paso fallido con un mensaje claro.
PipelineOptions::$stopOnError detiene la ejecución en el primer fallo; en caso contrario, la ejecución continúa y el estado final refleja cualquier fallo.
El tiempo de espera global, cuando se establece, hace fallar el pipeline si se supera antes de que comience el siguiente paso.
Los reintentos por paso están acotados por el máximo configurado; solo se reintentan los fallos no terminales.
Reanudar desde un paso omite los pasos anteriores hasta que se alcanza el paso con nombre.
Los tipos de paso restringidos por capacidad fallan de forma cerrada durante la ejecución con un código de error de licencia cuando la capacidad de Pack requerida está ausente; el resolvedor nunca se invoca.

Ejemplo de código — Inicio rápido

Lo siguiente refleja la API pública documentada. El repositorio no incluye un ejemplo ejecutable para este módulo.

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

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

Ejemplo de código — Producción

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

Casos límite y trampas

El pipeline está pensado para ejecutarse de forma asíncrona a través de un sistema de trabajos. Ejecutarlo en línea bloquea al llamador durante toda la duración del pipeline.
Un tipo de paso sin resolvedor registrado hace fallar ese paso en lugar de abortar todo el pipeline (a menos que se establezca la detención ante error).
El tiempo de espera global se comprueba entre pasos, no a mitad de un paso; un paso de larga ejecución puede sobrepasar el presupuesto antes de que se dispare la comprobación.

Rendimiento

La duración total es la suma de las duraciones de los pasos más la sobrecarga de los reintentos. El tiempo de espera global acota el tiempo de reloj en el peor caso. No hay una cifra de rendimiento publicada; el coste del pipeline está dominado por los pasos que incluyas. Mide con manifiestos representativos.

Notas de seguridad

El ejecutor pasa los documentos de entrada y las variables a los resolvedores de pasos; trátalos como no confiables y valídalos dentro de cada resolvedor. Los pasos restringidos por capacidad fallan de forma cerrada cuando no tienen licencia. El ejecutor no registra ningún contenido del documento.

Conformidad

El ejecutor no realiza por sí mismo ningún trabajo de conformidad de formato; la conformidad depende de los resolvedores de pasos individuales (generar, combinar, dividir, firmar, convertir). El corpus RAG no estaba disponible en el momento de la redacción, por lo que esta página no afirma identificadores de cláusula externos.

Nota sobre el límite de Enterprise

Enterprise añade las capacidades de Pack que desbloquean los tipos de paso restringidos (redacción, extracción, superposición de OCR) a nivel de comportamiento. Sin esos Packs, el pipeline sigue ejecutando todos los pasos no restringidos. El funcionamiento interno de los Packs queda fuera del alcance aquí.

Alternativa / opción de respaldo en Core

Sin Pro, orquesta las operaciones de PDF de forma imperativa con las API de NextPDF Core; el manifiesto declarativo, el ordenamiento por dependencias y los reintentos son adiciones de Pro..

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de API compatible. Las rutas de espacios de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivos de runbook y los prefijos de tickets quedan fuera del alcance.