Pengonversi

Sekilas pandang

NextPDF\Pro\Converter membaca PDF yang ada dan mengekspor kontennya ke salah satu dari tiga target berbasis teks: HTML berposisi, SVG yang disederhanakan, atau teks biasa. Ini adalah pengekspor ekstraksi-konten, bukan perender PDF yang piksel-sempurna.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tingkat Pro. Deployment tanpa hak akses tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag kapabilitas runtime yang menggerbangi modul ini. Kelas-kelas Converter teratasi setiap kali paket Pro terpasang dan ter-autoload.

Pemasangan

composer require nextpdf/pro:^3

Tinjauan konseptual

Converter mengurai operator pemunculan-teks di dalam content stream PDF — Tj, TJ, dan ' sesuai ISO 32000-2:2020 §9.4 — dan membangun ulang representasi perkiraan dari setiap halaman. Ia membaca pemosisian dari operator teks Td dan Tm dan ukuran fon dari Tf, lalu memetakan poin ke koordinat keluaran.

Tiga konverter diekspos, satu per ConversionTarget:

• PdfToHtmlConverter membungkus setiap halaman dalam kontainer berposisi dan memancarkan elemen <div> yang diposisikan secara absolut untuk setiap text run. Keluaran adalah dokumen HTML5 yang mandiri.
• PdfToSvgConverter mengurai serangkaian terbatas operator gambar (persegi panjang via re, garis via m/l) ditambah teks, dan memancarkan elemen <rect>, <line>, dan <text> yang sesuai untuk satu halaman.
• PdfToTextConverter mengekstrak hanya teks yang sudah didekode, halaman demi halaman, dipisahkan oleh penanda page-break.

Ini adalah pengekspor yang sengaja dibatasi. Ia memperkirakan posisi teks; ia tidak melakukan reflow, ia tidak melakukan rasterisasi, dan ia tidak mereproduksi jalur vektor, shading, kliping, transparansi, atau gambar tertanam. Untuk perenderan HTML-ke-PDF berfidelitas penuh dalam arah sebaliknya, gunakan pipeline HTML Core.

Mengapa cara kerjanya begini

Sebuah PDF menyimpan teks sebagai operator pemunculan-glyph yang berposisi, bukan karakter semantik, sehingga tidak ada teks dokumen yang andal untuk dibaca kembali. Karena itu Converter memindai operator content-stream secara langsung — Tj, TJ, ', ditambah Td, Tm, dan Tf untuk penempatan — dan membangun ulang tata letak perkiraan alih-alih melakukan reflow atau rasterisasi halaman. Pemindaian terbatas itulah yang menjaga ekspor tetap linear terhadap panjang byte, deterministik untuk input identik, dan aman pada byte tak tepercaya tanpa mengeksekusi logika tertanam. Ini juga menetapkan batas atas yang jujur: glyph tidak dipetakan-balik ke Unicode, sehingga fon berpengodean kustom diekspor sebagai byte mentah dan fidelitas visual yang persis tetap di luar cakupan. Latar desain: Mengapa teks di dalam PDF sebenarnya bukan teks.

Kontrak perilaku

• Input. Byte PDF mentah (string). String kosong memunculkan InvalidArgumentException.
• Output. Objek nilai ConversionResult yang menyimpan string yang dihasilkan, ConversionTarget, jumlah halaman yang diproses, dan pengukuran waktu pemrosesan.
• Cakupan. Ekspor teks (Tj/TJ/') adalah jalur terverifikasi, dilatih oleh unit suite. Ekspor SVG hanya mencakup persegi panjang, garis lurus, dan teks saja. Warna stroke RGB belum dipropagasikan ke keluaran SVG.
• Determinisme. Untuk input dan konfigurasi yang identik, byte stream HTML, SVG, atau teks yang dihasilkan bersifat stabil. Bidang processingTimeMs adalah pengukuran wall dan bukan bagian dari permukaan deterministik.
• Pengodean. Keluaran HTML di-escape dengan htmlspecialchars; keluaran SVG di-escape XML. Sekuens escape string PDF yang umum (\n, \r, \t, \(, \), \\) didekode untuk target teks.

Permukaan API publik

Tipe	Jenis	Anggota utama
NextPDF\Pro\Converter\PdfToHtmlConverter	final class	convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult
NextPDF\Pro\Converter\PdfToSvgConverter	final class	convert(string $pdfData, int $pageIndex = 0, ?ConversionConfig $config = null): ConversionResult
NextPDF\Pro\Converter\PdfToTextConverter	final class	convert(string $pdfData): ConversionResult, extractPage(string $pdfData, int $pageIndex): string
NextPDF\Pro\Converter\ConversionConfig	final readonly class	__construct(ConversionTarget $target, bool $embedFonts = false, bool $embedImages = true, float $scaleFactor = 1.0, string $cssClass = 'pdf-page')
NextPDF\Pro\Converter\ConversionResult	final readonly class	string $output, ConversionTarget $target, int $pageCount, float $processingTimeMs, size(): int, isValid(): bool
NextPDF\Pro\Converter\ConversionTarget	enum	Html5, Svg, PlainText; mimeType(): string, fileExtension(): string

Contoh kode — Mulai cepat

<?php

declare(strict_types=1);

use NextPDF\Pro\Converter\PdfToTextConverter;

$pdf    = file_get_contents('report.pdf');
$result = (new PdfToTextConverter())->convert($pdf);

echo $result->pageCount, " pages, ", $result->size(), " bytes of text\n";
echo $result->output;

Contoh kode — Produksi

<?php

declare(strict_types=1);

use NextPDF\Pro\Converter\ConversionConfig;
use NextPDF\Pro\Converter\ConversionTarget;
use NextPDF\Pro\Converter\PdfToHtmlConverter;

function exportPreview(string $pdfBytes): string
{
    if ($pdfBytes === '') {
        throw new InvalidArgumentException('empty PDF payload');
    }

    $config = new ConversionConfig(
        target: ConversionTarget::Html5,
        scaleFactor: 1.0,
        cssClass: 'doc-preview',
    );

    $result = (new PdfToHtmlConverter())->convert($pdfBytes, $config);

    if (! $result->isValid()) {
        throw new RuntimeException('converter produced no output');
    }

    return $result->output;
}

Kasus tepi & jebakan

• PDF tanpa blok teks BT/ET menghasilkan keluaran kosong atau hanya berupa kerangka halaman; PDF yang dipindai (hanya berupa gambar) tidak menghasilkan teks karena tidak ada langkah OCR.
• PdfToSvgConverter mengonversi satu halaman setiap kali, dipilih oleh $pageIndex; indeks di luar rentang menghasilkan page stream kosong.
• Pemosisian bersifat perkiraan. Teks yang ditempatkan dengan transformasi non-teks, teks terotasi, atau aliran kolom mungkin tidak mereproduksi tata letak visual aslinya.
• Pemetaan glyph-ke-Unicode tidak diterapkan; teks dari fon yang menggunakan pengodean kustom mungkin diekspor sebagai sekuens byte mentah.

Performa

Penguraian bersifat linear terhadap panjang byte PDF. Memori mengikuti input ditambah string keluaran yang dihasilkan. Front-matter performance_budget adalah referensi per-pemanggilan untuk dokumen perkantoran tipikal.

Catatan keamanan

Converter mengurai byte PDF yang tidak tepercaya dengan pemindaian strpos/substr yang terbatas atas operator teks; ia tidak mengeksekusi JavaScript tertanam atau mengikuti referensi eksternal. Perlakukan HTML yang diekspor sebagai konten tidak tepercaya dan escape secara semestinya untuk tujuannya. Lihat model keamanan Core.

Konformansi

Klaim	Klausa spec	Status
operator pemunculan-teks Tj diurai	ISO 32000-2:2020 §9.4	Terverifikasi (unit suite)
operator pemunculan-teks array TJ diurai	ISO 32000-2:2020 §9.4	Terverifikasi (unit suite)
Fidelitas halaman vektor/raster penuh	—	Tidak didukung (di luar cakupan)

Fallback / alternatif Core

Tidak ada padanan Core untuk ekspor PDF. Untuk arah maju (menulis PDF dari HTML), pipeline HTML Core sumber terbuka adalah jalur yang didukung. Lihat /modules/core/html/.

Catatan batas Enterprise

Converter adalah pengekspor teks/bentuk tingkat Pro. Ia tidak melakukan OCR, rekonstruksi semantik, atau pemahaman dokumen. Itu adalah urusan terpisah dan tidak disediakan oleh modul ini.

Batas publikasi

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

Lihat juga

• Converter — Referensi Mendalam
• Extraction
• Diff
• Core HTML pipeline