Optimizer — Diepe referentie

In één oogopslag

Deze pagina is de diepe referentie voor het openbare oppervlak van NextPDF\Pro\Optimizer. Ze behandelt de analyse-orchestrator, de optimalisatieniveaus, de twee scanners en de resultaat-waardeobjecten. Ze beschrijft parameters, standaardwaarden, schattingsberekeningen en foutmodi. Analyse is alleen-lezen: ze schat besparingen en produceert geen uitvoerdocument. Lees eerst de Optimizer-capabilitypagina voor begeleiding bij de workflow.

Beschikbaarheid en licentie

Deze capability wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een licentie-envelop op Pro-niveau. Een deployment zonder dat recht laadt de klassen van de capability niet. Vergelijk edities en vraag een licentie aan.

Optimizer heeft geen licentievlag per functie. Dit is een capability van de Pro-editie. Het optimalisatieniveau is een runtime-parameter, geen licentieschakelaar.

Publiek API-oppervlak

composer require nextpdf/pro:^3

Het nextpdf/premium-metapackage installeert de nextpdf/pro-code; deze module bevindt zich onder de namespace NextPDF\Pro\Optimizer.

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
PdfOptimizer::__construct	OptimizationLevel $level = OptimizationLevel::Balanced	Bouwt een optimizer op het gegeven niveau	PdfOptimizer	Niets gedeclareerd	Construeert zijn eigen scanner-instanties
PdfOptimizer::analyze	string $pdfData	Alleen-lezen analyse op het geconfigureerde niveau	OptimizationResult	OverflowException bij invoer boven 100,000,000 bytes; InvalidArgumentException van de scanners bij ongeldige PDF-data	Schat alleen; produceert geen uitvoerdocument
PdfOptimizer::withLevel	OptimizationLevel $level	Retourneert een nieuwe optimizer op het gevraagde niveau	self	Niets gedeclareerd	De ontvangende instantie blijft ongewijzigd
OptimizationLevel	cases Lossless, Balanced, Aggressive	String-backed enum van agressiviteitsniveaus	—	—	Backing-waarden lossless, balanced, aggressive
OptimizationLevel::label	geen	Leesbaar niveaulabel	string	Niets gedeclareerd	Voor weergavedoeleinden
OptimizationLevel::imageQuality	geen	Doelbeeldkwaliteit voor het niveau	int	Niets gedeclareerd	100, 75 of 50
OptimizationLevel::deduplicateStreams	geen	Of het niveau deduplicatie inschakelt	bool	Niets gedeclareerd	false alleen voor Lossless
OptimizationResult::__construct	int $originalSize, int $optimizedSize, int $objectsRemoved, int $imagesBefore, int $imagesAfter, float $processingTimeMs	Onveranderlijk analyseresultaat	OptimizationResult	Niets gedeclareerd	Alle eigenschappen zijn public en readonly
OptimizationResult::savedBytes	geen	Oorspronkelijke grootte minus geschatte geoptimaliseerde grootte	int	Niets gedeclareerd	Bytes
OptimizationResult::savedPercent	geen	Procentuele groottereductie	float	Niets gedeclareerd	0.0 wanneer de oorspronkelijke grootte nul is
OptimizationResult::summary	geen	Leesbaar rapport over meerdere regels	string	Niets gedeclareerd	Groottes opgemaakt als B, KB of MB
ObjectDeduplicator::findDuplicates	string $pdfData	Groepeert identieke objectbodies op SHA-256-hash	list<DuplicateGroup>	InvalidArgumentException bij een ontbrekende %PDF-header, invoer boven 268,435,456 bytes of meer dan 500,000 objectmarkeringen	Retourneert alleen groepen met twee of meer leden
ObjectDeduplicator::estimateSavings	list<DuplicateGroup> $groups	Telt per groep het aantal duplicaten maal de objectgrootte op	int	Niets gedeclareerd	Bytes
ImageRecompressor::analyzeImages	string $pdfData	Extraheert metadata voor elk image-XObject	list<ImageAnalysis>	InvalidArgumentException bij een ontbrekende %PDF-header	Slaat objecten zonder expliciete breedte en hoogte over
ImageRecompressor::suggestCompression	ImageAnalysis $image, OptimizationLevel $level	Beveelt een filter aan en schat de besparing	ImageCompressionSuggestion	Niets gedeclareerd	Niveauafhankelijke heuristieken; zie het gedragscontract
DuplicateGroup::__construct	string $contentHash, list<int> $objectNumbers, int $objectSize	Onveranderlijk duplicaatgroep-record	DuplicateGroup	Niets gedeclareerd	Het eerste objectnummer is het canonieke behouden object
DuplicateGroup::duplicateCount	geen	Groepsgrootte minus het canonieke object	int	Niets gedeclareerd	Objecten die door samenvoegen verwijderd kunnen worden
ImageAnalysis::__construct	int $objectNumber, int $width, int $height, string $colorSpace, int $bitsPerComponent, string $filter, int $streamSize	Onveranderlijk metadata-record per afbeelding	ImageAnalysis	Niets gedeclareerd	Velden weerspiegelen de items in de image dictionary
ImageAnalysis::estimatedDpi	float $displayWidthPt	Effectieve DPI bij de gegeven weergavebreedte	float	Niets gedeclareerd	0.0 wanneer de weergavebreedte nul of negatief is
ImageAnalysis::isOverResolution	float $displayWidthPt, int $targetDpi = 300	Markeert downsampling-kandidaten boven de doel-DPI	bool	Niets gedeclareerd	Strikt groter-dan-vergelijking
ImageCompressionSuggestion::__construct	int $objectNumber, string $currentFilter, string $suggestedFilter, int $estimatedSavings, string $reason	Onveranderlijk aanbevelingsrecord	ImageCompressionSuggestion	Niets gedeclareerd	reason is leesbare uitleg

Entry-point-signaturen

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
}

Gedragscontract

Orchestratie

PdfOptimizer::analyze accepteert ruwe PDF-bytes en is alleen-lezen. Ze begrenst eerst de niet-vertrouwde invoer op 100,000,000 bytes; te grote invoer werpt OverflowException voordat er een scan draait. Vervolgens draait ze deduplicatie-analyse wanneer het niveau dit toestaat, draait ze altijd image-analyse en aggregeert ze beide tot één OptimizationResult. withLevel retourneert een nieuwe optimizer; instanties worden nooit gemuteerd.

Niveausemantiek

Niveau	Doelbeeldkwaliteit	Deduplicatie	Doel
Lossless	100%	Uit	Geen kwaliteitsverlies; intentie van byte-stabiele uitvoer
Balanced	75%	Aan	Gematigde kwaliteitsafweging; de standaard
Aggressive	50%	Aan	Maximale reductie; downsampling; zichtbaar kwaliteitsverlies

Lossless slaat deduplicatie over zodat de uitvoer byte-stabiel kan blijven. Het kwaliteitsdoel voedt de image-suggestieberekening hieronder.

Deduplicatie-analyse

De deduplicator scant indirecte objectdefinities van generatie nul (N 0 obj tot en met endobj). Elke body wordt ontdaan van omringende witruimte, gehasht met SHA-256 en gegroepeerd op hash. Definities die alleen in padding verschillen, matchen daardoor toch. Alleen groepen met twee of meer leden worden geretourneerd. De geschatte besparing per groep is gelijk aan het aantal duplicaten maal de grootte van één body, aangezien alle objecten behalve het canonieke verwijderd kunnen worden.

Image-analyse

Een object wordt als afbeelding behandeld wanneer zijn body /Subtype /Image bevat (met of zonder interne spatie). Breedte en hoogte zijn verplicht; een object waarin een van beide ontbreekt, wordt overgeslagen. Bij afwezigheid vallen kleurruimte terug op DeviceRGB, bits per component op 8 en het filter op een lege string. De streamgrootte wordt gemeten tussen de markeringen stream en endstream; wanneer geen inline stream wordt gevonden, wordt in plaats daarvan de /Length-waarde gebruikt.

Suggestieheuristieken

• Op het Lossless-niveau wordt het huidige filter behouden en is de geschatte besparing nul.
• Voor DCTDecode-bronnen hercodeert de suggestie op de kwaliteit van het niveau. De schatting is streamgrootte maal (1 − kwaliteit/100) maal 0.5.
• Voor FlateDecode-bronnen converteert de suggestie naar DCTDecode. De schatting is 40% van de streamgrootte bij Balanced en 60% bij Aggressive.
• Voor elk ander filter, of geen filter, converteert de suggestie naar FlateDecode. De schatting is 20% van de streamgrootte.

Resultaatberekening

• Het aantal verwijderde objecten is de som, over alle duplicaatgroepen, van de leden voorbij het canonieke eerste.
• De totale besparing is gelijk aan de deduplicatiebesparing plus de suggestieschattingen per afbeelding.
• De geschatte geoptimaliseerde grootte is de oorspronkelijke grootte minus de totale besparing, met een ondergrens van nul. Besparingen zijn niet-negatief, dus de schatting overschrijdt de oorspronkelijke grootte nooit.
• Het afbeeldingsaantal-na trekt, voor elke duplicaatgroep die een geanalyseerde afbeelding bevat, het aantal duplicaatleden van die groep af. Het aantal heeft een ondergrens van nul.
• De verwerkingstijd wordt gemeten met een monotone klok en gerapporteerd in milliseconden.

De DPI-schatter deelt de pixelbreedte door de weergavebreedte in inches (72 points per inch). Een weergavebreedte van nul of negatief levert 0.0 op. Het over-resolutiepredicaat vergelijkt de schatting met een doel, standaard 300 DPI.

Randgevallen en foutmodi

• analyze rapporteert alleen het potentieel. Produceer geoptimaliseerde uitvoer met de Writer-module.
• Lege invoer, of invoer die niet met de %PDF-header begint, faalt met InvalidArgumentException.
• Invoer boven 100,000,000 bytes faalt met OverflowException bij de voordeur van de orchestrator, vóór elke scan.
• De deduplicator wijst onafhankelijk invoer boven 268,435,456 bytes en meer dan 500,000 objectmarkeringen af. Beide wijzen fail-closed af met InvalidArgumentException; er wordt niets afgekapt of gedeeltelijk gescand.
• Alleen objectdefinities van generatie nul doen mee. Objecten met een generatienummer ongelijk aan nul worden niet gescand.
• Een definitie zonder afsluitende endobj-markering wordt overgeslagen.
• Afbeeldingsobjecten zonder expliciete breedte en hoogte worden uitgesloten van het afbeeldingsrapport.
• Alle besparingscijfers zijn heuristieken afgeleid van objectmetadata, geen gemeten hercompressieresultaten.
• Het lossless-niveau rapporteert opzettelijk kleine reducties; het behoudt de kwaliteit en slaat deduplicatie over.
• Analyse decodeert ingebedde inhoud nooit, voert deze niet uit en rendert deze niet. Ze leest alleen de objectstructuur en metadata.
• De enige gebruikte cryptografische primitieve is SHA-256, voor het groeperen van dubbele inhoud. De module definieert geen FIPS-specifiek gedrag.

Conformiteit

Beide scanners werken op het PDF-object- en afbeeldingsmodel van ISO 32000-2:2020. Deduplicatie richt zich op indirecte objectdefinities; hun identifier-structuur is gedefinieerd in ISO 32000-2:2020, 7.3.10, geciteerd in het citatierecord van deze pagina. Image-analyse leest de parameters die een image dictionary expliciet vermeldt — breedte, hoogte en bits per component — conform ISO 32000-2:2020, 8.9.4, eveneens geciteerd.

Deze uitspraken beschrijven de capability ten opzichte van de geciteerde clausules. NextPDF beschikt over geen conformiteitscertificering, en ondersteuning voor een clausule is geen certificeringsclaim.

Ontwikkelnotities

• De modulebron draagt @since 1.9.0; deze referentie documenteert het oppervlak zoals geleverd in nextpdf/pro 3.1.0.
• Alle klassen zijn final; de resultaat- en analyserecords zijn readonly-waardeobjecten. Construeer nieuwe instanties in plaats van te muteren.
• Het standaardniveau is Balanced. Selecteer een ander niveau via de constructor of de with-stijlmethode.
• De invoerbegrenzing aan de voordeur wordt afgedwongen door een Core-invoergrootte-guard die over de NextPDF-invoeroppervlakken wordt gedeeld.
• Analyse is string-gebaseerd over bytes die al in het geheugen staan. De module voert geen bestandssysteem- of netwerktoegang uit.
• Interne mechanismedetails blijven in de interne documentatie van de bronrepository en vallen buiten de scope van deze handleiding.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Zie ook

• Optimizer — de capabilitypagina voor begeleiding bij de workflow en codevoorbeelden.
• Writer — Diepe referentie — produceert het geoptimaliseerde uitvoerdocument.
• Accelerator — Diepe referentie — batchoptimalisatie met sidecar-offload op de semantiek van deze module.