Enterprise edición

Pipeline de salida — Referencia detallada

De un vistazo

NextPDF\Enterprise\OutputPipeline ejecuta muchos manifiestos de pipeline de Pro como un único lote. BatchPipelineOrchestrator envuelve el PipelineExecutor de Pro con coordinación por lotes: una guarda de recursos acotada sobre el tamaño del lote, un tiempo de espera global de lote opcional, inyección de variables por manifiesto y contabilidad agregada. Una comprobación de cumplimiento opcional al final del lote revalida cada salida completada a través de la pasarela de cumplimiento de Enterprise y falla en modo cerrado. Cada ejecución devuelve un BatchPipelineResult que porta los resultados por manifiesto, los recuentos de completados y fallidos, los tiempos y el informe de cumplimiento opcional.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin ese derecho no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Nivel	Superficie del pipeline de salida
Core	Sin superficie de pipeline de salida.
Pro	Pipeline de un solo manifiesto (capacidad `pro.output.pipeline`).
Enterprise	Orquestación por lotes, límite de tamaño de lote, tiempo de espera de lote, transferencia de cumplimiento.

La superficie de lote de Enterprise no lleva ningún código de capacidad por característica independiente; el límite del paquete la controla. La capacidad de un solo manifiesto de Pro pro.output.pipeline es un prerrequisito, no el control de acceso. Una licencia de Pro por sí sola desbloquea únicamente el pipeline de un solo manifiesto subyacente, no esta superficie de lote.

composer require nextpdf/enterprise:^3

Superficie pública de la API

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`BatchPipelineOrchestrator::__construct()`	`PipelineExecutor $executor`, `BatchPipelineConfig $config`, `?ComplianceGateway $complianceGateway`, `ComplianceProfile $complianceProfile`	Configuración predeterminada; sin pasarela; perfil `ComplianceProfile::PdfA4`	—	Nada	Inyectar una pasarela cuando la comprobación de cumplimiento está habilitada; sin ella, cada manifiesto comprobado se reporta como fallido.
`BatchPipelineOrchestrator::executeBatch()`	`list<PipelineManifest> $manifests`, `array<string, array<string, mixed>> $variablesMap = []`	Ejecuta los manifiestos en orden de envío; las variables se resuelven por ID de manifiesto	`BatchPipelineResult`	`OverflowException` cuando el lote supera los 10.000 manifiestos; excepciones de la pasarela cuando la comprobación de cumplimiento está habilitada (véase Casos límite)	Los `Throwable` del resolutor nunca escapan; el ejecutor de Pro los degrada a resultados de paso fallidos.
`BatchPipelineConfig::__construct()`	`int $maxConcurrency = 4`, `int $timeoutMs = 0`, `bool $complianceCheckOnComplete = false`	Concurrencia 4; sin tiempo de espera; sin comprobación de cumplimiento	—	Nada	Objeto de valor de solo lectura. `timeoutMs = 0` desactiva el tiempo de espera del lote.
`BatchPipelineResult::__construct()`	`list<PipelineResult> $results`, `int $totalManifests`, `int $completedCount`, `int $failedCount`, `float $durationMs`, `?array $complianceReport = null`	Agregación sobre los valores `PipelineResult` por manifiesto	—	Nada	De solo lectura. `complianceReport` permanece `null` salvo que la comprobación se haya ejecutado.
`BatchPipelineResult::allSucceeded()`	—	Comprueba `failedCount === 0`	`bool`	Nada	Devuelve verdadero en un lote truncado por tiempo de espera con cero fallos; véase Casos límite.
`BatchPipelineResult::successRate()`	—	`completedCount / totalManifests`	`float`	Nada	Devuelve `1.0` para un lote vacío.
`BatchPipelineResult::hasComplianceReport()`	—	Comprueba `complianceReport !== null`	`bool`	Nada	—

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

Contrato de comportamiento

executeBatch() afirma primero el tamaño del lote contra un tope de 10.000 manifiestos. Un lote por encima del tope lanza OverflowException antes de que se ejecute cualquier manifiesto; nada se degrada de forma silenciosa.

Los manifiestos se ejecutan entonces en orden de envío a través del PipelineExecutor de Pro. Cada manifiesto recibe la entrada de variables asociada a su ID en $variablesMap; un manifiesto sin entrada recibe un mapa de variables vacío. Un manifiesto cuenta como completado cuando el estado de su PipelineResult es Completed; cualquier otro estado terminal cuenta como fallido. Las excepciones del resolutor no escapan: el ejecutor de Pro convierte cada Throwable del resolutor en un resultado de paso fallido, de modo que executeBatch() siempre agrega resultados en lugar de abortar a mitad de lote ante un error de paso.

Cuando timeoutMs es mayor que cero, el tiempo transcurrido se comprueba antes de que comience cada manifiesto. Una vez agotado el presupuesto, los manifiestos restantes se omiten: no producen ningún PipelineResult y no cuentan ni como completados ni como fallidos. totalManifests siempre reporta el recuento enviado.

Cuando complianceCheckOnComplete está habilitado, el orquestador valida el PDF final de cada manifiesto completado contra el ComplianceProfile configurado a través del ComplianceGateway inyectado. La comprobación falla en modo cerrado:

Sin pasarela inyectada: cada manifiesto comprobado se reporta como fallido, ya que el cumplimiento nunca se validó.
Sin salida PDF resoluble a partir de las salidas de pasos del manifiesto: fallido.
La pasarela no devuelve ningún resultado (indisponibilidad del sidecar en modo opcional): fallido. La ausencia de un resultado positivo no es una aprobación.
La pasarela reporta cualquier no conformidad: fallido.

El PDF final se resuelve explorando las salidas de pasos de un manifiesto completado, empezando por el último paso, en busca de un valor de cadena directo que comience con la cabecera %PDF. Las salidas de pasos nunca anidan cadenas de bytes PDF dentro de subarreglos; solo se inspeccionan los valores de salida directos. Los manifiestos que no se completaron se omiten, no se comprueban.

El informe de cumplimiento es un arreglo con las claves profile, checked, passed, failed y failures; cada entrada de fallo porta manifestId y reason. El informe se adjunta a BatchPipelineResult::$complianceReport y es accesible mediante hasComplianceReport().

La transferencia de cumplimiento es una ayuda de revalidación, no un control de autorización. Solo reporta hallazgos.

Casos límite y modos de fallo

Más de 10.000 manifiestos: OverflowException antes de que comience cualquier ejecución.
timeoutMs = 0 significa sin tiempo de espera de lote. Establecer un valor finito en producción.
Truncamiento por tiempo de espera: los manifiestos omitidos no aparecen en ningún recuento, por lo que completedCount + failedCount puede ser menor que totalManifests. allSucceeded() comprueba solo failedCount === 0 y puede devolver verdadero para un lote truncado. Comparar count($result->results) con totalManifests para detectar el truncamiento.
successRate() devuelve 1.0 para un lote vacío (cero manifiestos enviados).
Los IDs de manifiesto no se deduplican a nivel de lote. Dos manifiestos que comparten un ID se ejecutan ambos y resuelven la misma entrada de variables.
Los errores estructurales de manifiesto (lista de pasos vacía, IDs de paso duplicados, dependencia desconocida, ciclo de dependencias, discrepancia de tipo de salida, paso de reanudación faltante) lanzan InvalidArgumentException en la construcción del manifiesto, antes de que se llame siquiera a executeBatch().
Con la comprobación de cumplimiento habilitada, ComplianceGateway::validate() puede lanzar ComplianceSidecarUnavailableException (sidecar no disponible en modo requerido) o InvalidArgumentException (ningún validador registrado para la herramienta del perfil). Cualquiera de estas excepciones escapa de executeBatch() después de la ejecución pero antes de que se construya el resultado, por lo que los resultados por manifiesto se pierden para el llamador. En modo opcional la pasarela devuelve null en su lugar, y el manifiesto se registra como un fallo de cumplimiento.
Un paso de transferencia de cumplimiento dentro del pipeline falla cuando ninguna salida de paso anterior contiene bytes PDF reconocibles; nunca se aprueba de forma silenciosa.
Este módulo no realiza operaciones criptográficas; el modo FIPS no es aplicable.

Conformidad

No se reclama conformidad con ninguna norma para este módulo; es una capa de orquestación. La comprobación de cumplimiento opcional delega en la pasarela de cumplimiento de Enterprise y sus validadores externos, que portan sus propias referencias. El perfil predeterminado es ComplianceProfile::PdfA4; otros perfiles de la pasarela cubren objetivos adicionales de PDF/A, PDF/UA y PAdES.

Un informe de cumplimiento expone los hallazgos del validador contra el perfil seleccionado. No certifica un documento, ni garantiza suficiencia regulatoria, ni constituye asesoramiento legal. Determinar si una salida cumple sus obligaciones es su responsabilidad.

Notas de desarrollo

En los despliegues de producción, el despacho de trabajadores en paralelo y la contrapresión los gestiona un sidecar de ejecución independiente. El orquestador de PHP proporciona la coordinación por lotes y la lógica de transferencia de cumplimiento, y es invocado por el trabajador de trabajos, no directamente por los manejadores de peticiones.
La ruta de reserva de PHP ejecuta los manifiestos de forma secuencial. maxConcurrency acota las devoluciones de llamada concurrentes de trabajadores en el despliegue impulsado por sidecar; dimensionarlo en relación con el conjunto de trabajadores de PHP es responsabilidad del operador.
El resolutor del paso de transferencia de cumplimiento dentro del pipeline es un tipo interno registrado para pasos de tipo inspección. Habilitar la validación al final del lote a través de BatchPipelineConfig en lugar de construir pasos de pipeline para ello directamente.
Construir las instancias de PipelineManifest de forma temprana. Su validación estructural se ejecuta en el constructor, de modo que los grafos inválidos fallan rápido y nunca consumen presupuesto de lote.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de la API soportada. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbooks y los prefijos de tickets quedan fuera de alcance.