Converter

速覽

NextPDF\Pro\Converter 會讀取一份既有的 PDF，並將其內容匯出為三種文字型目標之一：定位後的 HTML、簡化的 SVG，或純文字。它是一個內容抽取匯出器， 而非像素級精確的 PDF 繪製器。

可用性與授權

此能力隨 NextPDF Pro（nextpdf/pro）出貨，並以 Pro 等級授權封套啟用。 不具該權益的部署不會載入此能力的類別。比較各版本並取得授權。

沒有任何執行階段能力旗標閘控此模組。只要 Pro 套件已安裝並完成自動載入， Converter 類別即可解析取用。

安裝

composer require nextpdf/pro:^3

概念總覽

Converter 會剖析 PDF 內容流內的文字顯示運算子 —— 依 ISO 32000-2:2020 §9.4 的 Tj、TJ 與 ' —— 並重建每一頁的近似呈現。它會從 Td 與 Tm 文字運算子讀取定位、從 Tf 讀取字級，接著將點（point）對應到輸出座標。

對外開放三個轉換器，各對應一種 ConversionTarget：

• PdfToHtmlConverter 會將每一頁包裝在一個定位後的容器中，並為每段文字流發出絕對定位的 <div> 元素。輸出是一份自包含的 HTML5 文件。
• PdfToSvgConverter 會剖析一組有限的繪圖運算子（透過 re 的矩形、 透過 m/l 的線條）再加上文字，並為單一頁面發出對應的 <rect>、<line> 與 <text> 元素。
• PdfToTextConverter 只逐頁抽取解碼後的文字，並以分頁標記分隔。

這是一個刻意限定範圍的匯出器。它近似文字位置；它不重新排版、不點陣化， 也不重現向量路徑、陰影、裁切、透明度或嵌入影像。若需要反方向的完整保真度 HTML 轉 PDF 繪製，請使用 Core HTML 管線。

為何如此設計

PDF 將文字儲存為定位後的字形顯示運算子，而非語意字元，因此並沒有可靠的文件文字可供讀回。Converter 因此直接掃描內容流運算子 —— Tj、TJ、'， 加上作為放置用途的 Td、Tm 與 Tf —— 並重建近似版面，而非重新排版或點陣化頁面。正是這種有界限的掃描，讓匯出在位元組長度上維持線性、對相同輸入維持決定性，並在不執行嵌入邏輯的前提下安全處理不受信任的位元組。它也劃出了誠實的上限：字形不會反向對應回 Unicode，因此使用自訂編碼的字型會以原始位元組匯出，且精確的視覺保真度不在範圍內。 設計背景：為何 PDF 中的文字其實不是文字。

行為合約

• 輸入。 原始 PDF 位元組（string）。空字串會引發 InvalidArgumentException。
• 輸出。 一個 ConversionResult 值物件，承載產生的字串、 ConversionTarget、已處理的頁數，以及一個處理時間量測。
• 涵蓋範圍。 文字匯出（Tj/TJ/'）是已驗證路徑，由單元測試套件演練。SVG 匯出僅涵蓋矩形、直線與文字。RGB 描邊顏色尚未傳播到 SVG 輸出。
• 決定性。 對於相同的輸入與設定，產生的 HTML、SVG 或文字位元組流是穩定的。processingTimeMs 欄位是一個牆鐘量測，不屬於決定性介面的一部分。
• 編碼。 HTML 輸出經 htmlspecialchars 轉義；SVG 輸出經 XML 轉義。 常見的 PDF 字串轉義序列（\n、\r、\t、\(、 \)、\\）會在文字目標中解碼。

公開 API 介面

型別	種類	主要成員
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;
}

邊界案例與陷阱

• 一份沒有 BT/ET 文字區塊的 PDF 會產生空白或只有頁面外殼的輸出； 掃描的（僅含影像）PDF 不會產生任何文字，因為沒有 OCR 步驟。
• PdfToSvgConverter 一次轉換單一頁面，由 $pageIndex 選定； 超出範圍的索引會產生空的頁面流。
• 定位是近似的。以非文字變換放置的文字、旋轉文字，或欄位流動排版， 可能無法重現其原始視覺版面。
• 不會套用字形（glyph）到 Unicode 的對應；使用自訂編碼之字型的文字， 可能會以原始位元組序列匯出。

效能

剖析與 PDF 位元組長度呈線性關係。記憶體用量隨輸入加上產生的輸出字串而變化。 performance_budget 前置資料是典型辦公文件的每次呼叫參考。

安全注意事項

轉換器以有界限的 strpos/substr 掃描在文字運算子上剖析不受信任的 PDF 位元組；它不會執行嵌入的 JavaScript，也不會跟隨外部參照。請將匯出的 HTML 視為不受信任的內容，並針對其目的地適當地進行轉義。請參閱 Core 安全模型。

一致性

聲明	規範條款	狀態
剖析 Tj 文字顯示運算子	ISO 32000-2:2020 §9.4	已驗證（單元測試套件）
剖析 TJ 陣列文字顯示運算子	ISO 32000-2:2020 §9.4	已驗證（單元測試套件）
完整的向量/點陣頁面保真度	—	不支援（不在範圍內）

Core 回退/替代方案

PDF 匯出沒有任何 Core 對應方案。至於正方向（從 HTML 撰寫一份 PDF）， 開源 Core HTML 管線是受支援的路徑。請參閱 /modules/core/html/。

Enterprise 邊界註記

Converter 是 Pro 等級的文字/形狀匯出器。它不執行 OCR、語意重建或文件理解。 那些是各自獨立的範疇，本模組不提供。

出版邊界

本頁僅記載外部可觀察的行為，以及受支援的公開 API 介面。內部命名空間路徑、 輔助類別、機制表格、維運手冊檔名與工單前綴皆不在範圍內。

另請參閱

• Converter —— 深入參考
• Extraction
• Diff
• Core HTML 管線