Converter

ภาพรวมโดยสังเขป

NextPDF\Pro\Converter อ่าน PDF ที่มีอยู่เดิมและส่งออกเนื้อหาไปยังเป้าหมายที่อิงข้อความหนึ่งในสามแบบ ได้แก่ HTML ที่จัดตำแหน่งแล้ว SVG แบบลดทอน หรือข้อความล้วน โดยเป็นตัวส่งออกการสกัดเนื้อหา ไม่ใช่ตัวเรนเดอร์ PDF ที่เที่ยงตรงระดับพิกเซล

ความพร้อมใช้งานและการให้สิทธิ์ใช้งาน

ความสามารถนี้มาพร้อมกับ NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วยซองใบอนุญาตระดับ Pro การนำไปใช้งานที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและขอใบอนุญาต

ไม่มีแฟล็กความสามารถรันไทม์ที่ควบคุมโมดูลนี้ คลาส Converter จะถูกรีโซลฟ์เมื่อใดก็ตามที่แพ็กเกจ Pro ถูกติดตั้งและออโตโหลดแล้ว

การติดตั้ง

composer require nextpdf/pro:^3

ภาพรวมเชิงแนวคิด

Converter แจงตัวดำเนินการแสดงข้อความภายในสตรีมเนื้อหา PDF ได้แก่ Tj, TJ และ ' ตาม ISO 32000-2:2020 §9.4 และสร้างการนำเสนอโดยประมาณของแต่ละหน้าขึ้นใหม่ โดยอ่านการจัดตำแหน่งจากตัวดำเนินการข้อความ Td และ Tm และขนาดฟอนต์จาก Tf แล้วแมปจุดให้เป็นพิกัดเอาต์พุต

มีตัวแปลงให้ใช้สามตัว หนึ่งตัวต่อ ConversionTarget:

• PdfToHtmlConverter ห่อหุ้มแต่ละหน้าในคอนเทนเนอร์ที่จัดตำแหน่งแล้วและปล่อยองค์ประกอบ <div> ที่จัดตำแหน่งสัมบูรณ์สำหรับแต่ละชุดข้อความที่แสดง เอาต์พุตเป็นเอกสาร HTML5 ที่สมบูรณ์ในตัวเอง
• PdfToSvgConverter แจงชุดตัวดำเนินการการวาดที่จำกัด (สี่เหลี่ยมผ่าน re เส้นผ่าน m/l) บวกข้อความ และปล่อยองค์ประกอบ <rect>, <line> และ <text> ที่ตรงกันสำหรับหนึ่งหน้า
• PdfToTextConverter สกัดเฉพาะข้อความที่ถอดรหัสแล้ว หน้าต่อหน้า โดยคั่นด้วยตัวทำเครื่องหมายแบ่งหน้า

นี่คือตัวส่งออกที่มีขอบเขตโดยเจตนา โดยประมาณตำแหน่งข้อความ ไม่ทำการไหลซ้ำ ไม่แรสเตอร์ และไม่สร้างเส้นทางเวกเตอร์ การแรเงา การตัดเนื้อหา ความโปร่งใส หรือภาพที่ฝังอยู่ขึ้นใหม่ สำหรับการเรนเดอร์ HTML เป็น PDF แบบเที่ยงตรงเต็มรูปแบบในทิศทางตรงข้าม ให้ใช้ไปป์ไลน์ HTML ของ Core

ทำไมจึงทำงานเช่นนี้

PDF จัดเก็บข้อความเป็นตัวดำเนินการแสดงกลิฟที่จัดตำแหน่งแล้ว ไม่ใช่อักขระเชิงความหมาย จึงไม่มีข้อความเอกสารที่เชื่อถือได้ให้อ่านกลับ Converter จึงสแกนตัวดำเนินการของสตรีมเนื้อหาโดยตรง ได้แก่ Tj, TJ, ' บวกกับ Td, Tm และ Tf สำหรับการวางตำแหน่ง และสร้างเค้าโครงโดยประมาณขึ้นใหม่แทนการไหลซ้ำหรือแรสเตอร์หน้า การสแกนที่มีขอบเขตนี้เองที่ทำให้การส่งออกเป็นเชิงเส้นตามความยาวไบต์ กำหนดได้แน่นอนสำหรับอินพุตเดียวกัน และปลอดภัยกับไบต์ที่ไม่น่าเชื่อถือโดยไม่รันตรรกะที่ฝังอยู่ อีกทั้งยังกำหนดเพดานตามความเป็นจริงว่า กลิฟจะไม่ถูกแมปย้อนกลับไปเป็นยูนิโคด ฟอนต์ที่เข้ารหัสแบบกำหนดเองจึงถูกส่งออกเป็นไบต์ดิบ และความเที่ยงตรงทางภาพที่แม่นยำยังคงอยู่นอกขอบเขต เบื้องหลังการออกแบบ: ทำไมข้อความใน PDF จึงไม่ใช่ข้อความจริงๆ

สัญญาพฤติกรรม

• อินพุต ไบต์ PDF ดิบ (string) สตริงว่างจะทำให้เกิด InvalidArgumentException
• เอาต์พุต ออบเจ็กต์ค่า ConversionResult ที่บรรจุสตริงที่ผลิตได้ ConversionTarget จำนวนหน้าที่ประมวลผล และการวัดเวลาประมวลผล
• ความครอบคลุม การส่งออกข้อความ (Tj/TJ/') คือเส้นทางที่ตรวจสอบแล้วและทดสอบโดยชุดทดสอบยูนิต การส่งออก SVG ครอบคลุมเฉพาะสี่เหลี่ยม เส้นตรง และข้อความ สี stroke แบบ RGB ยังไม่ถูกส่งต่อไปยังเอาต์พุต SVG
• ความแน่นอน สำหรับอินพุตและการกำหนดค่าเดียวกัน สตรีมไบต์ HTML, SVG หรือข้อความที่ผลิตได้จะเสถียร ฟิลด์ processingTimeMs เป็นการวัดเวลาตามนาฬิกาจริงและไม่ได้เป็นส่วนหนึ่งของพื้นผิวที่กำหนดได้แน่นอน
• การเข้ารหัส เอาต์พุต HTML ถูกหลีกด้วย htmlspecialchars เอาต์พุต SVG ถูกหลีกแบบ XML ลำดับหลีกสตริง PDF ทั่วไป (\n, \r, \t, \(, \), \\) ถูกถอดรหัสสำหรับเป้าหมายข้อความ

พื้นผิว API สาธารณะ

Type	Kind	Key members
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

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

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

ตัวอย่างโค้ด — สำหรับใช้งานจริง

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

ข้อควรระวังและกรณีขอบ

• PDF ที่ไม่มีบล็อกข้อความ BT/ET จะให้เอาต์พุตที่ว่างเปล่าหรือมีเพียงโครงหน้า PDF ที่เป็นภาพล้วน (สแกน) จะไม่ให้ข้อความเพราะไม่มีขั้นตอน OCR
• PdfToSvgConverter แปลงทีละหน้าเดียว ซึ่งเลือกด้วย $pageIndex ดัชนีที่อยู่นอกช่วงจะให้สตรีมหน้าว่าง
• การจัดตำแหน่งเป็นแบบประมาณ ข้อความที่วางด้วยการแปลงที่ไม่ใช่ข้อความ ข้อความที่หมุน หรือการไหลแบบคอลัมน์ อาจไม่สร้างเค้าโครงภาพดั้งเดิมขึ้นใหม่
• ไม่มีการใช้การแมปกลิฟเป็นยูนิโคด ข้อความจากฟอนต์ที่ใช้การเข้ารหัสแบบกำหนดเองอาจถูกส่งออกเป็นลำดับไบต์ดิบ

ประสิทธิภาพ

การแจงเป็นเชิงเส้นตามความยาวไบต์ของ PDF หน่วยความจำติดตามอินพุตบวกกับสตริงเอาต์พุตที่ผลิตได้ frontmatter performance_budget คือค่าอ้างอิงต่อการเรียกหนึ่งครั้งสำหรับเอกสารสำนักงานทั่วไป

บันทึกด้านความปลอดภัย

ตัวแปลงแจงไบต์ PDF ที่ไม่น่าเชื่อถือด้วยการสแกนแบบ strpos/substr ที่มีขอบเขตเหนือตัวดำเนินการข้อความ โดยไม่รัน JavaScript ที่ฝังอยู่หรือติดตามการอ้างอิงภายนอก จงปฏิบัติต่อ HTML ที่ส่งออกว่าเป็นเนื้อหาที่ไม่น่าเชื่อถือและหลีกอย่างเหมาะสมสำหรับปลายทางของมัน ดูแบบจำลองความปลอดภัยของ Core

ความสอดคล้องกับมาตรฐาน

Claim	Spec clause	Status
Tj text-showing operator parsed	ISO 32000-2:2020 §9.4	Verified (unit suite)
TJ array text-showing operator parsed	ISO 32000-2:2020 §9.4	Verified (unit suite)
Full vector/raster page fidelity	—	Not supported (out of scope)

ทางเลือก / ทางสำรองของ Core

ไม่มีสิ่งเทียบเท่าใน Core สำหรับการส่งออก PDF สำหรับทิศทางไปข้างหน้า (การสร้าง PDF จาก HTML) ไปป์ไลน์ HTML ของ Core แบบโอเพนซอร์สคือเส้นทางที่รองรับ ดู /modules/core/html/

บันทึกขอบเขตของ Enterprise

Converter เป็นตัวส่งออกข้อความ/รูปทรงระดับ Pro โดยไม่ทำ OCR การสร้างใหม่เชิงความหมาย หรือการเข้าใจเอกสาร สิ่งเหล่านั้นเป็นเรื่องที่แยกต่างหากและไม่ได้จัดให้โดยโมดูลนี้

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทางเนมสเปซภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้าหมายเลขทิกเก็ต อยู่นอกขอบเขต

ดูเพิ่มเติม

• Converter — การอ้างอิงเชิงลึก
• Extraction
• Diff
• Core HTML pipeline