Pro edition

Optimizer

At a glance

The Optimizer analyzes a PDF for duplicate objects and image-recompression potential, then reports the estimated size reduction. Three levels trade output fidelity against file size.

Availability & licensing

This capability ships in NextPDF Pro (nextpdf/pro) and activates with a Pro-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

There is no separate per-feature license flag. The optimization level (lossless, balanced, aggressive) is a runtime parameter, not a license switch.

Install

composer require nextpdf/pro:^3

The code lives under the NextPDF\Pro\Optimizer namespace.

Conceptual overview

PdfOptimizer coordinates an object deduplicator and an image recompressor. Given raw PDF bytes, it finds duplicate object groups (when the level allows it), analyzes images, and estimates compression for each image at the level’s target quality. It aggregates the findings into an OptimizationResult reporting original size, estimated optimized size, objects removed, and image counts before and after.

OptimizationLevel defines the trade-off: lossless preserves image quality and skips deduplication for byte-stable output; balanced deduplicates and targets 75 percent image quality; aggressive deduplicates, downsamples, and targets 50 percent quality.

Why it works this way

The optimizer analyzes rather than rewrites. analyze() estimates potential savings and returns an OptimizationResult without mutating the input. That keeps the pass non-destructive and lets you decide whether to apply it through the Writer. The level abstraction holds the trade-off in one place: lossless returns false from deduplicateStreams() so output can stay byte-identical, while balanced and aggressive recompress image streams at lower quality targets. Achievable savings depend on how a document already encodes its streams and images, so the module reports an estimate from the objects actually present rather than a fixed headline figure. Design background: Streams and filters.

Behavior contract

analyze($pdfData) returns an OptimizationResult; it does not mutate the input.
The lossless level skips stream deduplication so output can stay byte-stable; balanced and aggressive enable deduplication.
Image quality targets are 100, 75, and 50 percent for lossless, balanced, and aggressive respectively.
The estimated optimized size never falls below zero and never exceeds the original.
withLevel($level) returns a new optimizer at the requested level; instances are not mutated.

Code sample — Quick start

The following reflects the documented public API. The repository does not ship a runnable example for this module.

use NextPDF\Pro\Optimizer\PdfOptimizer;

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

Code sample — Production

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;

Edge cases & gotchas

analyze() estimates potential; pair it with the Writer module to produce an optimized document.
The lossless level intentionally yields little size reduction because it preserves quality and skips deduplication.
Image-count-after reflects images removed through deduplication, not images dropped.

Performance

Analysis is linear in input size plus the cost of scanning object and image structures. The level controls how aggressive deduplication and recompression estimates are. There is no published fixed size-reduction figure; results depend entirely on the document. Measure with representative documents.

Security notes

Treat input as untrusted. Analysis stays read-only and does not execute embedded content. This module logs no document content.

Conformance

Optimization operates on the PDF object and image model defined by ISO 32000-2; the source annotates the relevant clauses.

Enterprise boundary note

Enterprise does not change Optimizer behavior. Enterprise adds higher-tier compliance and archival features documented separately; they are not required to analyze optimization potential.

Core fallback / alternative

Without Pro, use NextPDF Core’s base optimization; object deduplication and tunable image-recompression analysis are Pro additions.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.