Output Pipeline — Referencia detallada

De un vistazo

Esta página es la referencia detallada de la superficie pública de NextPDF\Pro\OutputPipeline. Abarca la construcción y validación del manifiesto, el orden de ejecución topológico, la semántica de reintentos y tiempos de espera, el comportamiento de reanudación y la barrera de capacidad de packs fail-closed. Indica los parámetros, los valores predeterminados y los modos de fallo de cada símbolo público. Lea primero la página de capacidad de Output Pipeline para orientación sobre el flujo de trabajo.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la capacidad. Compare ediciones y obtenga una licencia.

El ejecutor y siete de los diez tipos de paso no llevan ninguna marca por función. Tres tipos de paso requieren además una capacidad de Pack:

Tipo de paso	Valor del manifiesto	Capacidad requerida	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 barrera se aplica en tiempo de ejecución, fail-closed, antes de que el paso llegue a su resolver. Un paso restringido sin licencia produce un resultado de paso Failed que lleva el código SPEC-LIC-001 y la capacidad requerida; el resolver nunca se invoca. Un pipeline sin resolver de capacidad inyectado rechaza todos los pasos restringidos.

Superficie de la API pública

composer require nextpdf/pro:^3

El metapaquete nextpdf/premium instala el código de nextpdf/pro; este módulo reside en el espacio de nombres NextPDF\Pro\OutputPipeline.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	Vincula el registro de resolvers integrado y la fuente de derechos opcional	PipelineExecutor	Nada declarado	Un resolver de capacidad null rechaza todos los pasos restringidos por Pack
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	Ejecuta los pasos en orden topológico y agrega los resultados	PipelineResult	Nada declarado; los fallos del resolver se capturan como resultados de paso Failed	Diseñado para ejecutarse dentro de un worker de trabajos asíncrono
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	Valida el grafo de pasos en la construcción	PipelineManifest	InvalidArgumentException ante una lista de pasos vacía, IDs de paso duplicados, dependencias desconocidas, ciclos, incompatibilidad de tipos de salida o un paso de reanudación inexistente; OverflowException por encima de 10 000 pasos	Toda la validación se completa antes de cualquier ejecución
PipelineManifest::topologicalOrder	ninguno	Ordena los pasos con las dependencias antes que los dependientes	list<PipelineStep>	Nada declarado	Determinista para un manifiesto dado
PipelineManifest::getStep	string $stepId	Búsqueda lineal por ID de paso	?PipelineStep	Nada declarado	null para un ID desconocido
PipelineManifest::rootSteps	ninguno	Devuelve los pasos sin dependencias	list<PipelineStep>	Nada declarado	Los pasos raíz se ejecutan primero
PipelineManifestBuilder::create	string $manifestId	Inicia un nuevo builder	self	Nada declarado	El constructor es privado; esta es la única entrada
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	Añade un paso; un tipo de salida null se infiere a partir del tipo de paso	self	Nada declarado	La validación se aplaza a build()
PipelineManifestBuilder::stopOnError	bool $stop = true	Establece la detención en el primer fallo	self	Nada declarado	Predeterminado a true
PipelineManifestBuilder::maxRetries	int $retries	Establece el límite de reintentos por paso	self	Nada declarado	Predeterminado a 0 (sin reintentos)
PipelineManifestBuilder::timeout	int $timeoutMs	Establece el tiempo de espera global del pipeline	self	Nada declarado	0 desactiva el tiempo de espera
PipelineManifestBuilder::resumeFrom	string $stepId	Establece el punto de reanudación	self	Nada declarado	El paso debe existir en el momento de build()
PipelineManifestBuilder::build	ninguno	Construye el manifiesto validado	PipelineManifest	Igual que PipelineManifest::__construct	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	Opciones de ejecución inmutables	PipelineOptions	Nada declarado	Objeto de valor readonly
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	Definición de paso inmutable	PipelineStep	Nada declarado	La construcción directa establece el tipo de salida a PDF de forma predeterminada para cada tipo
PipelineStep::isRoot	ninguno	True cuando el paso no tiene dependencias	bool	Nada declarado	—
PipelineStepType (enum)	—	Diez casos respaldados por cadena: generate, merge, split, inspect, compress, sign, convert, más los restringidos redact, extract, ocr_overlay	—	—	Un caso por operación integrada
PipelineStepType::requiresPack	ninguno	True para Redact, Extract y OcrOverlay	bool	Nada declarado	Todos los demás casos devuelven false
PipelineStepType::requiredCapability	ninguno	Asigna los casos restringidos a sus códigos de capacidad	?string	Nada declarado	null para los casos no restringidos
PipelineStatus (enum)	—	Cinco casos: pending, running, completed, failed, cancelled	—	—	Compartido por los resultados de pipeline y de paso
PipelineStatus::isTerminal	ninguno	True para Completed, Failed y Cancelled	bool	Nada declarado	Pending y Running no son terminales
StepOutputType (enum)	—	Tres casos: pdf, json, metadata	—	—	Impulsa la validación de aristas en tiempo de construcción
StepOutputType::forStepType	PipelineStepType $stepType	Tipo de salida predeterminado para un tipo de paso	self	Nada declarado	Inspect y Extract se asignan a JSON; todos los demás tipos se asignan a PDF
StepOutputType::isCompatibleWith	self $expectedInput	True para una coincidencia del mismo tipo o una salida PDF	bool	Nada declarado	Auxiliar; PDF es la entrada universal
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	Contexto en memoria por ejecución	PipelineContext	Nada declarado	Sin TTL, caducidad, persistencia ni almacén de respaldo
PipelineContext::setStepResult / ::getStepResult	string $stepId (+ StepResult al establecer)	Registra o lee un resultado de paso	void / ?StepResult	Nada declarado	null para un paso aún no ejecutado
PipelineContext::setStepOutput / ::getStepOutput	string $stepId (+ mixed al establecer)	Almacena o lee una salida intermedia	void / mixed	Nada declarado	null para una salida ausente
PipelineContext::hasStepResult	string $stepId	Si un paso ya se ejecutó	bool	Nada declarado	Admite comprobaciones de reanudación
PipelineContext::allStepResults	ninguno	Todos los resultados registrados hasta el momento	array<string, StepResult>	Nada declarado	Indexado por ID de paso
PipelineContext::isResume	ninguno	Si la ejecución se reanuda desde un paso	bool	Nada declarado	—
PipelineResult::isSuccess	ninguno	True solo para el estado global Completed	bool	Nada declarado	El resultado lo produce el ejecutor
PipelineResult::getStepResult	string $stepId	Encuentra un resultado de paso por ID	?StepResult	Nada declarado	null para pasos omitidos o desconocidos
PipelineResult::failedSteps	ninguno	Filtra los resultados de paso fallidos	list<StepResult>	Nada declarado	Lista vacía cuando todo tiene éxito
StepResult::isSuccess	ninguno	True solo para el estado de paso Completed	bool	Nada declarado	Lleva stepId, type, status, durationMs, error, output
CapabilityResolverInterface::hasCapability	string $capability	Prueba afirmativa de derecho para un código de capacidad	bool	No debe lanzar	Denegación por omisión: false para códigos desconocidos, caducados o no asignados

Firmas de los puntos de entrada

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

Contrato de comportamiento

Validación del manifiesto

La validación se ejecuta en el constructor de PipelineManifest, antes de cualquier ejecución. En orden: la lista de pasos no debe estar vacía; el número de pasos está limitado a 10 000, lo que convierte cadenas de dependencias adversarialmente profundas en una OverflowException capturable en lugar de un agotamiento nativo de la pila; los IDs de paso deben ser únicos; toda referencia dependsOn debe resolverse; el grafo de dependencias debe ser acíclico; los tipos de salida deben ser compatibles; un paso de reanudación declarado debe existir. Cada infracción lanza InvalidArgumentException con un mensaje específico.

La comprobación de tipo de salida se aplica a los pasos cuyo tipo se asigna a salida PDF: toda dependencia de un paso así debe producir a su vez salida PDF. Las aristas de dependencia hacia tipos de paso que producen JSON (inspect, extract) no se comprueban por tipo en esta versión.

Orden de ejecución, reanudación y tiempo de espera

execute($manifest, $variables) construye un PipelineContext nuevo, calcula el orden topológico y ejecuta los pasos secuencialmente en ese orden. Con un punto de reanudación establecido, los pasos anteriores se omiten hasta alcanzar el paso indicado. Los predecesores omitidos no se vuelven a ejecutar y sus salidas no se restauran: el contexto es por ejecución y en memoria, de modo que un paso reanudado que lea la salida de un predecesor omitido observa null.

El tiempo de espera global, cuando es positivo, se evalúa entre pasos, antes de que comience cada paso. Al expirar, el estado del pipeline pasa a Failed y los pasos restantes no comienzan. Un paso que ya se está ejecutando nunca se interrumpe a mitad de ejecución, por lo que un paso largo puede exceder el presupuesto.

Reintentos y captura de fallos

Cada paso recibe como máximo maxRetries + 1 intentos. Un intento con éxito retorna de inmediato. Cualquier intento fallido —un resultado Failed del resolver o un Throwable lanzado— se reintenta mientras queden intentos; se devuelve el resultado del último intento. Un Throwable lanzado dentro de un resolver se degrada a un resultado de paso Failed que lleva el mensaje de la excepción, o Unknown error cuando el mensaje está vacío. Por tanto, execute() siempre devuelve un PipelineResult; nunca propaga un fallo del resolver.

Un tipo de paso sin resolver registrado produce un resultado de paso Failed con un mensaje explícito; la ejecución no se aborta. Con stopOnError en true (el valor predeterminado), la ejecución se detiene en el primer paso fallido y el estado del pipeline es Failed. Con él en false, la ejecución continúa y el estado final es Failed si algún paso falló, y Completed en caso contrario.

Barrera de capacidad de Pack

Antes de cualquier despacho de resolver, cada paso restringido por Pack (Redact, Extract, OcrOverlay) se comprueba contra el CapabilityResolverInterface inyectado. La barrera es fail-closed: un resolver ausente, una respuesta false o un código de capacidad no asignado rechazan el paso en todos los casos. El rechazo produce un resultado de paso Failed cuyo error lleva el código SPEC-LIC-001, el tipo de paso y la capacidad requerida. Un rechazo por barrera no consume intentos de reintento e informa una duración de 0.0. Las implementaciones del resolver deben devolver true únicamente para un derecho poseído de forma afirmativa y no deben lanzar.

Agregación de resultados

PipelineResult informa el ID del manifiesto, el estado global, los resultados por paso en orden de ejecución, la duración total en milisegundos y los recuentos de pasos totales, completados y fallidos. stepsTotal cuenta todos los pasos del manifiesto, incluidos los pasos omitidos por reanudación o no alcanzados tras una detención; stepsCompleted y stepsFailed cuentan solo los pasos ejecutados.

Casos límite y modos de fallo

• El ejecutor está diseñado para ejecución asíncrona dentro de un worker de trabajos. El uso en línea bloquea al llamador durante toda la duración del pipeline.
• El tiempo de espera global es una comprobación entre pasos. Un solo paso largo puede exceder el presupuesto; ningún paso se interrumpe a mitad de ejecución.
• La reanudación omite pasos únicamente dentro de la misma ejecución. No restaura salidas de ningún almacén; la reanudación entre ejecuciones con salidas en caché no está implementada.
• Construir PipelineStep directamente establece el tipo de salida a PDF de forma predeterminada para cada tipo de paso. Utilice el builder, o pase el tipo de salida de forma explícita, para que los pasos inspect y extract declaren salida JSON y la validación de aristas siga siendo significativa.
• Una excepción del resolver con un mensaje vacío se normaliza a Unknown error en el resultado del paso.
• Los resultados de paso Failed producidos por la barrera o por un resolver ausente informan una duración de 0.0.
• PipelineResult::getStepResult() devuelve null tanto para IDs desconocidos como para pasos omitidos por reanudación o por una detención; distíngalos mediante stepsTotal frente a la longitud de la lista de resultados.
• Este módulo no realiza operaciones criptográficas ni define ningún comportamiento específico de FIPS. La postura FIPS para el paso sign se rige por el módulo de firma, no por el pipeline.

Conformidad

El pipeline no realiza ningún trabajo de conformidad de formato por sí mismo. La conformidad de cada artefacto producido corresponde al módulo que hay detrás del paso en ejecución —firma, optimización, conversión, etc.— y se documenta en las páginas de referencia de esos módulos. Esta página no reivindica identificadores de cláusula externos; toda afirmación se fundamenta en el código fuente del producto. NextPDF no formula ninguna afirmación de certificación.

Notas de desarrollo

• El código fuente del módulo lleva @since 2.2.0; esta referencia documenta la superficie tal como se distribuye en nextpdf/pro 3.1.0.
• Todas las clases son final; los tipos de manifiesto, opciones, paso y resultado son objetos de valor readonly. Construya nuevas instancias en lugar de mutarlas.
• StepResolverInterface y StepResolverRegistry son @internal. Los resolvers de paso son solo integrados; los manejadores de paso personalizados definidos por el usuario no se admiten en esta versión.
• CapabilityResolverInterface es la costura pública de derechos. Las implementaciones deben ser de denegación por omisión y no deben permitir por defecto.
• Este ejecutor de PHP es la ruta de validación del manifiesto y ejecución secuencial; los despliegues de producción pueden despachar a través del sidecar para orquestación paralela. La barrera de capacidad en la ruta de PHP es fail-closed de forma independiente en cualquier caso.
• El detalle del mecanismo interno permanece en la documentación interna del repositorio de código fuente y queda fuera del alcance de este manual.

Límite de publicación

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

Véase también

• Output Pipeline — la página de capacidad para orientación sobre el flujo de trabajo.
• Output Pipeline — Referencia detallada de NextPDF Enterprise — orquestación por lotes entre manifiestos.
• Document — Referencia detallada
• Accelerator — Referencia detallada