Dönüştürücü

Bir bakışta

NextPDF\Pro\Converter, mevcut bir PDF’i okur ve içeriğini üç metin tabanlı hedeften birine dışa aktarır: konumlandırılmış HTML, basitleştirilmiş SVG veya düz metin. Bu, piksel düzeyinde mükemmel bir PDF işleyici değil, bir içerik çıkarma dışa aktarıcısıdır.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) içinde sunulur ve bir Pro katmanı lisans zarfıyla etkinleşir. Bu yetkiye 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 otomatik yüklenmiş olduğunda çözümlenir.

Kurulum

composer require nextpdf/pro:^3

Kavramsal genel bakış

Converter, bir PDF içerik akışı içindeki metin gösterme operatörlerini — ISO 32000-2:2020 §9.4 uyarınca Tj, TJ ve ' — ayrıştırır ve her sayfanın yaklaşık bir temsilini yeniden oluşturur. Konumlandırmayı Td ve Tm metin operatörlerinden, yazı tipi boyutunu Tf operatöründen okur, ardından noktaları çıktı koordinatlarına eşler.

Her ConversionTarget için bir tane olmak üzere üç dönüştürücü sunulur:

• PdfToHtmlConverter, her sayfayı konumlandırılmış bir kapsayıcıyla sarar ve her metin parçası için mutlak konumlandırılmış <div> öğeleri yayar. Çıktı, kendi içinde tamamlanmış bir HTML5 belgesidir.
• PdfToSvgConverter, sınırlı bir çizim operatörü kümesini (re ile dikdörtgenler, m/l ile çizgiler) artı metni ayrıştırır ve bir sayfa için eşleşen <rect>, <line> ve <text> öğeleri yayar.
• PdfToTextConverter, yalnızca çözülmüş metni sayfa sayfa, bir sayfa sonu işaretçisiyle ayrılmış olarak çıkarır.

Bu, bilinçli olarak sınırlandırılmış bir dışa aktarıcıdır. Metin konumunu yaklaşık olarak hesaplar; yeniden akış yapmaz, rasterleştirmez ve vektör yollarını, gölgelemeyi, kırpmayı, saydamlığı veya gömülü görüntüleri yeniden üretmez. Ters yönde tam aslına uygun HTML’den PDF’e işleme için Core HTML işlem hattını kullanın.

Neden bu şekilde çalışır

Bir PDF, metni anlamsal karakterler olarak değil, konumlandırılmış glif gösterme operatörleri olarak saklar, bu nedenle geri okunacak güvenilir bir belge metni yoktur. Bu nedenle Converter, içerik akışı operatörlerini doğrudan tarar — Tj, TJ, ' artı yerleştirme için Td, Tm ve Tf — ve sayfayı yeniden akıtmak veya rasterleştirmek yerine yaklaşık bir yerleşimi yeniden oluşturur. Bu sınırlı tarama, dışa aktarımı bayt uzunluğunda doğrusal, aynı girdi için belirlenimci ve gömülü mantığı yürütmeden güvenilmeyen baytlar üzerinde güvenli tutan şeydir. Ayrıca dürüst tavanı belirler: glifler Unicode’a ters eşlenmez, bu nedenle özel kodlanmış yazı tipleri ham bayt olarak dışa aktarılır ve tam görsel aslına uygunluk kapsam dışı kalır. Tasarım arka planı: Bir PDF’teki metnin neden gerçekten metin olmadığı.

Davranış sözleşmesi

• Girdi. Ham PDF baytları (string). Boş bir dize, InvalidArgumentException oluşturur.
• Çıktı. Üretilen dizeyi, ConversionTarget değerini, işlenen sayfa sayısını ve bir işleme süresi ölçümünü tutan bir ConversionResult değer nesnesi.
• Kapsam. Metin dışa aktarımı (Tj/TJ/'), birim paketi tarafından test edilen doğrulanmış yoldur. SVG dışa aktarımı yalnızca dikdörtgenleri, düz çizgileri ve metni kapsar. RGB kontur rengi henüz SVG çıktısına aktarılmaz.
• Belirlenimcilik. Aynı girdi ve yapılandırma için üretilen HTML, SVG veya metin bayt akışı kararlıdır. processingTimeMs alanı bir duvar ölçümüdür ve belirlenimci yüzeyin parçası değildir.
• Kodlama. HTML çıktısı htmlspecialchars ile kaçışlanır; SVG çıktısı XML ile kaçışlanır. Yaygın PDF dize kaçış dizileri (\n, \r, \t, \(, \), \\) metin hedefi için çözülür.

Genel API yüzeyi

Tür	Çeşit	Temel üyeler
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

Kod örneği — Hızlı başlangıç

<?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;

Kod örneği — Üretim

<?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;
}

Uç durumlar ve dikkat edilmesi gerekenler

• BT/ET metin blokları olmayan bir PDF, boş veya yalnızca sayfa kabuğu içeren çıktı verir; taranmış (yalnızca görüntü içeren) PDF’ler hiçbir metin üretmez, çünkü hiçbir OCR adımı yoktur.
• PdfToSvgConverter, $pageIndex ile seçilen tek bir sayfayı bir seferde dönüştürür; aralık dışı bir dizin boş bir sayfa akışı verir.
• Konumlandırma yaklaşıktır. Metin dışı dönüşümlerle yerleştirilen metin, döndürülmüş metin veya sütun akışı, özgün görsel yerleşimini yeniden üretmeyebilir.
• Glif-Unicode eşlemesi uygulanmaz; özel kodlamalar kullanan yazı tiplerinden gelen metin, ham bayt dizisi olarak dışa aktarılabilir.

Performans

Ayrıştırma, PDF bayt uzunluğunda doğrusaldır. Bellek, girdiyi artı üretilen çıktı dizesini izler. performance_budget ön bilgisi, tipik bir ofis belgesi için çağrı başına başvurudur.

Güvenlik notları

Dönüştürücü, güvenilmeyen PDF baytlarını metin operatörleri üzerinde sınırlı strpos/substr taramasıyla ayrıştırır; gömülü JavaScript’i yürütmez veya harici başvuruları izlemez. Dışa aktarılan HTML’i güvenilmeyen içerik olarak değerlendirin ve hedefi için uygun biçimde kaçışlayın. Core güvenlik modeline bakın.

Uygunluk

İddia	Standart maddesi	Durum
Tj metin gösterme operatörü ayrıştırıldı	ISO 32000-2:2020 §9.4	Doğrulandı (birim paketi)
TJ dizi metin gösterme operatörü ayrıştırıldı	ISO 32000-2:2020 §9.4	Doğrulandı (birim paketi)
Tam vektör/raster sayfa aslına uygunluğu	—	Desteklenmiyor (kapsam dışı)

Core geri dönüşü / alternatifi

PDF dışa aktarımı için hiçbir Core eşdeğeri yoktur. İleri yön için (HTML’den bir PDF oluşturma), açık kaynaklı Core HTML işlem hattı desteklenen yoldur. Bkz. /modules/core/html/.

Enterprise sınır notu

Converter, Pro katmanı bir metin/şekil dışa aktarıcısıdır. OCR, anlamsal yeniden yapılandırma veya belge anlama gerçekleştirmez. Bunlar ayrı konulardır ve bu modül tarafından sağlanmaz.

Yayın sınırı

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

Ayrıca bkz.

• Converter — Ayrıntılı başvuru
• Extraction
• Diff
• Core HTML işlem hattı