Pro エディション

コンバーター

概要

NextPDF\Pro\Converter は、既存の PDF を読み取り、その内容をテキストベースの 3 つのターゲット（位置付き HTML、簡略化された SVG、プレーンテキスト）のいずれかにエクスポートします。これはコンテンツ抽出エクスポーターであり、ピクセル単位で正確な PDF レンダラーではありません。

提供状況とライセンス

この機能は NextPDF Pro（nextpdf/pro）に同梱され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイでは、この機能のクラスはロードされません。エディションを比較してライセンスを取得する。

このモジュールをゲートするランタイムの機能フラグはありません。コンバーターのクラスは、Pro パッケージがインストールされてオートロードされていれば常に解決されます。

インストール

composer require nextpdf/pro:^3

概念的な概要

コンバーターは、PDF コンテンツストリーム内のテキスト表示演算子（ISO 32000-2:2020 §9.4 に準拠した Tj、TJ、'）を解析し、各ページのおおよその表現を再構築します。Td と Tm のテキスト演算子から位置情報を、Tf からフォントサイズを読み取り、ポイントを出力座標にマッピングします。

ConversionTarget ごとに 1 つずつ、3 つのコンバーターが公開されています。

PdfToHtmlConverter は、各ページを位置付きのコンテナで包み、テキストランごとに絶対配置の <div> 要素を出力します。出力は自己完結型の HTML5 ドキュメントです。
PdfToSvgConverter は、限定的な描画演算子のセット（re による矩形、 m/l による線）とテキストを解析し、それに対応する <rect>、<line>、 <text> 要素を 1 ページ分出力します。
PdfToTextConverter は、デコードされたテキストのみをページごとに抽出し、ページ区切りマーカーで区切ります。

これは意図的に範囲を限定したエクスポーターです。テキスト位置を近似しますが、リフローは行わず、ラスタライズも行わず、ベクトルパス、シェーディング、クリッピング、透明度、埋め込み画像を再現しません。反対方向の完全忠実な HTML から PDF へのレンダリングには、Core の HTML パイプラインを使用してください。

この仕組みの理由

PDF はテキストを意味的な文字ではなく位置付きのグリフ表示演算子として保存するため、読み戻せる信頼性の高いドキュメントテキストは存在しません。そのためコンバーターは、コンテンツストリームの演算子（Tj、TJ、'、および配置のための Td、Tm、Tf）を直接スキャンし、ページをリフローしたりラスタライズしたりする代わりに、おおよそのレイアウトを再構築します。この上限付きのスキャンこそが、エクスポートをバイト長に対して線形に保ち、同一の入力に対して決定的にし、埋め込みロジックを実行することなく信頼できないバイトに対して安全に保ちます。またこれは正直な限界も定めます。グリフは Unicode に逆マッピングされないため、カスタムエンコードされたフォントは生のバイトとしてエクスポートされ、正確な視覚的忠実度は範囲外のままです。設計の背景：PDF 内のテキストが本当のテキストではない理由。

振る舞いの契約

入力。 生 PDF バイト（string）。空文字列は InvalidArgumentException を発生させます。
出力。 生成された文字列、ConversionTarget、処理したページ数、処理時間の計測値を保持する ConversionResult 値オブジェクト。
カバレッジ。 テキストのエクスポート（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 で選択した 1 ページを一度に変換します。範囲外のインデックスは空のページストリームになります。
位置付けは近似です。テキスト以外の変換で配置されたテキスト、回転したテキスト、段組みのフローは、元の視覚レイアウトを再現しない場合があります。
グリフから 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 の境界に関する注意

コンバーターは Pro ティアのテキスト/シェイプエクスポーターです。OCR、セマンティックな再構築、ドキュメント理解は行いません。それらは別個の関心事であり、本モジュールでは提供されません。

公開の境界

この公開ページは、外部から観測可能な振る舞いと、サポートされる公開 API サーフェスのみを記述します。内部の名前空間パス、ヘルパークラス、メカニズムの表、ランブックのファイル名、チケットのプレフィックスは範囲外です。