Converter — Referensi Mendalam

Sekilas

NextPDF\Pro\Converter mengekspor PDF yang sudah ada ke HTML terposisi, SVG yang disederhanakan, atau teks biasa, dan menyegmentasikan konten dokumen menjadi region struktural bertipe. Referensi mendalam ini menguraikan permukaan API publik, matriks cakupan operator, kontrak perilaku, dan mode kegagalan. Ini adalah eksportir ekstraksi konten, bukan renderer pixel-perfect.

Ketersediaan & lisensi

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

Tidak ada flag kapabilitas runtime yang men-gate modul ini. Kelas converter di-resolve setiap kali paket Pro terpasang dan berlisensi.

Permukaan API publik

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
PdfToHtmlConverter::convert()	string $pdfData, ?ConversionConfig $config = null	Mengekspor setiap halaman yang memuat teks ke satu dokumen HTML5 mandiri	ConversionResult (target Html5)	InvalidArgumentException ketika $pdfData kosong	Config null default ke ConversionTarget::Html5
PdfToSvgConverter::convert()	string $pdfData, int $pageIndex = 0, ?ConversionConfig $config = null	Mengekspor satu halaman ke dokumen SVG standalone	ConversionResult (target Svg; pageCount selalu 1)	InvalidArgumentException ketika $pdfData kosong	$pageIndex di luar rentang menghasilkan SVG hanya-latar
PdfToTextConverter::convert()	string $pdfData	Mengekstrak teks terdekode dari semua halaman, dipisahkan oleh penanda jeda halaman	ConversionResult (target PlainText)	InvalidArgumentException ketika $pdfData kosong	Hanya target ini yang mendekode escape literal-string
PdfToTextConverter::extractPage()	string $pdfData, int $pageIndex	Mengekstrak teks terdekode untuk satu halaman berbasis-nol	string	Tidak melempar; mengembalikan '' untuk halaman yang tidak ada atau input kosong	Berbeda dari convert(), tidak ada penjaga input-kosong
DocumentSegmentationEngine::segment()	string $pdfData	Mengklasifikasikan konten halaman ke dalam segmen struktural bertipe menggunakan heuristik spasial dan font	NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation	InvalidArgumentException ketika input kosong atau struktur PDF tidak dapat di-parse	Berbasis aturan; tidak melakukan inferensi AI
ConversionConfig::__construct()	ConversionTarget $target, bool $embedFonts = false, bool $embedImages = true, float $scaleFactor = 1.0, string $cssClass = 'pdf-page'	Pengaturan konversi immutable	ConversionConfig	—	embedFonts dan embedImages diterima tetapi tidak dikonsumsi di 3.1.0
ConversionResult::size()	—	Panjang byte dari output yang dihasilkan	int	—	Field readonly publik: output, target, pageCount, processingTimeMs
ConversionResult::isValid()	—	Melaporkan apakah output tidak kosong	bool	—	Shell dokumen HTML dan SVG tidak pernah kosong; periksa pageCount sebagai gantinya
ConversionTarget	Case ber-backing string Html5, Svg, PlainText	Memilih target ekspor	mimeType(): string, fileExtension(): string	—	fileExtension() memetakan ke html, svg, txt

Tanda tangan titik masuk:

public function convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult

public function convert(
    string $pdfData,
    int $pageIndex = 0,
    ?ConversionConfig $config = null,
): ConversionResult

public function convert(string $pdfData): ConversionResult
public function extractPage(string $pdfData, int $pageIndex): string

public function segment(string $pdfData): DocumentSegmentation

Kontrak perilaku

Input berupa byte PDF mentah; output berupa value object ConversionResult. Ketiga converter ekspor berbagi model pemindaian yang sama: menemukan batas stream/endstream, mengisolasi blok teks BT/ET, dan mem-parse operator text-showing. Mereka tidak mem-parse cross-reference table dan tidak menginflasi stream terkompresi. DocumentSegmentationEngine berbeda: ia me-resolve trailer, catalog, dan page tree, serta menginflasi konten halaman FlateDecode sebelum klasifikasi.

Cakupan operator:

Operator PDF	HTML	SVG	Text
Tj (show string)	ya	ya	ya
TJ (show array)	ya	ya	ya
' (move + show)	tidak	tidak	ya
Td / Tm (position)	ya	ya	n/a
Tf (font size)	ya	ya	n/a
re (rectangle)	tidak	ya	tidak
m / l (line)	tidak	ya	tidak
RG (RGB stroke)	tidak	ya (diterapkan pada stroke rect/line)	tidak
curves, shading, clipping, images	tidak	tidak	tidak

• Pemosisian. Setiap blok BT/ET me-resolve satu posisi dari kecocokan Td atau Tm pertamanya; Tm didahulukan ketika keduanya muncul. Sumbu Y dibalik dari ruang pengguna PDF ke ruang output kiri-atas. Ukuran font default ke 12 pt ketika tidak ada Tf.
• Geometri halaman. HTML dan SVG mengasumsikan kotak halaman A4 (595 x 842 pt) dikalikan scaleFactor. Root SVG membawa atribut viewBox, width, dan height yang cocok di atas persegi panjang latar putih.
• Warna stroke. Operator RG di-resolve secara posisional, sehingga stream yang mengubah warna stroke lebih dari sekali mewarnai setiap persegi panjang dan garis dengan operator pendahulu terbaru. Komponen di-clamp ke rentang 0..1 sebelum konversi hex. Isian persegi panjang selalu hitam; operator isian rg tidak dievaluasi.
• Pendekodean string. Target text mendekode escape literal-string sesuai ISO 32000-2:2020 §7.3.4.2: named escape, kode oktal \ddd yang di-mask ke satu byte, kelanjutan baris backslash, dan penghapusan lone-backslash. Target HTML dan SVG memancarkan byte mentah di antara tanda kurung setelah escaping HTML atau XML; mereka tidak mendekode escape.
• Perakitan output. Target text menggabungkan teks blok dengan spasi, dan halaman dengan --- Page Break --- yang dibingkai oleh baris kosong. Target HTML memancarkan satu <div> terposisi absolut per blok teks di dalam kontainer per-halaman yang membawa kelas CSS terkonfigurasi dan atribut data-page.
• Determinisme. Untuk input dan konfigurasi identik, byte HTML, SVG, atau teks yang dihasilkan stabil. processingTimeMs adalah pengukuran wall-clock dan dikecualikan dari permukaan deterministik.

Kasus tepi & mode kegagalan

• Input kosong: setiap titik masuk convert() dan segment() memunculkan InvalidArgumentException (“PDF data must not be empty”). Tidak ada output parsial yang dihasilkan. extractPage() adalah pengecualian: ia mengembalikan '' tanpa melempar.
• Stream tanpa BT/ET dilewati oleh converter HTML dan text. PDF yang hanya berisi stream semacam itu menghasilkan pageCount nol dengan output teks kosong atau shell HTML tanpa halaman.
• isValid() hanya memeriksa output yang tidak kosong. Converter HTML dan SVG selalu memancarkan shell dokumen, sehingga isValid() tetap true bahkan ketika tidak ada teks yang ditemukan; gunakan pageCount (HTML, text) untuk mendeteksi ekstraksi kosong.
• Konten FlateDecode tidak diinflasi oleh ketiga converter ekspor. PDF yang hanya-terkompresi mengekspor sedikit atau tanpa konten melaluinya. segment() memang menginflasi stream halaman FlateDecode.
• segment() membatasi dekompresi berdasarkan ukuran per-stream, rasio kompresi, dan anggaran kumulatif. Stream yang melanggar batas menurun ke konten halaman kosong alih-alih menguras memori; ia tidak melempar.
• segment() memunculkan InvalidArgumentException ketika trailer, offset cross-reference, catalog dokumen, atau page tree tidak dapat di-resolve.
• Pengindeksan halaman berbeda per converter. Converter HTML dan text hanya menghitung stream yang memuat teks; converter SVG menghitung stream yang memuat operator grafis atau teks yang dikenali. Karena itu $pageIndex yang sama dapat mengalamati stream yang berbeda.
• Penyesuaian kerning numerik TJ dibuang; string array digabungkan tanpa spasi antar-glyph.
• Pemetaan glyph-ke-Unicode tidak diterapkan. Teks yang diatur dalam font dengan encoding kustom diekspor sebagai urutan byte mentah.
• Teks yang dirotasi, transform non-teks, dan alur kolom didekati oleh pemosisian kecocokan-pertama dan mungkin tidak mereproduksi layout aslinya.
• Tidak ada operasi kriptografis yang terjadi di modul ini, sehingga mode FIPS tidak memiliki perilaku khusus-modul.

Konformansi

NextPDF mendokumentasikan kapabilitas terhadap klausul yang dikutip. Pernyataan dukungan menjelaskan perilaku yang diimplementasikan; keduanya bukan hasil pengujian konformansi dan bukan sertifikasi, dan NextPDF tidak memegang sertifikasi.

Klaim	Klausul spesifikasi	Status
Operator text-showing Tj di-parse	ISO 32000-2:2020 §9.4	Verified (unit suite)
Operator text-showing array TJ di-parse	ISO 32000-2:2020 §9.4	Verified (unit suite)
Operator move-and-show ' di-parse (hanya target text)	ISO 32000-2:2020 §9.4	Verified (unit suite)
Escape literal-string didekode (hanya target text)	ISO 32000-2:2020 §7.3.4.2	Implemented; byte dikembalikan apa adanya, interpretasi charset di hilir
Konstruksi path re, m, l dikenali (target SVG)	ISO 32000-2:2020 §8.5.2	Partial: subset tanpa evaluasi kurva, penutupan, atau painting-mode
Mesin text-state penuh dan rendering halaman	—	Not supported (out of scope)

Converter mem-parse operator text-showing untuk memulihkan konten; ia tidak mengimplementasikan mesin text-state penuh, sehingga pemosisian glyph bersifat aproksimatif alih-alih presisi-spesifikasi.

Catatan pengembangan

• Parsing bersifat linear terhadap panjang byte PDF. Memori mengikuti input ditambah string output yang dihasilkan. Front matter performance_budget adalah referensi per-invokasi untuk dokumen kantor tipikal.
• Converter mem-parse byte PDF tak-tepercaya dengan pemindaian strpos/substr yang terbatas. Mereka tidak mengeksekusi JavaScript tersemat dan tidak mengikuti referensi eksternal. Perlakukan HTML yang diekspor sebagai konten tak-tepercaya dan escape untuk tujuannya.
• Output HTML di-escape dengan htmlspecialchars (ENT_QUOTES, HTML5); teks SVG di-XML-escape. cssClass terkonfigurasi di-escape sebelum dipancarkan.
• Konsumsi config: scaleFactor berlaku untuk target HTML dan SVG; cssClass hanya berlaku untuk HTML; embedFonts dan embedImages dicadangkan dan saat ini tidak digunakan; field target tidak menggantikan format output converter itu sendiri.
• Converter ekspor dikirimkan sejak 1.9.0; DocumentSegmentationEngine dikirimkan sejak 2.1.0 dan mendukung tool segment_document Pro MCP serta kontrak segmentasi Interop.
• PdfPageExtractor dan PdfPageData dalam namespace yang sama bersifat internal bagi mesin segmentasi dan bukan API publik.

Batas publikasi

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

Lihat juga

• Ikhtisar kapabilitas Converter
• Extraction
• Diff
• Interop
• Pipeline HTML Core