Pro edição

Output Pipeline

Visão geral

O Output Pipeline executa um manifesto declarativo de etapas de PDF em ordem de dependência, com retentativas por etapa e uma opção de parar em caso de erro. Alguns tipos de etapa requerem uma capacidade adicional de Enterprise Pack.

Disponibilidade e licenciamento

Este recurso vem no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem essa habilitação não carrega as classes do recurso. Compare edições e obtenha uma licença.

O próprio executor do pipeline faz parte da edição Pro. Três tipos de etapa requerem, adicionalmente, uma capacidade nomeada de Enterprise Pack: a etapa de tarjamento requer uma capacidade Privacy Pack, e as etapas de extração e de sobreposição de OCR requerem capacidades Intelligence Pack. Uma etapa restrita sem licença falha de forma segura (fail-closed) na execução — ela produz um resultado de etapa com falha e seu resolvedor nunca é invocado — em vez de abortar a execução inteira.

Instalação

composer require nextpdf/pro:^3

O código está sob o namespace NextPDF\Pro\OutputPipeline.

Visão conceitual

PipelineExecutor recebe um PipelineManifest, ordena as etapas em ordem topológica e despacha cada etapa para um resolvedor registrado no StepResolverRegistry. As saídas das etapas são armazenadas em um PipelineContext para as etapas subsequentes. O executor impõe um timeout global, oferece suporte a retentativas por etapa e pode retomar a partir de uma etapa nomeada. Ele foi projetado para ser executado dentro de um worker de job assíncrono, não diretamente a partir de um handler de requisição.

Os tipos de etapa integrados incluem generate, merge, split, inspect, compress, sign e convert. Os tipos de etapa de tarjamento, extração e sobreposição de OCR são licenciados por capacidade e mapeiam para capacidades de Enterprise Pack.

Por que funciona assim

O executor é apenas orquestração. Ele ordena as etapas, impõe a restrição de licença e despacha cada uma para um resolvedor registrado, mas não realiza nenhum trabalho de PDF por si só. Essa divisão permite que um mesmo manifesto seja executado tanto por este caminho sequencial em PHP quanto por um worker externo que despacha etapas em paralelo, sem alteração no código chamador. O design tem como alvo um worker de job assíncrono em vez de um handler de requisição, porque um pipeline de múltiplas etapas rotineiramente ultrapassa o orçamento de uma requisição, e uma fila escala a vazão adicionando workers. O timeout global é verificado entre as etapas pelo mesmo motivo: uma etapa inteira é a unidade de trabalho entregue a um resolvedor, e o orquestrador não interfere na execução desse resolvedor. As falhas se manifestam como valores StepResult por etapa em vez de exceções lançadas, de modo que uma etapa com falha nunca colapsa o PipelineResult agregado que o worker reporta.

Contexto de design: Geração de documentos em alto volume.

Contrato de comportamento

execute($manifest, $variables) retorna um resultado com o status geral, os resultados por etapa, a duração e as contagens de etapas concluídas e com falha.
As etapas são executadas em ordem topológica; um resolvedor ausente para um tipo de etapa produz uma etapa com falha com uma mensagem clara.
PipelineOptions::$stopOnError interrompe a execução na primeira falha; caso contrário, a execução continua e o status final reflete quaisquer falhas.
O timeout global, quando definido, faz o pipeline falhar se ele for excedido antes do início da próxima etapa.
As retentativas por etapa são limitadas pelo máximo configurado; apenas falhas não terminais são repetidas.
A retomada a partir de uma etapa pula as etapas anteriores até que a etapa nomeada seja alcançada.
Os tipos de etapa restritos por capacidade falham de forma segura na execução com um código de erro de licença quando a capacidade de Pack necessária está ausente; o resolvedor nunca é invocado.

Exemplo de código — Início rápido

O exemplo a seguir reflete a API pública documentada. O repositório não fornece um exemplo executável para este módulo.

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

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

Exemplo de código — Produção

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 extremos e armadilhas

O pipeline foi projetado para ser executado de forma assíncrona por meio de um sistema de jobs. Executá-lo de forma inline bloqueia o chamador durante toda a duração do pipeline.
Um tipo de etapa sem resolvedor registrado faz aquela etapa falhar, em vez de abortar o pipeline inteiro (a menos que a opção de parar em caso de erro esteja definida).
O timeout global é verificado entre as etapas, não no meio de uma etapa; uma etapa de longa duração pode ultrapassar o orçamento antes que a verificação seja disparada.

Desempenho

A duração total é a soma das durações das etapas mais a sobrecarga de retentativas. O timeout global limita o tempo de parede no pior caso. Não há um valor de throughput publicado; o custo do pipeline é dominado pelas etapas que você inclui. Meça com manifestos representativos.

Notas de segurança

O executor passa documentos de entrada e variáveis aos resolvedores de etapa; trate-os como não confiáveis e valide-os dentro de cada resolvedor. As etapas restritas por capacidade falham de forma segura (fail-closed) quando sem licença. O executor não registra nenhum conteúdo do documento.

Conformidade

O executor não realiza nenhum trabalho de conformidade de formato por si só; a conformidade depende dos resolvedores de etapa individuais (generate, merge, split, sign, convert). O corpus de RAG estava indisponível no momento da autoria, então esta página não afirma nenhum identificador de cláusula externo.

Nota sobre o limite do Enterprise

O Enterprise acrescenta as capacidades de Pack que desbloqueiam os tipos de etapa restritos (tarjamento, extração, sobreposição de OCR) em nível de comportamento. Sem esses Packs, o pipeline ainda executa todas as etapas não restritas. Os detalhes internos dos Packs estão fora do escopo aqui.

Fallback / alternativa do Core

Sem o Pro, orquestre as operações de PDF de forma imperativa com as APIs do NextPDF Core; o manifesto declarativo, a ordenação por dependência e as retentativas são adições do Pro..

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície da API pública suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de ticket estão fora do escopo.