Inspect: introspecção e preflight de PDF

Visão geral

O módulo Inspect lê um arquivo Portable Document Format (PDF) existente e informa o que ele contém: pontuação de complexidade, auditorias de fontes e imagens, dicas de conformidade e sinalizadores de risco. Uma política de preflight transforma esse relatório em uma decisão de pass/fail, para que você possa filtrar o documento antes que ele entre em um pipeline.

Estabilidade: experimental. A introspecção ainda está evoluindo. A forma de InspectResult, o conjunto de sinalizadores de risco e o caminho opcional de inspeção acelerada podem mudar entre versões menores. Use-o para diagnóstico e filtragem; ainda não dependa da forma desse resultado para contratos de longa duração.

Instalação

composer require nextpdf/core:^3

Visão conceitual

Use o Inspector como ponto de entrada. Ele implementa InspectorInterface e expõe um método: inspect(string $pdfData, InspectConfig $config = new InspectConfig()): InspectResult. É somente leitura: analisa e caracteriza um PDF; ele não modifica o documento.

InspectResult é o relatório estruturado. Ele inclui pontuação de complexidade, auditorias, dicas e um conjunto de RiskFlags. Use hasRisks() / hasRisk(RiskFlag $flag) para ramificar com base em um risco específico, em vez de analisar texto livre. ComplexityScore expõe uma pontuação numérica e uma faixa de category(). FontAuditEntry e ImageAuditEntry descrevem recursos incorporados. ComplianceHint sinaliza prováveis problemas de conformidade. InspectIssue registra uma constatação específica. InspectDepth define a profundidade da inspeção, e toSpectrumDepth() mapeia essa profundidade para o caminho acelerado quando o sidecar Spectrum está disponível. A inspeção funciona sem o sidecar. O sidecar altera apenas o desempenho, não o contrato. InspectResponseParser constrói um InspectResult a partir de uma resposta bruta (por exemplo, a resposta do caminho acelerado) com um ID de rastreamento opcional.

PreflightPolicy é a camada de decisão. evaluate(InspectResult $result) aplica uma política configurada a um resultado e retorna o desfecho dessa política. O módulo inteiro é @since 2.2.0.

Superfície da API

Tipo	Membros principais	Função
Inspector	inspect(string $pdfData, InspectConfig $config): InspectResult	Inspetor de PDF somente leitura (@since 2.2.0)
InspectResult	hasRisks(), hasRisk(RiskFlag), acessadores de score/audit	Relatório estruturado de inspeção (@since 2.2.0)
ComplexityScore	category()	Pontuação numérica de complexidade + faixa (@since 2.2.0)
FontAuditEntry / ImageAuditEntry	acessadores de recursos	Auditorias de recursos incorporados (@since 2.2.0)
ComplianceHint / InspectIssue	acessadores de constatações	Dicas e constatações de conformidade (@since 2.2.0)
InspectDepth (enum)	toSpectrumDepth()	Profundidade da inspeção → caminho acelerado (@since 2.2.0)
PreflightPolicy	evaluate(InspectResult): array, toArray()	Decisão pass/fail de preflight (@since 2.2.0)
InspectResponseParser	parse(array, InspectConfig, ?string $traceId): InspectResult	Constrói um resultado a partir de uma resposta bruta (@since 2.2.0)

Execute composer docs:generate-api-php -- --module=Inspect para gerar a tabela completa de PHPDoc.

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

Fonte: examples/34-inspect-layout-boxes.php demonstra como ler a geometria da página. Este exemplo inspeciona o perfil de risco de um PDF arbitrário:

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Inspect\Inspector;

$result = (new Inspector())->inspect(file_get_contents('/srv/in/incoming.pdf'));

if ($result->hasRisks()) {
    echo "Complexity: {$result->complexityScore()->category()}; risks present.\n";
}

Exemplo de código — Produção

Filtre um PDF recebido com uma política de preflight e rejeite-o diante de qualquer risco.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Inspect\Inspector;
use NextPDF\Inspect\PreflightPolicy;
use Psr\Log\LoggerInterface;

final readonly class IngestPreflight
{
    public function __construct(
        private Inspector $inspector,
        private PreflightPolicy $policy,
        private LoggerInterface $logger,
    ) {}

    public function accept(string $pdfData): bool
    {
        $result = $this->inspector->inspect($pdfData);
        $verdict = $this->policy->evaluate($result);

        if ($verdict !== []) {
            $this->logger->warning('PDF rejected at preflight.', ['findings' => $verdict]);

            return false;
        }

        return true;
    }
}

Casos extremos e armadilhas

• inspect() é somente leitura. Ele nunca modifica nem repara a entrada; não espere que retorne um documento “corrigido”.
• hasRisk(RiskFlag) é a verificação precisa. Ramificar apenas com base em hasRisks() trata todos os riscos de forma idêntica; em geral, você quer um sinalizador específico.
• InspectDepth controla o custo. Uma inspeção profunda de um PDF grande é significativamente mais lenta; use a menor profundidade que responda à sua pergunta.
• O caminho acelerado por Spectrum altera o desempenho, não o contrato do resultado. Programe contra InspectResult, não contra a forma da resposta acelerada.
• PreflightPolicy::evaluate() retorna as constatações; ele não lança exceção. Um resultado vazio é uma aprovação; aja de acordo com o valor de retorno.

Desempenho

O custo da inspeção aumenta conforme o tamanho do documento e o InspectDepth escolhido. A inspeção rasa é rápida; uma auditoria profunda de um PDF grande pode se aproximar do orçamento. O caminho Spectrum descarrega a análise pesada quando disponível. O performance_budget de 1500 ms de tempo real / 64 MB de pico descreve a carga de trabalho de referência. O perfil de reprodutibilidade é structural: um resultado pode incluir um ID de rastreamento e medições de tempo. Duas execuções podem variar nesses campos, enquanto as constatações permanecem estáveis para a mesma entrada.

Notas de segurança

Inspector::inspect() analisa bytes de PDF não confiáveis; essa é a finalidade dele, portanto trate a entrada como hostil. Execute a inspeção em um worker restrito para documentos fornecidos pelo usuário e limite o tamanho da entrada na origem. Um PDF deliberadamente complexo é um vetor de negação de serviço, independentemente da profundidade. O resultado descreve o documento, mas não o sanitiza; um veredito de “baixo risco” é uma heurística, não uma garantia de segurança. Trate as strings e os metadados extraídos como não confiáveis. Consulte o modelo de ameaças do motor em /modules/core/security/.

Conformidade

Este módulo relata dicas de conformidade; ele não fornece o veredito definitivo de conformidade. ComplianceHint sinaliza prováveis problemas de forma heurística. Para PDF/A, PDF/UA e International Organization for Standardization (ISO) 32000-2, o veredito definitivo de conformidade vem dos validadores de referência acionados por /modules/core/cli/ e dos conjuntos oracle e golden descritos em /modules/core/conformance/. Não trate um resultado limpo do Inspect como certificação de conformidade.

Veja também

• Módulo Cli — aciona os validadores externos definitivos.
• Visão geral de conformidade — descreve o veredito definitivo e os conjuntos golden.
• Módulo Accelerator — descreve o caminho opcional de inspeção acelerada.
• Modelo de segurança do motor