Optimizer — Referência Profunda

Visão geral

Esta página é a referência profunda da superfície pública de NextPDF\Pro\Optimizer. Ela cobre o orquestrador de análise, os níveis de otimização, os dois scanners e os objetos de valor de resultado. Ela declara parâmetros, padrões, a aritmética de estimativa e os modos de falha. A análise é somente leitura: ela estima a economia e não produz nenhum documento de saída. Leia primeiro a página de capacidade do Optimizer para orientação de fluxo de trabalho.

Disponibilidade e licenciamento

Esta capacidade acompanha o NextPDF Pro (nextpdf/pro) e é ativada com um envelope de licença de nível Pro. Uma implantação sem esse direito não carrega as classes da capacidade. Compare as edições e obtenha uma licença.

O Optimizer não tem sinalizador de licença por recurso. Esta é uma capacidade da edição Pro. O nível de otimização é um parâmetro de tempo de execução, não um interruptor de licença.

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 sob o namespace NextPDF\Pro\Optimizer.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
PdfOptimizer::__construct	OptimizationLevel $level = OptimizationLevel::Balanced	Constrói um otimizador no nível fornecido	PdfOptimizer	Nada declarado	Constrói suas próprias instâncias de scanner
PdfOptimizer::analyze	string $pdfData	Análise somente leitura no nível configurado	OptimizationResult	OverflowException para entrada acima de 100.000.000 bytes; InvalidArgumentException dos scanners para dados PDF inválidos	Apenas estima; não produz documento de saída
PdfOptimizer::withLevel	OptimizationLevel $level	Retorna um novo otimizador no nível solicitado	self	Nada declarado	A instância receptora permanece inalterada
OptimizationLevel	casos Lossless, Balanced, Aggressive	Enum baseado em string dos níveis de agressividade	—	—	Valores de apoio lossless, balanced, aggressive
OptimizationLevel::label	nenhum	Rótulo de nível legível por humanos	string	Nada declarado	Para uso em exibição
OptimizationLevel::imageQuality	nenhum	Qualidade de imagem alvo para o nível	int	Nada declarado	100, 75 ou 50
OptimizationLevel::deduplicateStreams	nenhum	Se o nível habilita a deduplicação	bool	Nada declarado	false somente para Lossless
OptimizationResult::__construct	int $originalSize, int $optimizedSize, int $objectsRemoved, int $imagesBefore, int $imagesAfter, float $processingTimeMs	Resultado de análise imutável	OptimizationResult	Nada declarado	Todas as propriedades são públicas e readonly
OptimizationResult::savedBytes	nenhum	Tamanho original menos o tamanho otimizado estimado	int	Nada declarado	Bytes
OptimizationResult::savedPercent	nenhum	Redução percentual de tamanho	float	Nada declarado	0.0 quando o tamanho original é zero
OptimizationResult::summary	nenhum	Relatório legível por humanos de várias linhas	string	Nada declarado	Tamanhos formatados como B, KB ou MB
ObjectDeduplicator::findDuplicates	string $pdfData	Agrupa corpos de objeto idênticos por hash SHA-256	list<DuplicateGroup>	InvalidArgumentException para cabeçalho %PDF ausente, entrada acima de 268.435.456 bytes ou mais de 500.000 marcadores de objeto	Retorna apenas grupos com dois ou mais membros
ObjectDeduplicator::estimateSavings	list<DuplicateGroup> $groups	Soma a contagem de duplicatas vezes o tamanho do objeto por grupo	int	Nada declarado	Bytes
ImageRecompressor::analyzeImages	string $pdfData	Extrai metadados de todo XObject de imagem	list<ImageAnalysis>	InvalidArgumentException para cabeçalho %PDF ausente	Ignora objetos sem largura e altura explícitas
ImageRecompressor::suggestCompression	ImageAnalysis $image, OptimizationLevel $level	Recomenda um filtro e estima a economia	ImageCompressionSuggestion	Nada declarado	Heurísticas dependentes do nível; consulte o contrato de comportamento
DuplicateGroup::__construct	string $contentHash, list<int> $objectNumbers, int $objectSize	Registro imutável de grupo de duplicatas	DuplicateGroup	Nada declarado	O primeiro número de objeto é o objeto canônico mantido
DuplicateGroup::duplicateCount	nenhum	Tamanho do grupo menos o objeto canônico	int	Nada declarado	Objetos removíveis por mesclagem
ImageAnalysis::__construct	int $objectNumber, int $width, int $height, string $colorSpace, int $bitsPerComponent, string $filter, int $streamSize	Registro imutável de metadados por imagem	ImageAnalysis	Nada declarado	Os campos espelham as entradas do dicionário de imagem
ImageAnalysis::estimatedDpi	float $displayWidthPt	DPI efetivo na largura de exibição fornecida	float	Nada declarado	0.0 quando a largura de exibição é zero ou negativa
ImageAnalysis::isOverResolution	float $displayWidthPt, int $targetDpi = 300	Sinaliza candidatos a downsampling acima do DPI alvo	bool	Nada declarado	Comparação estritamente maior que
ImageCompressionSuggestion::__construct	int $objectNumber, string $currentFilter, string $suggestedFilter, int $estimatedSavings, string $reason	Registro imutável de recomendação	ImageCompressionSuggestion	Nada declarado	reason é texto explicativo legível por humanos

Assinaturas dos pontos de entrada

final class PdfOptimizer
{
    public function __construct(
        private OptimizationLevel $level = OptimizationLevel::Balanced,
    )

    public function analyze(string $pdfData): OptimizationResult

    public function withLevel(OptimizationLevel $level): self
}

enum OptimizationLevel: string
{
    case Lossless = 'lossless';
    case Balanced = 'balanced';
    case Aggressive = 'aggressive';

    public function label(): string

    public function imageQuality(): int

    public function deduplicateStreams(): bool
}

final readonly class OptimizationResult
{
    public function __construct(
        public int $originalSize,
        public int $optimizedSize,
        public int $objectsRemoved,
        public int $imagesBefore,
        public int $imagesAfter,
        public float $processingTimeMs,
    )

    public function savedBytes(): int

    public function savedPercent(): float

    public function summary(): string
}

final class ObjectDeduplicator
{
    public function findDuplicates(string $pdfData): array

    public function estimateSavings(array $groups): int
}

final class ImageRecompressor
{
    public function analyzeImages(string $pdfData): array

    public function suggestCompression(
        ImageAnalysis $image,
        OptimizationLevel $level,
    ): ImageCompressionSuggestion
}

Contrato de comportamento

Orquestração

PdfOptimizer::analyze aceita bytes brutos de PDF e é somente leitura. Ele primeiro limita a entrada não confiável em 100.000.000 bytes; entrada em excesso levanta OverflowException antes de qualquer varredura ser executada. Em seguida ele executa a análise de deduplicação quando o nível permite, sempre executa a análise de imagem e agrega ambas em um único OptimizationResult. withLevel retorna um novo otimizador; as instâncias nunca são mutadas.

Semântica de nível

Nível	Qualidade de imagem alvo	Deduplicação	Intenção
Lossless	100%	Desligada	Sem perda de qualidade; intenção de saída com estabilidade em bytes
Balanced	75%	Ligada	Compromisso moderado de qualidade; o padrão
Aggressive	50%	Ligada	Redução máxima; downsampling; perda de qualidade visível

Lossless ignora a deduplicação para que a saída possa permanecer estável em bytes. A qualidade alvo alimenta a aritmética de sugestão de imagem abaixo.

Análise de deduplicação

O deduplicador varre definições de objeto indireto de geração zero (N 0 obj até endobj). Cada corpo é aparado do espaço em branco ao redor, hasheado com SHA-256 e agrupado por hash. Definições que diferem apenas em preenchimento ainda assim coincidem. Somente grupos com dois ou mais membros são retornados. A economia estimada por grupo equivale à contagem de duplicatas vezes o tamanho de um único corpo, já que todos os objetos, exceto o canônico, podem ser removidos.

Análise de imagem

Um objeto é tratado como imagem quando seu corpo contém /Subtype /Image (com ou sem espaço interno). Largura e altura são obrigatórias; um objeto sem uma delas é ignorado. O espaço de cor tem como padrão DeviceRGB, os bits por componente 8, e o filtro uma string vazia quando ausente. O tamanho do stream é medido entre os marcadores stream e endstream; quando nenhum stream em linha é encontrado, o valor de /Length é usado no lugar.

Heurísticas de sugestão

• No nível Lossless, o filtro atual é mantido e a economia estimada é zero.
• Para fontes DCTDecode, a sugestão recodifica na qualidade do nível. A estimativa é o tamanho do stream vezes (1 − qualidade/100) vezes 0,5.
• Para fontes FlateDecode, a sugestão converte para DCTDecode. A estimativa é 40% do tamanho do stream em Balanced e 60% em Aggressive.
• Para qualquer outro filtro, ou nenhum filtro, a sugestão converte para FlateDecode. A estimativa é 20% do tamanho do stream.

Aritmética de resultado

• Os objetos removidos equivalem à soma, sobre todos os grupos de duplicatas, dos membros além do primeiro canônico.
• A economia total equivale à economia de deduplicação mais as estimativas de sugestão por imagem.
• O tamanho otimizado estimado é o tamanho original menos a economia total, limitado a zero. A economia é não negativa, então a estimativa nunca excede o tamanho original.
• A contagem de imagens posterior subtrai, para cada grupo de duplicatas que contém uma imagem analisada, a contagem de membros duplicados desse grupo. A contagem é limitada a zero.
• O tempo de processamento é medido com um relógio monotônico e reportado em milissegundos.

O estimador de DPI divide a largura em pixels pela largura de exibição em polegadas (72 pontos por polegada). Uma largura de exibição zero ou negativa resulta em 0.0. O predicado de sobre-resolução compara a estimativa com um alvo, 300 DPI por padrão.

Casos extremos e modos de falha

• analyze reporta apenas o potencial. Produza a saída otimizada com o módulo Writer.
• Entrada vazia, ou entrada que não começa com o cabeçalho %PDF, falha com InvalidArgumentException.
• Entrada acima de 100.000.000 bytes falha com OverflowException na porta de entrada do orquestrador, antes de qualquer varredura.
• O deduplicador rejeita independentemente entrada acima de 268.435.456 bytes e mais de 500.000 marcadores de objeto. Ambas rejeitam de forma fail-closed com InvalidArgumentException; nada é truncado ou parcialmente varrido.
• Apenas definições de objeto de geração zero participam. Objetos com números de geração diferentes de zero não são varridos.
• Uma definição sem um marcador endobj de fechamento é ignorada.
• Objetos de imagem sem largura e altura explícitas são excluídos do relatório de imagem.
• Todos os valores de economia são heurísticas derivadas dos metadados de objeto, não resultados de recompressão medidos.
• O nível lossless reporta intencionalmente reduções pequenas; ele preserva a qualidade e ignora a deduplicação.
• A análise nunca decodifica, executa ou renderiza conteúdo incorporado. Ela lê apenas a estrutura e os metadados dos objetos.
• A única primitiva criptográfica usada é SHA-256, para o agrupamento de conteúdo duplicado. O módulo não define nenhum comportamento específico de FIPS.

Conformidade

Ambos os scanners operam sobre o modelo de objeto e de imagem do PDF da ISO 32000-2:2020. A deduplicação tem como alvo definições de objeto indireto; sua estrutura de identificador é definida na ISO 32000-2:2020, 7.3.10, citada no registro de citação desta página. A análise de imagem lê os parâmetros que um dicionário de imagem declara explicitamente — largura, altura e bits por componente — conforme a ISO 32000-2:2020, 8.9.4, também citada.

Estas declarações descrevem a capacidade em relação às cláusulas citadas. A NextPDF não possui nenhuma certificação de conformidade, e o suporte a uma cláusula não é uma declaração de certificação.

Notas de desenvolvimento

• A fonte do módulo carrega @since 1.9.0; esta referência documenta a superfície conforme entregue em nextpdf/pro 3.1.0.
• Todas as classes são final; os registros de resultado e de análise são objetos de valor readonly. Construa novas instâncias em vez de mutar.
• O nível padrão é Balanced. Selecione outro nível pelo construtor ou pelo método no estilo with.
• O limite de entrada na porta de entrada é imposto por um guard de tamanho de entrada do Core, compartilhado entre as superfícies de entrada do NextPDF.
• A análise é baseada em string sobre bytes já em memória. O módulo não realiza nenhum acesso a sistema de arquivos ou rede.
• Detalhes internos de mecanismo permanecem na documentação interna do repositório de origem e estão fora do escopo deste manual.

Fronteira de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície de API pública suportada. 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

• Optimizer — a página de capacidade para orientação de fluxo de trabalho e exemplos de código.
• Writer — Referência Profunda — produz o documento de saída otimizado.
• Accelerator — Referência Profunda — otimização em lote com descarregamento sidecar na semântica deste módulo.