Pro 에디션

변환기

한눈에 보기

NextPDF\Pro\Converter는 기존 PDF를 읽어 그 콘텐츠를 세 가지 텍스트 기반 대상 중 하나로 내보냅니다. 위치가 지정된 HTML, 단순화된 SVG, 또는 일반 텍스트입니다. 이는 콘텐츠 추출 내보내기 도구이며 픽셀 단위로 완벽한 PDF 렌더러가 아닙니다.

가용성 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)에서 제공되며 Pro 등급 라이선스 봉투로 활성화됩니다. 해당 권한이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

이 모듈을 게이트하는 런타임 기능 플래그는 없습니다. Converter 클래스는 Pro 패키지가 설치되어 오토로드될 때마다 확인됩니다.

설치

composer require nextpdf/pro:^3

개념 개요

Converter는 PDF 콘텐츠 스트림 내부의 텍스트 표시 연산자 — ISO 32000-2:2020 §9.4에 따른 Tj, TJ, ' —를 파싱하여 각 페이지의 근사 표현을 다시 구축합니다. Td 및 Tm 텍스트 연산자에서 위치를, Tf에서 글꼴 크기를 읽은 뒤 포인트를 출력 좌표로 매핑합니다.

ConversionTarget마다 하나씩 세 가지 변환기가 노출됩니다.

**PdfToHtmlConverter**는 각 페이지를 위치가 지정된 컨테이너로 감싸고 각 텍스트 런에 대해 절대 위치가 지정된 <div> 요소를 방출합니다. 출력은 자체 완결형 HTML5 문서입니다.
**PdfToSvgConverter**는 제한된 그리기 연산자 집합(re를 통한 사각형, m/l을 통한 선)과 텍스트를 파싱하고, 한 페이지에 대해 대응하는 <rect>, <line>, <text> 요소를 방출합니다.
**PdfToTextConverter**는 디코딩된 텍스트만 페이지 단위로 추출하며, 페이지 구분 마커로 분리합니다.

이는 의도적으로 경계가 지정된 내보내기 도구입니다. 텍스트 위치를 근사하며, 리플로우하지 않고, 래스터화하지 않으며, 벡터 경로, 셰이딩, 클리핑, 투명도, 임베드된 이미지를 재현하지 않습니다. 반대 방향의 완전 충실도 HTML-to-PDF 렌더링에는 Core HTML 파이프라인을 사용하십시오.

이렇게 동작하는 이유

PDF는 텍스트를 시맨틱 문자가 아니라 위치가 지정된 글리프 표시 연산자로 저장하므로, 다시 읽어들일 신뢰할 수 있는 문서 텍스트가 존재하지 않습니다. 따라서 Converter는 콘텐츠 스트림 연산자를 직접 스캔하고 — Tj, TJ, ', 그리고 배치를 위한 Td, Tm, Tf — 페이지를 리플로우하거나 래스터화하는 대신 근사 레이아웃을 다시 구축합니다. 이 경계가 지정된 스캔 덕분에 내보내기는 바이트 길이에 선형적이고, 동일한 입력에 대해 결정적이며, 임베드된 로직을 실행하지 않고도 신뢰할 수 없는 바이트에 대해 안전합니다. 또한 이는 정직한 한계를 설정합니다. 글리프는 유니코드로 역매핑되지 않으므로, 사용자 정의 인코딩 글꼴은 원시 바이트로 내보내지고 정확한 시각적 충실도는 범위를 벗어납니다. 설계 배경: 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로 선택된 한 번에 한 페이지씩 변환합니다. 범위를 벗어난 인덱스는 빈 페이지 스트림을 산출합니다.
위치 지정은 근사적입니다. 텍스트 외 변환으로 배치된 텍스트, 회전된 텍스트, 또는 단 흐름은 원래의 시각적 레이아웃을 재현하지 못할 수 있습니다.
글리프-유니코드 매핑은 적용되지 않습니다. 사용자 정의 인코딩을 사용하는 글꼴의 텍스트는 원시 바이트 시퀀스로 내보내질 수 있습니다.

성능

파싱은 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 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위를 벗어납니다.