Output Pipeline — Referência Profunda

Visão geral

Esta página é a referência profunda da superfície pública de NextPDF\Pro\OutputPipeline. Ela abrange a construção e validação de manifesto, a ordem de execução topológica, a semântica de repetição e tempo limite, o comportamento de retomada e a restrição por capacidade de Pack fail-closed. Ela declara parâmetros, valores padrão e modos de falha de cada símbolo público. Leia primeiro a página de apresentação do Output Pipeline para orientação sobre fluxo de trabalho.

Disponibilidade & licenciamento

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

O executor e sete dos dez tipos de etapa não têm sinalizador por recurso. Três tipos de etapa exigem, adicionalmente, uma capacidade de Pack:

Tipo de etapa	Valor no manifesto	Capacidade necessária	Pack
Tarjamento	redact	pack.privacy.redact	Privacy Pack
Extração	extract	pack.intelligence.extract	Intelligence Pack
Sobreposição de OCR	ocr_overlay	pack.intelligence.searchable_pdf	Intelligence Pack

A restrição é aplicada em tempo de execução, fail-closed, antes de a etapa alcançar seu resolver. Uma etapa restrita sem licença produz um resultado de etapa Failed contendo o código SPEC-LIC-001 e a capacidade necessária; o resolver nunca é invocado. Um pipeline sem resolver de capacidade injetado rejeita todas as etapas restritas.

Superfície da API pública

composer require nextpdf/pro:^3

O metapacote nextpdf/premium instala o código do nextpdf/pro; este módulo reside no namespace NextPDF\Pro\OutputPipeline.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	Vincula o registro de resolvers integrado e a fonte opcional de direitos	PipelineExecutor	Nada declarado	Um resolver de capacidade nulo rejeita todas as etapas restritas por Pack
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	Executa as etapas em ordem topológica e agrega os resultados	PipelineResult	Nada declarado; falhas de resolver são capturadas como resultados de etapa Failed	Projetado para ser executado dentro de um worker de jobs assíncrono
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	Valida o grafo de etapas na construção	PipelineManifest	InvalidArgumentException para uma lista de etapas vazia, IDs de etapa duplicados, dependências desconhecidas, ciclos, incompatibilidade de tipo de saída ou uma etapa de retomada ausente; OverflowException acima de 10 000 etapas	Toda a validação é concluída antes de qualquer execução
PipelineManifest::topologicalOrder	nenhum	Ordena as etapas com dependências antes dos dependentes	list<PipelineStep>	Nada declarado	Determinístico para um dado manifesto
PipelineManifest::getStep	string $stepId	Busca linear por ID de etapa	?PipelineStep	Nada declarado	null para um ID desconhecido
PipelineManifest::rootSteps	nenhum	Retorna as etapas sem dependências	list<PipelineStep>	Nada declarado	As etapas raiz são executadas primeiro
PipelineManifestBuilder::create	string $manifestId	Inicia um novo builder	self	Nada declarado	O construtor é privado; este é o único ponto de entrada
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	Anexa uma etapa; um tipo de saída nulo é inferido a partir do tipo de etapa	self	Nada declarado	A validação é adiada para build()
PipelineManifestBuilder::stopOnError	bool $stop = true	Define a interrupção na primeira falha	self	Nada declarado	Padrão true
PipelineManifestBuilder::maxRetries	int $retries	Define o teto de repetições por etapa	self	Nada declarado	Padrão 0 (sem repetições)
PipelineManifestBuilder::timeout	int $timeoutMs	Define o tempo limite global do pipeline	self	Nada declarado	0 desativa o tempo limite
PipelineManifestBuilder::resumeFrom	string $stepId	Define o ponto de retomada	self	Nada declarado	A etapa deve existir no momento de build()
PipelineManifestBuilder::build	nenhum	Constrói o manifesto validado	PipelineManifest	Como PipelineManifest::__construct	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	Opções de execução imutáveis	PipelineOptions	Nada declarado	Objeto de valor readonly
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	Definição de etapa imutável	PipelineStep	Nada declarado	A construção direta usa PDF como tipo de saída padrão para todos os tipos
PipelineStep::isRoot	nenhum	Verdadeiro quando a etapa não tem dependências	bool	Nada declarado	—
PipelineStepType (enum)	—	Dez casos com backing de string: generate, merge, split, inspect, compress, sign, convert, além dos restritos redact, extract, ocr_overlay	—	—	Um caso por operação integrada
PipelineStepType::requiresPack	nenhum	Verdadeiro para Redact, Extract e OcrOverlay	bool	Nada declarado	Todos os outros casos retornam false
PipelineStepType::requiredCapability	nenhum	Mapeia os casos restritos para seus códigos de capacidade	?string	Nada declarado	null para casos não restritos
PipelineStatus (enum)	—	Cinco casos: pending, running, completed, failed, cancelled	—	—	Compartilhado por resultados de pipeline e de etapa
PipelineStatus::isTerminal	nenhum	Verdadeiro para Completed, Failed e Cancelled	bool	Nada declarado	Pending e Running não são terminais
StepOutputType (enum)	—	Três casos: pdf, json, metadata	—	—	Direciona a validação de arestas em tempo de build
StepOutputType::forStepType	PipelineStepType $stepType	Tipo de saída padrão para um tipo de etapa	self	Nada declarado	Inspect e Extract mapeiam para JSON; todos os outros tipos mapeiam para PDF
StepOutputType::isCompatibleWith	self $expectedInput	Verdadeiro para correspondência do mesmo tipo ou uma saída PDF	bool	Nada declarado	Auxiliar; PDF é a entrada universal
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	Contexto em memória por execução	PipelineContext	Nada declarado	Sem TTL, expiração, persistência ou armazenamento de apoio
PipelineContext::setStepResult / ::getStepResult	string $stepId (+ StepResult no set)	Registra ou lê um resultado de etapa	void / ?StepResult	Nada declarado	null para uma etapa ainda não executada
PipelineContext::setStepOutput / ::getStepOutput	string $stepId (+ mixed no set)	Armazena ou lê uma saída intermediária	void / mixed	Nada declarado	null para uma saída ausente
PipelineContext::hasStepResult	string $stepId	Se uma etapa já foi executada	bool	Nada declarado	Dá suporte às verificações de retomada
PipelineContext::allStepResults	nenhum	Todos os resultados registrados até o momento	array<string, StepResult>	Nada declarado	Indexado por ID de etapa
PipelineContext::isResume	nenhum	Se a execução é retomada a partir de uma etapa	bool	Nada declarado	—
PipelineResult::isSuccess	nenhum	Verdadeiro apenas para o status geral Completed	bool	Nada declarado	O resultado é produzido pelo executor
PipelineResult::getStepResult	string $stepId	Encontra um resultado de etapa por ID	?StepResult	Nada declarado	null para etapas puladas ou desconhecidas
PipelineResult::failedSteps	nenhum	Filtra os resultados de etapa com falha	list<StepResult>	Nada declarado	Lista vazia em caso de sucesso total
StepResult::isSuccess	nenhum	Verdadeiro apenas para o status de etapa Completed	bool	Nada declarado	Contém stepId, type, status, durationMs, error, output
CapabilityResolverInterface::hasCapability	string $capability	Teste afirmativo de direito para um código de capacidade	bool	Não deve lançar	Negação por omissão: false para códigos desconhecidos, expirados ou não mapeados

Assinaturas de ponto 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 comportamento

Validação de manifesto

A validação é executada no construtor de PipelineManifest, antes de qualquer execução. Em ordem: a lista de etapas não pode ser vazia; a contagem de etapas é limitada a 10 000, convertendo cadeias de dependência adversarialmente profundas em uma OverflowException capturável em vez de esgotamento nativo da pilha; os IDs de etapa devem ser únicos; toda referência em dependsOn deve ser resolvida; o grafo de dependências deve ser acíclico; os tipos de saída devem ser compatíveis; uma etapa de retomada declarada deve existir. Cada violação lança InvalidArgumentException com uma mensagem específica.

A verificação de tipo de saída se aplica às etapas cujo tipo mapeia para saída PDF: toda dependência de tal etapa deve, ela própria, produzir saída PDF. Arestas de dependência para tipos de etapa que produzem JSON (inspect, extract) não têm o tipo verificado nesta versão.

Ordem de execução, retomada e tempo limite

execute($manifest, $variables) monta um novo PipelineContext, calcula a ordem topológica e executa as etapas sequencialmente nessa ordem. Com um ponto de retomada definido, as etapas anteriores são puladas até alcançar a etapa nomeada. Os predecessores pulados não são reexecutados e suas saídas não são restauradas: o contexto é por execução e em memória, portanto uma etapa retomada que lê a saída de um predecessor pulado observa null.

O tempo limite global, quando positivo, é avaliado entre as etapas, antes do início de cada etapa. Ao expirar, o status do pipeline torna-se Failed e as etapas restantes não são iniciadas. Uma etapa já em execução nunca é interrompida no meio da execução, portanto uma etapa longa pode ultrapassar o orçamento.

Repetições e captura de falhas

Cada etapa recebe no máximo maxRetries + 1 tentativas. Uma tentativa bem-sucedida retorna imediatamente. Qualquer tentativa com falha — um resultado Failed do resolver ou um Throwable lançado — é repetida enquanto houver tentativas restantes; o resultado da tentativa final é retornado. Um Throwable lançado dentro de um resolver é rebaixado a um resultado de etapa Failed contendo a mensagem da exceção, ou Unknown error quando a mensagem está vazia. Portanto, execute() sempre retorna um PipelineResult; ele nunca propaga uma falha de resolver.

Um tipo de etapa sem resolver registrado produz um resultado de etapa Failed com uma mensagem explícita; a execução não é abortada. Com stopOnError true (o padrão), a execução é interrompida na primeira etapa com falha e o status do pipeline é Failed. Com ele false, a execução continua e o status final é Failed se qualquer etapa falhou, caso contrário Completed.

Restrição por capacidade de Pack

Antes de qualquer despacho de resolver, toda etapa restrita por Pack (Redact, Extract, OcrOverlay) é verificada contra o CapabilityResolverInterface injetado. A restrição é fail-closed: um resolver ausente, uma resposta false ou um código de capacidade não mapeado rejeitam a etapa. A rejeição produz um resultado de etapa Failed cujo erro contém o código SPEC-LIC-001, o tipo de etapa e a capacidade necessária. Uma rejeição restrita não consome tentativas de repetição e informa uma duração de 0.0. As implementações do resolver devem retornar true apenas para um direito afirmativamente mantido e não devem lançar.

Agregação de resultados

PipelineResult informa o ID do manifesto, o status geral, os resultados por etapa em ordem de execução, a duração total em milissegundos e as contagens total, concluídas e com falha de etapas. stepsTotal conta todas as etapas do manifesto, incluindo as etapas puladas pela retomada ou não alcançadas após uma interrupção; stepsCompleted e stepsFailed contam apenas as etapas executadas.

Casos extremos & modos de falha

• O executor é projetado para execução assíncrona dentro de um worker de jobs. O uso inline bloqueia o chamador durante toda a duração do pipeline.
• O tempo limite global é uma verificação entre etapas. Uma única etapa longa pode ultrapassar o orçamento; nenhuma etapa é interrompida no meio do processamento.
• A retomada pula etapas apenas dentro da mesma execução. Ela não restaura saídas de nenhum armazenamento; a retomada entre execuções com saídas em cache não está implementada.
• Construir PipelineStep diretamente usa PDF como tipo de saída padrão para todos os tipos de etapa. Use o builder, ou passe o tipo de saída explicitamente, para que as etapas inspect e extract declarem saída JSON e a validação de arestas continue significativa.
• Uma exceção de resolver com mensagem vazia é normalizada para Unknown error no resultado da etapa.
• Resultados de etapa Failed produzidos pela restrição ou por um resolver ausente informam uma duração de 0.0.
• PipelineResult::getStepResult() retorna null tanto para IDs desconhecidos quanto para etapas puladas pela retomada ou por uma interrupção; distinga por meio de stepsTotal versus o comprimento da lista de resultados.
• Este módulo não realiza operações criptográficas e não define comportamento específico de FIPS. A postura FIPS da etapa sign é regida pelo módulo de assinatura, não pelo pipeline.

Conformidade

O pipeline não realiza nenhum trabalho próprio de conformidade de formato. A conformidade de cada artefato produzido pertence ao módulo por trás da etapa em execução — assinatura, otimização, conversão e assim por diante — e é documentada nas páginas de referência desses módulos. Esta página não afirma nenhum identificador de cláusula externo; cada afirmação está fundamentada na fonte do produto. A NextPDF não faz nenhuma alegação de certificação.

Notas de desenvolvimento

• A fonte do módulo traz @since 2.2.0; esta referência documenta a superfície conforme fornecida no nextpdf/pro 3.1.0.
• Todas as classes são final; os tipos de manifesto, opções, etapa e resultado são objetos de valor readonly. Construa novas instâncias em vez de mutar.
• StepResolverInterface e StepResolverRegistry são @internal. Os resolvers de etapa são apenas integrados; manipuladores de etapa personalizados definidos pelo usuário não são suportados nesta versão.
• CapabilityResolverInterface é a costura pública de direitos. As implementações devem ser de negação por omissão e não devem permitir por padrão.
• Este executor PHP é o caminho de validação de manifesto e execução sequencial; implantações de produção podem despachar por meio do sidecar para orquestração paralela. A restrição por capacidade no caminho PHP é independentemente fail-closed em qualquer caso.
• Detalhes internos de mecanismo permanecem na documentação interna do repositório de código e estão fora do escopo deste manual.

Limite de publicação

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

Veja também

• Output Pipeline — a página de apresentação para orientação sobre fluxo de trabalho.
• Output Pipeline — Referência Profunda do NextPDF Enterprise — orquestração em lote entre manifestos.
• Document — Referência Profunda
• Accelerator — Referência Profunda