Pro edição

Optimizer

Visão geral

O Optimizer analisa um PDF em busca de objetos duplicados e potencial de recompressão de imagens e, em seguida, informa a redução de tamanho estimada. Três níveis equilibram a fidelidade da saída em relação ao tamanho do arquivo.

Disponibilidade e licenciamento

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

Não há um sinalizador de licença separado por recurso. O nível de otimização (lossless, balanced, aggressive) é um parâmetro de tempo de execução, não uma chave de licença.

Instalação

composer require nextpdf/pro:^3

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

Visão conceitual

PdfOptimizer coordena um deduplicador de objetos e um recompressor de imagens. Dados bytes brutos de PDF, ele encontra grupos de objetos duplicados (quando o nível permite), analisa imagens e estima a compressão de cada imagem na qualidade-alvo do nível. Ele agrega os achados em um OptimizationResult que informa o tamanho original, o tamanho otimizado estimado, os objetos removidos e as contagens de imagens antes e depois.

OptimizationLevel define o equilíbrio: lossless preserva a qualidade da imagem e pula a deduplicação para uma saída byte-estável; balanced faz a deduplicação e tem como alvo 75 por cento de qualidade de imagem; aggressive faz a deduplicação, faz downsampling e tem como alvo 50 por cento de qualidade.

Por que funciona assim

O otimizador analisa em vez de reescrever. analyze() estima as economias potenciais e retorna um OptimizationResult sem alterar a entrada. Isso mantém a passagem não destrutiva e deixa você decidir se vai aplicá-la por meio do Writer. A abstração de nível concentra o equilíbrio em um único lugar: lossless retorna false de deduplicateStreams() para que a saída possa permanecer byte-idêntica, enquanto balanced e aggressive recomprimem os streams de imagem em metas de qualidade mais baixas. As economias alcançáveis dependem de como um documento já codifica seus streams e imagens, então o módulo informa uma estimativa a partir dos objetos realmente presentes, em vez de um número fixo de destaque. Contexto de projeto: Streams e filtros.

Contrato de comportamento

analyze($pdfData) retorna um OptimizationResult; ele não altera a entrada.
O nível lossless pula a deduplicação de streams para que a saída possa permanecer byte-estável; balanced e aggressive habilitam a deduplicação.
As metas de qualidade de imagem são 100, 75 e 50 por cento para lossless, balanced e aggressive, respectivamente.
O tamanho otimizado estimado nunca fica abaixo de zero e nunca excede o original.
withLevel($level) retorna um novo otimizador no nível solicitado; as instâncias não são alteradas.

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\Optimizer\PdfOptimizer;

$result = (new PdfOptimizer())->analyze($pdfBytes);

Exemplo de código — Produção

use NextPDF\Pro\Optimizer\PdfOptimizer;
use NextPDF\Pro\Optimizer\OptimizationLevel;

$optimizer = new PdfOptimizer(OptimizationLevel::Aggressive);
$result = $optimizer->analyze($pdfBytes);

$savings = $result->originalSize > 0
    ? (1 - $result->optimizedSize / $result->originalSize) * 100
    : 0.0;

Casos extremos e armadilhas

analyze() estima o potencial; combine-o com o módulo Writer para produzir um documento otimizado.
O nível lossless intencionalmente produz pouca redução de tamanho porque preserva a qualidade e pula a deduplicação.
A contagem de imagens “depois” reflete as imagens removidas por deduplicação, não as imagens descartadas.

Desempenho

A análise é linear em relação ao tamanho da entrada, mais o custo de varrer as estruturas de objetos e imagens. O nível controla quão agressivas são as estimativas de deduplicação e recompressão. Não há um valor fixo publicado de redução de tamanho; os resultados dependem inteiramente do documento. Meça com documentos representativos.

Notas de segurança

Trate a entrada como não confiável. A análise permanece somente leitura e não executa conteúdo incorporado. Este módulo não registra nenhum conteúdo do documento.

Conformidade

A otimização opera sobre o modelo de objetos e imagens do PDF definido pela ISO 32000-2; a fonte anota as cláusulas relevantes. 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 e limita as declarações de conformidade ao comportamento verificado pelos testes do módulo.

Nota sobre o limite do Enterprise

O Enterprise não altera o comportamento do Optimizer. O Enterprise acrescenta recursos de conformidade e arquivamento de nível superior documentados separadamente; eles não são necessários para analisar o potencial de otimização.

Fallback / alternativa do Core

Sem o Pro, use a otimização básica do NextPDF Core; a deduplicação de objetos e a análise ajustável de recompressão de imagens 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 tickets estão fora de escopo.