Optimizer — Referensi Mendalam

Sekilas pandang

Halaman ini adalah referensi mendalam untuk permukaan publik NextPDF\Pro\Optimizer. Halaman ini mencakup orchestrator analisis, level optimisasi, kedua scanner, dan value object hasil. Halaman ini menyatakan parameter, nilai default, aritmetika estimasi, dan mode kegagalan. Analisis bersifat hanya-baca: ia mengestimasi penghematan dan tidak menghasilkan dokumen keluaran. Baca halaman kapabilitas Optimizer terlebih dahulu untuk panduan alur kerja.

Ketersediaan & lisensi

Kapabilitas ini hadir dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tier Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Optimizer tidak memiliki bendera lisensi per-fitur. Ini adalah kapabilitas edisi Pro. Level optimisasi adalah parameter runtime, bukan sakelar lisensi.

Permukaan API publik

composer require nextpdf/pro:^3

Metapackage nextpdf/premium memasang kode nextpdf/pro; modul ini berada di bawah namespace NextPDF\Pro\Optimizer.

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
PdfOptimizer::__construct	OptimizationLevel $level = OptimizationLevel::Balanced	Membangun optimizer pada level yang diberikan	PdfOptimizer	Tidak ada yang dideklarasikan	Membangun instans scanner-nya sendiri
PdfOptimizer::analyze	string $pdfData	Analisis hanya-baca pada level yang dikonfigurasi	OptimizationResult	OverflowException pada input di atas 100,000,000 byte; InvalidArgumentException dari scanner pada data PDF yang tidak valid	Hanya mengestimasi; tidak menghasilkan dokumen keluaran
PdfOptimizer::withLevel	OptimizationLevel $level	Mengembalikan optimizer baru pada level yang diminta	self	Tidak ada yang dideklarasikan	Instans penerima tidak berubah
OptimizationLevel	case Lossless, Balanced, Aggressive	Enum berbasis-string untuk level agresivitas	—	—	Nilai backing lossless, balanced, aggressive
OptimizationLevel::label	tidak ada	Label level yang mudah dibaca	string	Tidak ada yang dideklarasikan	Untuk keperluan tampilan
OptimizationLevel::imageQuality	tidak ada	Kualitas gambar target untuk level	int	Tidak ada yang dideklarasikan	100, 75, atau 50
OptimizationLevel::deduplicateStreams	tidak ada	Apakah level mengaktifkan deduplikasi	bool	Tidak ada yang dideklarasikan	false hanya untuk Lossless
OptimizationResult::__construct	int $originalSize, int $optimizedSize, int $objectsRemoved, int $imagesBefore, int $imagesAfter, float $processingTimeMs	Hasil analisis yang immutable	OptimizationResult	Tidak ada yang dideklarasikan	Semua properti bersifat public dan readonly
OptimizationResult::savedBytes	tidak ada	Ukuran asli dikurangi estimasi ukuran teroptimasi	int	Tidak ada yang dideklarasikan	Byte
OptimizationResult::savedPercent	tidak ada	Persentase reduksi ukuran	float	Tidak ada yang dideklarasikan	0.0 ketika ukuran asli adalah nol
OptimizationResult::summary	tidak ada	Laporan multi-baris yang mudah dibaca	string	Tidak ada yang dideklarasikan	Ukuran diformat sebagai B, KB, atau MB
ObjectDeduplicator::findDuplicates	string $pdfData	Mengelompokkan body objek identik berdasarkan hash SHA-256	list<DuplicateGroup>	InvalidArgumentException pada header %PDF yang hilang, input di atas 268,435,456 byte, atau lebih dari 500,000 penanda objek	Hanya mengembalikan grup dengan dua anggota atau lebih
ObjectDeduplicator::estimateSavings	list<DuplicateGroup> $groups	Menjumlahkan jumlah duplikat dikali ukuran objek per grup	int	Tidak ada yang dideklarasikan	Byte
ImageRecompressor::analyzeImages	string $pdfData	Mengekstrak metadata untuk setiap image XObject	list<ImageAnalysis>	InvalidArgumentException pada header %PDF yang hilang	Melewati objek tanpa width dan height eksplisit
ImageRecompressor::suggestCompression	ImageAnalysis $image, OptimizationLevel $level	Merekomendasikan filter dan mengestimasi penghematan	ImageCompressionSuggestion	Tidak ada yang dideklarasikan	Heuristik bergantung-level; lihat kontrak perilaku
DuplicateGroup::__construct	string $contentHash, list<int> $objectNumbers, int $objectSize	Rekaman grup-duplikat yang immutable	DuplicateGroup	Tidak ada yang dideklarasikan	Nomor objek pertama adalah objek kanonis yang dipertahankan
DuplicateGroup::duplicateCount	tidak ada	Ukuran grup dikurangi objek kanonis	int	Tidak ada yang dideklarasikan	Objek yang dapat dihapus melalui penggabungan
ImageAnalysis::__construct	int $objectNumber, int $width, int $height, string $colorSpace, int $bitsPerComponent, string $filter, int $streamSize	Rekaman metadata per-gambar yang immutable	ImageAnalysis	Tidak ada yang dideklarasikan	Field mencerminkan entri dictionary gambar
ImageAnalysis::estimatedDpi	float $displayWidthPt	DPI efektif pada display width yang diberikan	float	Tidak ada yang dideklarasikan	0.0 ketika display width nol atau negatif
ImageAnalysis::isOverResolution	float $displayWidthPt, int $targetDpi = 300	Menandai kandidat downsampling di atas DPI target	bool	Tidak ada yang dideklarasikan	Perbandingan lebih-besar-dari secara ketat
ImageCompressionSuggestion::__construct	int $objectNumber, string $currentFilter, string $suggestedFilter, int $estimatedSavings, string $reason	Rekaman rekomendasi yang immutable	ImageCompressionSuggestion	Tidak ada yang dideklarasikan	reason adalah teks penjelasan yang mudah dibaca

Signature entry-point

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
}

Kontrak perilaku

Orkestrasi

PdfOptimizer::analyze menerima byte PDF mentah dan bersifat hanya-baca. Ia terlebih dahulu membatasi input tak-tepercaya pada 100,000,000 byte; input yang berukuran berlebih memunculkan OverflowException sebelum scan apa pun berjalan. Ia lalu menjalankan analisis deduplikasi ketika level mengizinkannya, selalu menjalankan analisis gambar, dan menggabungkan keduanya menjadi satu OptimizationResult. withLevel mengembalikan optimizer baru; instans tidak pernah dimutasi.

Semantik level

Level	Kualitas gambar target	Deduplikasi	Intent
Lossless	100%	Nonaktif	Tanpa penurunan kualitas; intent keluaran stabil-byte
Balanced	75%	Aktif	Trade-off kualitas moderat; default
Aggressive	50%	Aktif	Reduksi maksimum; downsampling; penurunan kualitas yang terlihat

Lossless melewati deduplikasi sehingga keluaran dapat tetap stabil-byte. Kualitas target memasok aritmetika saran-gambar di bawah ini.

Analisis deduplikasi

Deduplikator memindai definisi objek tak langsung generasi-nol (N 0 obj hingga endobj). Setiap body dipangkas dari whitespace di sekitarnya, di-hash dengan SHA-256, dan dikelompokkan berdasarkan hash. Definisi yang berbeda hanya pada padding karena itu tetap cocok. Hanya grup dengan dua anggota atau lebih yang dikembalikan. Estimasi penghematan per grup sama dengan jumlah duplikat dikali ukuran body tunggal, karena semua objek kecuali objek kanonis dapat dihapus.

Analisis gambar

Sebuah objek diperlakukan sebagai gambar ketika body-nya memuat /Subtype /Image (dengan atau tanpa spasi internal). Width dan height wajib ada; objek yang kehilangan salah satunya dilewati. Color space default-nya DeviceRGB, bits per component 8, dan filter menjadi string kosong ketika tidak ada. Ukuran stream diukur di antara penanda stream dan endstream; ketika tidak ada stream inline yang ditemukan, nilai /Length digunakan sebagai gantinya.

Heuristik saran

• Pada level Lossless, filter saat ini dipertahankan dan estimasi penghematan adalah nol.
• Untuk sumber DCTDecode, saran meng-encode ulang pada kualitas level. Estimasinya adalah ukuran stream dikali (1 − quality/100) dikali 0.5.
• Untuk sumber FlateDecode, saran mengonversi ke DCTDecode. Estimasinya adalah 40% dari ukuran stream pada Balanced dan 60% pada Aggressive.
• Untuk filter lain apa pun, atau tanpa filter, saran mengonversi ke FlateDecode. Estimasinya adalah 20% dari ukuran stream.

Aritmetika hasil

• Objek yang dihapus sama dengan jumlah, di seluruh grup duplikat, dari anggota di luar objek kanonis pertama.
• Total penghematan sama dengan penghematan deduplikasi ditambah estimasi saran per-gambar.
• Estimasi ukuran teroptimasi adalah ukuran asli dikurangi total penghematan, dengan batas bawah nol. Penghematan bersifat non-negatif, sehingga estimasi tidak pernah melampaui ukuran asli.
• Jumlah gambar-sesudah mengurangi, untuk setiap grup duplikat yang memuat gambar teranalisis, jumlah anggota duplikat grup tersebut. Jumlah ini dibatasi bawah pada nol.
• Waktu pemrosesan diukur dengan monotonic clock dan dilaporkan dalam milidetik.

Estimator DPI membagi lebar piksel dengan display width dalam inci (72 poin per inci). Display width nol atau negatif menghasilkan 0.0. Predikat over-resolution membandingkan estimasi terhadap target, 300 DPI secara default.

Kasus tepi & mode kegagalan

• analyze hanya melaporkan potensi. Hasilkan keluaran teroptimasi dengan modul Writer.
• Input kosong, atau input yang tidak diawali header %PDF, gagal dengan InvalidArgumentException.
• Input di atas 100,000,000 byte gagal dengan OverflowException di pintu depan orchestrator, sebelum scan apa pun.
• Deduplikator secara independen menolak input di atas 268,435,456 byte dan lebih dari 500,000 penanda objek. Keduanya menolak secara fail-closed dengan InvalidArgumentException; tidak ada yang dipangkas atau dipindai sebagian.
• Hanya definisi objek generasi-nol yang ikut serta. Objek dengan nomor generasi bukan-nol tidak dipindai.
• Definisi tanpa penanda penutup endobj dilewati.
• Objek gambar tanpa width dan height eksplisit dikecualikan dari laporan gambar.
• Semua angka penghematan adalah heuristik yang diturunkan dari metadata objek, bukan hasil rekompresi yang terukur.
• Level lossless secara sengaja melaporkan reduksi kecil; ia mempertahankan kualitas dan melewati deduplikasi.
• Analisis tidak pernah men-decode, mengeksekusi, atau me-render konten yang disematkan. Ia hanya membaca struktur objek dan metadata.
• Satu-satunya primitif kriptografis yang digunakan adalah SHA-256, untuk pengelompokan konten duplikat. Modul ini tidak mendefinisikan perilaku spesifik FIPS.

Kesesuaian

Kedua scanner beroperasi pada model objek dan gambar PDF dari ISO 32000-2:2020. Deduplikasi menargetkan definisi objek tak langsung; struktur pengidentifikasinya didefinisikan dalam ISO 32000-2:2020, 7.3.10, yang dikutip dalam rekaman sitasi halaman ini. Analisis gambar membaca parameter yang dinyatakan secara eksplisit oleh dictionary gambar — width, height, dan bits per component — sesuai ISO 32000-2:2020, 8.9.4, yang juga dikutip.

Pernyataan-pernyataan ini menjelaskan kapabilitas terhadap klausa yang dikutip. NextPDF tidak memegang sertifikasi kesesuaian, dan dukungan terhadap sebuah klausa bukanlah klaim sertifikasi.

Catatan pengembangan

• Sumber modul membawa @since 1.9.0; referensi ini mendokumentasikan permukaan sebagaimana dirilis dalam nextpdf/pro 3.1.0.
• Semua kelas bersifat final; rekaman hasil dan analisis adalah value object readonly. Bangun instans baru alih-alih memutasi.
• Level default adalah Balanced. Pilih level lain melalui konstruktor atau metode bergaya-with.
• Batas input pintu-depan diberlakukan oleh guard ukuran-input Core yang dibagikan di seluruh permukaan input NextPDF.
• Analisis berbasis-string atas byte yang sudah berada di memori. Modul ini tidak melakukan akses filesystem atau jaringan.
• Detail mekanisme internal tetap berada dalam dokumentasi internal repository sumber dan berada di luar cakupan manual ini.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Optimizer — halaman kapabilitas untuk panduan alur kerja dan contoh kode.
• Writer — Referensi Mendalam — menghasilkan dokumen keluaran teroptimasi.
• Accelerator — Referensi Mendalam — optimisasi batch dengan offload sidecar pada semantik modul ini.