Converter — Derinlemesine başvuru

Bir bakışta

NextPDF\Pro\Converter, mevcut bir PDF’i konumlandırılmış HTML’e, sadeleştirilmiş SVG’ye veya düz metne aktarır ve belge içeriğini türlenmiş yapısal bölgelere ayırır. Bu derinlemesine başvuru; genel API yüzeyini, operatör kapsam matrisini, davranış sözleşmesini ve hata modlarını sıralar. Bu, piksel-mükemmel bir işleyici değil, bir içerik çıkarma aktarıcısıdır.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile birlikte gelir ve bir Pro katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Hiçbir çalışma zamanı yetenek bayrağı bu modülü kapılamaz. Converter sınıfları, Pro paketi yüklü ve lisanslıyken çözümlenir.

Genel API yüzeyi

Simge	Parametreler	Varsayılan davranış	Döndürür	Şununla hata verir veya başarısız olur	Notlar
PdfToHtmlConverter::convert()	string $pdfData, ?ConversionConfig $config = null	Metin taşıyan her sayfayı tek bir bağımsız HTML5 belgesine aktarır	ConversionResult (hedef Html5)	$pdfData boş olduğunda InvalidArgumentException	Null yapılandırma varsayılan olarak ConversionTarget::Html5 olur
PdfToSvgConverter::convert()	string $pdfData, int $pageIndex = 0, ?ConversionConfig $config = null	Tek bir sayfayı bağımsız bir SVG belgesine aktarır	ConversionResult (hedef Svg; pageCount her zaman 1’dir)	$pdfData boş olduğunda InvalidArgumentException	Aralık dışı $pageIndex, yalnızca arka plandan oluşan bir SVG üretir
PdfToTextConverter::convert()	string $pdfData	Tüm sayfalardan çözülmüş metni, bir sayfa sonu işaretçisiyle ayrılmış olarak çıkarır	ConversionResult (hedef PlainText)	$pdfData boş olduğunda InvalidArgumentException	Değişmez dize kaçışlarını yalnızca bu hedef çözer
PdfToTextConverter::extractPage()	string $pdfData, int $pageIndex	Sıfır tabanlı tek bir sayfa için çözülmüş metni çıkarır	string	Oluşturmaz; eksik bir sayfa veya boş giriş için '' döndürür	convert()’in aksine, boş giriş koruması yoktur
DocumentSegmentationEngine::segment()	string $pdfData	Sayfa içeriğini uzamsal ve yazı tipi sezgileriyle türlenmiş yapısal parçalara sınıflandırır	NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation	Giriş boş olduğunda veya PDF yapısı ayrıştırılamadığında InvalidArgumentException	Kural tabanlı; hiçbir AI çıkarımı yapmaz
ConversionConfig::__construct()	ConversionTarget $target, bool $embedFonts = false, bool $embedImages = true, float $scaleFactor = 1.0, string $cssClass = 'pdf-page'	Değiştirilemez dönüştürme ayarları	ConversionConfig	—	embedFonts ve embedImages kabul edilir ancak 3.1.0’da kullanılmaz
ConversionResult::size()	—	Üretilen çıktının bayt uzunluğu	int	—	Genel salt okunur alanlar: output, target, pageCount, processingTimeMs
ConversionResult::isValid()	—	Çıktının boş olup olmadığını bildirir	bool	—	HTML ve SVG belge kabukları hiçbir zaman boş değildir; bunun yerine pageCount’u denetleyin
ConversionTarget	Dize destekli durumlar Html5, Svg, PlainText	Aktarım hedefini seçer	mimeType(): string, fileExtension(): string	—	fileExtension() şuna eşlenir: html, svg, txt

Giriş noktası imzaları:

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

Davranış sözleşmesi

Girişler ham PDF baytlarıdır; çıkışlar bir ConversionResult değer nesnesidir. Üç aktarım dönüştürücüsü aynı tarama modelini paylaşır: stream/endstream sınırlarını bulun, BT/ET metin bloklarını yalıtın ve metin gösteren operatörleri ayrıştırın. Bunlar çapraz başvuru tablosunu ayrıştırmaz ve sıkıştırılmış akışları açmaz. DocumentSegmentationEngine farklıdır: sınıflandırmadan önce trailer’ı, kataloğu ve sayfa ağacını çözümler ve FlateDecode sayfa içeriğini açar.

Operatör kapsamı:

PDF operatörü	HTML	SVG	Metin
Tj (dize göster)	evet	evet	evet
TJ (dizi göster)	evet	evet	evet
' (taşı + göster)	hayır	hayır	evet
Td / Tm (konum)	evet	evet	yok
Tf (yazı tipi boyutu)	evet	evet	yok
re (dikdörtgen)	hayır	evet	hayır
m / l (çizgi)	hayır	evet	hayır
RG (RGB kontur)	hayır	evet (dikdörtgen/çizgi konturuna uygulanır)	hayır
eğriler, gölgeleme, kırpma, görüntüler	hayır	hayır	hayır

• Konumlandırma. Her BT/ET bloğu, ilk Td veya Tm eşleşmesinden tek bir konum çözümler; ikisi de görünürse Tm önceliklidir. Y ekseni, PDF kullanıcı uzayından sol üst çıkış uzayına çevrilir. Tf yoksa yazı tipi boyutu varsayılan olarak 12 pt’dir.
• Sayfa geometrisi. HTML ve SVG, scaleFactor ile çarpılan bir A4 sayfa kutusu (595 x 842 pt) varsayar. SVG kökü, beyaz bir arka plan dikdörtgeni üzerinde eşleşen viewBox, genişlik ve yükseklik özniteliklerini taşır.
• Kontur rengi. RG operatörleri konumsal olarak çözümlenir, dolayısıyla kontur rengini birden çok kez değiştiren bir akış, her dikdörtgeni ve çizgiyi kendisinden önce gelen en son operatöre göre renklendirir. Bileşenler, onaltılık dönüşümden önce 0..1 aralığına sıkıştırılır. Dikdörtgen dolgusu her zaman siyahtır; rg dolgu operatörü değerlendirilmez.
• Dize çözme. Metin hedefi, değişmez dize kaçışlarını ISO 32000-2:2020 §7.3.4.2’ye göre çözer: adlandırılmış kaçışlar, tek bayta maskelenen sekizlik \ddd kodları, ters eğik çizgi satır devamları ve tek başına ters eğik çizgi kaldırma. HTML ve SVG hedefleri, parantez arasındaki ham baytları HTML veya XML kaçışından sonra yayar; kaçışları çözmezler.
• Çıktı birleştirme. Metin hedefi, blok metinlerini bir boşlukla ve sayfaları boş satırlarla çerçevelenmiş --- Page Break --- ile birleştirir. HTML hedefi, yapılandırılmış CSS sınıfını ve bir data-page özniteliğini taşıyan sayfa başına bir kapsayıcının içinde, metin bloğu başına mutlak konumlandırılmış bir <div> yayar.
• Belirlenimcilik. Aynı giriş ve yapılandırma için üretilen HTML, SVG veya metin baytları kararlıdır. processingTimeMs bir duvar saati ölçümüdür ve belirlenimci yüzeyin dışında tutulur.

Uç durumlar ve hata modları

• Boş giriş: her convert() ve segment() giriş noktası InvalidArgumentException oluşturur (“PDF data must not be empty”). Kısmi çıktı üretilmez. extractPage() istisnadır: oluşturmadan '' döndürür.
• BT/ET içermeyen akışlar, HTML ve metin dönüştürücüleri tarafından atlanır. Yalnızca bu tür akışları içeren bir PDF, boş bir metin çıktısıyla veya sayfasız bir HTML kabuğuyla birlikte sıfır pageCount verir.
• isValid() yalnızca boş olmayan çıktıyı denetler. HTML ve SVG dönüştürücüleri her zaman bir belge kabuğu yayar, dolayısıyla hiç metin bulunmasa bile isValid() true kalır; boş çıkarımı algılamak için pageCount’u (HTML, metin) kullanın.
• FlateDecode içeriği, üç aktarım dönüştürücüsü tarafından açılmaz. Yalnızca sıkıştırılmış PDF’ler bunlar aracılığıyla çok az içerik aktarır veya hiç aktarmaz. segment(), FlateDecode sayfa akışlarını açar.
• segment(), açmayı akış başına boyut, sıkıştırma oranı ve birikimli bir bütçeyle sınırlar. Bir üst sınırı aşan bir akış, belleği tüketmek yerine boş sayfa içeriğine indirgenir; oluşturmaz.
• segment(), trailer, çapraz başvuru ofseti, belge kataloğu veya sayfa ağacı çözümlenemediğinde InvalidArgumentException oluşturur.
• Sayfa dizinleme dönüştürücüye göre farklıdır. HTML ve metin dönüştürücüleri yalnızca metin taşıyan akışları sayar; SVG dönüştürücüsü, tanınan herhangi bir grafik veya metin operatörü içeren akışları sayar. Aynı $pageIndex bu nedenle farklı akışlara işaret edebilir.
• TJ sayısal kerning düzeltmeleri atılır; dizi dizeleri glifler arası boşluk olmadan birleştirilir.
• Glif-Unicode eşlemesi uygulanmaz. Özel kodlamalara sahip yazı tiplerinde ayarlanan metin, ham bayt dizisi olarak aktarılır.
• Döndürülmüş metin, metin dışı dönüşümler ve sütun akışı, ilk eşleşme konumlandırmasıyla yaklaşıklanır ve orijinal düzeni yeniden üretmeyebilir.
• Bu modülde hiçbir kriptografik işlem gerçekleşmez, dolayısıyla FIPS modunun modüle özgü bir davranışı yoktur.

Uygunluk

NextPDF, yeteneği belirtilen maddelere karşı belgeler. Destek ifadeleri, uygulanan davranışı açıklar; bunlar uygunluk testi sonuçları veya sertifikalar değildir ve NextPDF hiçbir sertifikaya sahip değildir.

İddia	Spec maddesi	Durum
Tj metin gösteren operatörü ayrıştırıldı	ISO 32000-2:2020 §9.4	Doğrulandı (birim paketi)
TJ dizi metin gösteren operatörü ayrıştırıldı	ISO 32000-2:2020 §9.4	Doğrulandı (birim paketi)
' taşı-ve-göster operatörü ayrıştırıldı (yalnızca metin hedefi)	ISO 32000-2:2020 §9.4	Doğrulandı (birim paketi)
Değişmez dize kaçışları çözüldü (yalnızca metin hedefi)	ISO 32000-2:2020 §7.3.4.2	Uygulandı; baytlar olduğu gibi döndürülür, karakter kümesi yorumu alt akıştadır
re, m, l yol oluşturma tanınır (SVG hedefi)	ISO 32000-2:2020 §8.5.2	Kısmi: eğriler, kapatma veya boyama modu değerlendirmesi olmayan alt küme
Tam metin durumu makinesi ve sayfa işleme	—	Desteklenmiyor (kapsam dışı)

Converter, içeriği geri kazanmak için metin gösteren operatörleri ayrıştırır; tam metin durumu makinesini uygulamaz, dolayısıyla glif konumlandırması standart kesinliğinde değil, yaklaşıktır.

Geliştirme notları

• Ayrıştırma, PDF bayt uzunluğunda doğrusaldır. Bellek, girişi artı üretilen çıktı dizesini izler. performance_budget ön maddesi, tipik bir ofis belgesi için çağrı başına referanstır.
• Dönüştürücüler, güvenilmeyen PDF baytlarını sınırlı strpos/substr taramasıyla ayrıştırır. Hiçbir gömülü JavaScript çalıştırmaz ve hiçbir harici başvuruyu izlemez. Aktarılan HTML’i güvenilmeyen içerik olarak değerlendirin ve hedefine göre kaçışlayın.
• HTML çıktısı htmlspecialchars (ENT_QUOTES, HTML5) ile kaçışlanır; SVG metni XML kaçışlıdır. Yapılandırılmış cssClass, yayımlanmadan önce kaçışlanır.
• Yapılandırma kullanımı: scaleFactor HTML ve SVG hedefleri için geçerlidir; cssClass yalnızca HTML için geçerlidir; embedFonts ve embedImages ayrılmıştır ve şu anda kullanılmaz; target alanı, bir dönüştürücünün kendi çıktı biçimini geçersiz kılmaz.
• Aktarım dönüştürücüleri 1.9.0’dan beri gelir; DocumentSegmentationEngine 2.1.0’dan beri gelir ve Pro MCP segment_document aracını ve Interop segmentasyon sözleşmesini destekler.
• Aynı ad alanındaki PdfPageExtractor ve PdfPageData, segmentasyon motoruna içseldir ve genel API değildir.

Yayımlama sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve talep ön ekleri kapsam dışıdır.

Ayrıca bkz.

• Converter yetenek genel bakışı
• Extraction
• Diff
• Interop
• Core HTML iş hattı