Optimizer — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die Deep-Referenz für die öffentliche Oberfläche von NextPDF\Pro\Optimizer. Sie behandelt den Analyse-Orchestrator, die Optimierungsstufen, die beiden Scanner und die Ergebnis-Wertobjekte. Sie beschreibt Parameter, Standardwerte, die Schätzarithmetik und die Fehlermodi. Die Analyse ist schreibgeschützt: Sie schätzt Einsparungen und erzeugt kein Ausgabedokument. Lesen Sie zuerst die Optimizer-Fähigkeitsseite für Workflow-Hinweise.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit wird in NextPDF Pro (nextpdf/pro) ausgeliefert und aktiviert sich mit einer Lizenzhülle der Pro-Stufe. Ein Deployment ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und Lizenz beziehen.

Optimizer hat kein feature-spezifisches Lizenz-Flag. Dies ist eine Fähigkeit der Pro-Edition. Die Optimierungsstufe ist ein Laufzeitparameter, kein Lizenzschalter.

Öffentliche API-Oberfläche

composer require nextpdf/pro:^3

Das Metapaket nextpdf/premium installiert den nextpdf/pro-Code; dieses Modul liegt im Namespace NextPDF\Pro\Optimizer.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
PdfOptimizer::__construct	OptimizationLevel $level = OptimizationLevel::Balanced	Erstellt einen Optimizer auf der angegebenen Stufe	PdfOptimizer	Nichts deklariert	Konstruiert eigene Scanner-Instanzen
PdfOptimizer::analyze	string $pdfData	Schreibgeschützte Analyse auf der konfigurierten Stufe	OptimizationResult	OverflowException bei Eingaben über 100,000,000 Bytes; InvalidArgumentException von den Scannern bei ungültigen PDF-Daten	Nur Schätzungen; erzeugt kein Ausgabedokument
PdfOptimizer::withLevel	OptimizationLevel $level	Gibt einen neuen Optimizer auf der angeforderten Stufe zurück	self	Nichts deklariert	Die empfangende Instanz bleibt unverändert
OptimizationLevel	Fälle Lossless, Balanced, Aggressive	String-basiertes Enum der Aggressivitätsstufen	—	—	Backing-Werte lossless, balanced, aggressive
OptimizationLevel::label	keine	Menschenlesbare Stufenbezeichnung	string	Nichts deklariert	Zur Anzeige
OptimizationLevel::imageQuality	keine	Zielbildqualität für die Stufe	int	Nichts deklariert	100, 75 oder 50
OptimizationLevel::deduplicateStreams	keine	Ob die Stufe die Deduplizierung aktiviert	bool	Nichts deklariert	false nur für Lossless
OptimizationResult::__construct	int $originalSize, int $optimizedSize, int $objectsRemoved, int $imagesBefore, int $imagesAfter, float $processingTimeMs	Unveränderliches Analyseergebnis	OptimizationResult	Nichts deklariert	Alle Eigenschaften sind public und readonly
OptimizationResult::savedBytes	keine	Ursprüngliche Größe minus geschätzte optimierte Größe	int	Nichts deklariert	Bytes
OptimizationResult::savedPercent	keine	Prozentuale Größenreduktion	float	Nichts deklariert	0.0, wenn die ursprüngliche Größe null ist
OptimizationResult::summary	keine	Mehrzeiliger, menschenlesbarer Bericht	string	Nichts deklariert	Größen formatiert als B, KB oder MB
ObjectDeduplicator::findDuplicates	string $pdfData	Gruppiert identische Objektkörper nach SHA-256-Hash	list<DuplicateGroup>	InvalidArgumentException bei fehlendem %PDF-Header, Eingaben über 268,435,456 Bytes oder mehr als 500,000 Objektmarkierungen	Gibt nur Gruppen mit zwei oder mehr Mitgliedern zurück
ObjectDeduplicator::estimateSavings	list<DuplicateGroup> $groups	Summiert Duplikatanzahl mal Objektgröße pro Gruppe	int	Nichts deklariert	Bytes
ImageRecompressor::analyzeImages	string $pdfData	Extrahiert Metadaten für jedes Bild-XObject	list<ImageAnalysis>	InvalidArgumentException bei fehlendem %PDF-Header	Überspringt Objekte ohne explizite Breite und Höhe
ImageRecompressor::suggestCompression	ImageAnalysis $image, OptimizationLevel $level	Empfiehlt einen Filter und schätzt die Einsparungen	ImageCompressionSuggestion	Nichts deklariert	Stufenabhängige Heuristiken; siehe den Verhaltensvertrag
DuplicateGroup::__construct	string $contentHash, list<int> $objectNumbers, int $objectSize	Unveränderlicher Duplikatgruppen-Datensatz	DuplicateGroup	Nichts deklariert	Die erste Objektnummer ist das kanonische, beibehaltene Objekt
DuplicateGroup::duplicateCount	keine	Gruppengröße minus das kanonische Objekt	int	Nichts deklariert	Durch Zusammenführung entfernbare Objekte
ImageAnalysis::__construct	int $objectNumber, int $width, int $height, string $colorSpace, int $bitsPerComponent, string $filter, int $streamSize	Unveränderlicher Metadaten-Datensatz pro Bild	ImageAnalysis	Nichts deklariert	Felder spiegeln die Einträge des Bildwörterbuchs wider
ImageAnalysis::estimatedDpi	float $displayWidthPt	Effektive DPI bei der angegebenen Anzeigebreite	float	Nichts deklariert	0.0, wenn die Anzeigebreite null oder negativ ist
ImageAnalysis::isOverResolution	float $displayWidthPt, int $targetDpi = 300	Markiert Downsampling-Kandidaten über der Ziel-DPI	bool	Nichts deklariert	Vergleich strikt größer als
ImageCompressionSuggestion::__construct	int $objectNumber, string $currentFilter, string $suggestedFilter, int $estimatedSavings, string $reason	Unveränderlicher Empfehlungs-Datensatz	ImageCompressionSuggestion	Nichts deklariert	reason ist menschenlesbarer Erläuterungstext

Signaturen der Einstiegspunkte

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
}

Verhaltensvertrag

Orchestrierung

PdfOptimizer::analyze nimmt rohe PDF-Bytes entgegen und ist schreibgeschützt. Zunächst begrenzt es die nicht vertrauenswürdige Eingabe auf 100,000,000 Bytes; überdimensionierte Eingaben lösen OverflowException aus, bevor irgendein Scan läuft. Anschließend führt es die Deduplizierungsanalyse aus, wenn die Stufe es erlaubt, führt immer die Bildanalyse aus und aggregiert beide zu einem OptimizationResult. withLevel gibt einen neuen Optimizer zurück; Instanzen werden niemals mutiert.

Stufensemantik

Stufe	Zielbildqualität	Deduplizierung	Absicht
Lossless	100%	Aus	Kein Qualitätsverlust; Absicht byte-stabiler Ausgabe
Balanced	75%	An	Moderater Qualitätskompromiss; die Standardeinstellung
Aggressive	50%	An	Maximale Reduktion; Downsampling; sichtbarer Qualitätsverlust

Lossless überspringt die Deduplizierung, damit die Ausgabe byte-stabil bleiben kann. Die Zielqualität fließt in die untenstehende Bildvorschlags-Arithmetik ein.

Deduplizierungsanalyse

Der Deduplikator scannt indirekte Objektdefinitionen der Generation null (N 0 obj bis endobj). Jeder Körper wird von umgebendem Leerraum befreit, mit SHA-256 gehasht und nach Hash gruppiert. Definitionen, die sich nur in der Auffüllung unterscheiden, stimmen daher weiterhin überein. Es werden nur Gruppen mit zwei oder mehr Mitgliedern zurückgegeben. Die geschätzten Einsparungen pro Gruppe entsprechen der Duplikatanzahl mal der Größe eines einzelnen Körpers, da alle außer dem kanonischen Objekt entfernt werden können.

Bildanalyse

Ein Objekt wird als Bild behandelt, wenn sein Körper /Subtype /Image enthält (mit oder ohne inneres Leerzeichen). Breite und Höhe sind erforderlich; ein Objekt, dem eines von beiden fehlt, wird übersprungen. Der Farbraum wird standardmäßig auf DeviceRGB gesetzt, die Bits pro Komponente auf 8 und der Filter auf einen leeren String, wenn er fehlt. Die Stream-Größe wird zwischen den Markierungen stream und endstream gemessen; wird kein Inline-Stream gefunden, wird stattdessen der Wert /Length verwendet.

Vorschlagsheuristiken

• Auf der Stufe Lossless wird der aktuelle Filter beibehalten und die geschätzten Einsparungen betragen null.
• Für DCTDecode-Quellen kodiert der Vorschlag mit der Qualität der Stufe neu. Die Schätzung ist die Stream-Größe mal (1 − Qualität/100) mal 0.5.
• Für FlateDecode-Quellen konvertiert der Vorschlag zu DCTDecode. Die Schätzung beträgt 40% der Stream-Größe bei Balanced und 60% bei Aggressive.
• Für jeden anderen Filter oder keinen Filter konvertiert der Vorschlag zu FlateDecode. Die Schätzung beträgt 20% der Stream-Größe.

Ergebnis-Arithmetik

• Entfernte Objekte entsprechen der Summe, über alle Duplikatgruppen, der Mitglieder jenseits des kanonischen ersten.
• Die Gesamteinsparungen entsprechen den Deduplizierungseinsparungen plus den Vorschlagsschätzungen pro Bild.
• Die geschätzte optimierte Größe ist die ursprüngliche Größe minus Gesamteinsparungen, nach unten auf null begrenzt. Einsparungen sind nicht negativ, daher überschreitet die Schätzung nie die ursprüngliche Größe.
• Die Bildzahl danach subtrahiert für jede Duplikatgruppe, die ein analysiertes Bild enthält, die Duplikatmitgliederzahl dieser Gruppe. Die Zahl wird nach unten auf null begrenzt.
• Die Verarbeitungszeit wird mit einer monotonen Uhr gemessen und in Millisekunden angegeben.

Der DPI-Schätzer teilt die Pixelbreite durch die Anzeigebreite in Zoll (72 Punkte pro Zoll). Eine Anzeigebreite von null oder negativ ergibt 0.0. Das Überauflösungs-Prädikat vergleicht die Schätzung mit einem Ziel, standardmäßig 300 DPI.

Edge Cases & Fehlermodi

• analyze meldet nur das Potenzial. Erzeugen Sie optimierte Ausgaben mit dem Writer-Modul.
• Leere Eingaben oder Eingaben, die nicht mit dem %PDF-Header beginnen, scheitern mit InvalidArgumentException.
• Eingaben über 100,000,000 Bytes scheitern mit OverflowException am Eingang des Orchestrators, vor jedem Scan.
• Der Deduplikator lehnt unabhängig Eingaben über 268,435,456 Bytes und mehr als 500,000 Objektmarkierungen ab. Beide lehnen fail-closed mit InvalidArgumentException ab; nichts wird abgeschnitten oder teilweise gescannt.
• Nur Objektdefinitionen der Generation null nehmen teil. Objekte mit von null verschiedenen Generationsnummern werden nicht gescannt.
• Eine Definition ohne abschließende endobj-Markierung wird übersprungen.
• Bildobjekte ohne explizite Breite und Höhe werden vom Bildbericht ausgeschlossen.
• Alle Einsparungswerte sind Heuristiken, abgeleitet aus Objektmetadaten, keine gemessenen Rekompressionsergebnisse.
• Die Lossless-Stufe meldet absichtlich kleine Reduktionen; sie bewahrt die Qualität und überspringt die Deduplizierung.
• Die Analyse dekodiert, führt aus oder rendert eingebettete Inhalte niemals. Sie liest ausschließlich Objektstruktur und Metadaten.
• Das einzige verwendete kryptografische Primitiv ist SHA-256, zur Gruppierung doppelter Inhalte. Das Modul definiert kein FIPS-spezifisches Verhalten.

Konformität

Beide Scanner operieren auf dem PDF-Objekt- und Bildmodell von ISO 32000-2:2020. Die Deduplizierung zielt auf indirekte Objektdefinitionen; ihre Bezeichnerstruktur ist in ISO 32000-2:2020, 7.3.10, definiert, zitiert im Zitat-Datensatz dieser Seite. Die Bildanalyse liest die Parameter, die ein Bildwörterbuch explizit angibt — Breite, Höhe und Bits pro Komponente — gemäß ISO 32000-2:2020, 8.9.4, ebenfalls zitiert.

Diese Aussagen beschreiben die Fähigkeit gegenüber den zitierten Klauseln. NextPDF besitzt keine Konformitätszertifizierung, und die Unterstützung einer Klausel ist keine Zertifizierungsbehauptung.

Entwicklungshinweise

• Der Modulquellcode trägt @since 1.9.0; diese Referenz dokumentiert die Oberfläche, wie sie in nextpdf/pro 3.1.0 ausgeliefert wird.
• Alle Klassen sind final; die Ergebnis- und Analyse-Datensätze sind readonly-Wertobjekte. Konstruieren Sie neue Instanzen, anstatt zu mutieren.
• Die Standardstufe ist Balanced. Wählen Sie über den Konstruktor oder die with-artige Methode eine andere Stufe.
• Die Eingangs-Eingabegrenze wird durch einen Core-Eingabegrößenwächter durchgesetzt, der über die NextPDF-Eingabeoberflächen hinweg geteilt wird.
• Die Analyse ist string-basiert über bereits im Speicher befindliche Bytes. Das Modul führt keinen Dateisystem- oder Netzwerkzugriff durch.
• Interne Mechanismusdetails verbleiben in der internen Dokumentation des Quellrepositorys und liegen außerhalb des Umfangs dieses Handbuchs.

Publikationsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.

Siehe auch

• Optimizer — die Fähigkeitsseite für Workflow-Hinweise und Codebeispiele.
• Writer — Deep-Referenz — erzeugt das optimierte Ausgabedokument.
• Accelerator — Deep-Referenz — Stapeloptimierung mit Sidecar-Auslagerung nach der Semantik dieses Moduls.