다운스트림 도구에서 추출 가능한 텍스트 콘텐츠 생성

한눈에 보기

NextPDF Core는 PDF 생산자입니다. 공개 PDF-텍스트 변환 리더는 제공하지 않습니다. Core에서 “텍스트 콘텐츠 추출”이란 문서의 텍스트가 추출 가능하도록 작성하는 것을 의미합니다. 글리프에는 /ToUnicode CMap이 포함되며, 문서에는 태그된 논리 구조가 있습니다. 그러면 규격을 준수하는 리더나 다운스트림 추출 도구가 읽기 순서대로 유니코드 텍스트를 복원할 수 있습니다.

임의의 서드파티 PDF에서 텍스트를 다시 읽어내는 일은 소비자 측 관심사입니다. 이 작업은 Core 생산자 표면이 아니라 Inspect 모듈 사이드카나 외부 도구의 영역입니다.

설치

composer require nextpdf/core:^3

개념 개요

콘텐츠 스트림의 텍스트 표시 연산자는 페이지에 텍스트를 배치합니다(ISO 32000-2 §9.4.3). 글리프 코드는 유니코드가 아닙니다. /ToUnicode CMap을 사용하면 리더가 추출 과정에서 해당 코드를 유니코드로 다시 매핑할 수 있습니다(ISO 32000-2 §9.10.2). 태그된 구조 트리는 논리적 읽기 순서를 기록하므로, 추출할 때 페인팅 순서가 아닌 문서 순서대로 텍스트를 복원합니다(ISO 32000-2 §14.8).

enableTaggedPdf()는 해당 구조 트리를 구축하고 임베드된 서브셋 글꼴의 /ToUnicode CMap을 유지합니다. 이 조합으로 출력물을 안정적으로 추출할 수 있게 됩니다.

API 표면

Document::enableTaggedPdf(string $lang = 'en')는 구조 트리를 구축하고 /ToUnicode CMap을 보존하는 준수 모드를 설정합니다. Document::setLanguage(string $lang)는 BCP-47 자연어를 기록합니다. 콘텐츠를 작성하기 전에 두 메서드를 모두 호출하세요. 그런 다음 일반적인 setFont() / cell() / multiCell() API 표면을 사용해 텍스트를 작성합니다.

코드 샘플 — 빠른 시작

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setLanguage('en');
$doc->enableTaggedPdf('en');     // structure tree + ToUnicode retention
$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->multiCell(0, 7, 'This text is extractable by a downstream reader.');

file_put_contents(__DIR__ . '/extractable.pdf', $doc->getPdfData());

코드 샘플 — 프로덕션

다음은 독립적으로 실행되며 하네스에서도 실행 가능한 프로그램입니다. 예제 examples/38-extract-text-content.php와 같은 흐름입니다. 이 프로그램은 텍스트에 대해 /ToUnicode CMap과 논리적 읽기 순서를 포함하는 태그된 문서를 작성하므로, 다운스트림 추출기가 유니코드 텍스트를 순서대로 복원할 수 있습니다.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$paragraphs = [
    'NextPDF produces documents whose text content is extractable.',
    'A tagged structure tree records the logical reading order.',
    'The ToUnicode CMap lets a reader recover Unicode from glyph codes.',
];

$doc = Document::createStandalone();
$doc->setTitle('Extractable text content');
$doc->setAuthor('NextPDF Cookbook');
$doc->setLanguage('en');             // BCP 47; validated on enableTaggedPdf()

// Configure tagged mode BEFORE content so the structure tree captures the
// text in reading order and the /ToUnicode CMap is retained.
$doc->enableTaggedPdf('en');

$doc->addPage();
$doc->setFont('helvetica', '', 12);
foreach ($paragraphs as $p) {
    $doc->multiCell(0, 7, $p);       // captured in reading order
    $doc->ln(2);
}

$pdf = $doc->getPdfData();
// $pdf contains a /StructTreeRoot and per-font /ToUnicode CMaps; an external
// extractor (or the Inspect sidecar) recovers the Unicode text in order.

echo "Wrote a tagged PDF with extractable text content\n";
echo 'Paragraphs authored: ' . count($paragraphs) . "\n";
echo "Text is recoverable via the /ToUnicode CMap + tagged reading order.\n";

// The harness sets NEXTPDF_COOKBOOK_OUTPUT and runs this script under the
// semantic profile; emit the document to the side-channel.
$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
file_put_contents($out !== false && $out !== '' ? $out : __DIR__ . '/extractable.pdf', $pdf);

예상 STDOUT:

Wrote a tagged PDF with extractable text content
Paragraphs authored: 3
Text is recoverable via the /ToUnicode CMap + tagged reading order.

엣지 케이스 및 주의 사항

리더가 아닌 생산자. Core에는 공개 extractText()가 없습니다. 기존 서드파티 PDF에서 텍스트를 읽어내는 것은 소비자 측 작업입니다. Spectrum 사이드카와 함께 Inspect 모듈을 사용하거나, 외부 추출 도구를 사용하세요. 이 레시피는 사용자의 출력을 추출 가능하게 만듭니다.
태그 지정을 먼저 구성하세요. 콘텐츠를 작성하기 전에 enableTaggedPdf()를 호출하면 구조 트리가 텍스트를 읽기 순서대로 캡처합니다. 콘텐츠가 추가된 후에 호출하면 이미 추가된 콘텐츠에는 태그가 지정되지 않습니다.
잘못된 언어 태그. enableTaggedPdf()는 BCP-47 태그를 검증하고, 태그가 잘못된 경우 InvalidConfigException을 발생시킵니다. 등록된 태그를 사용하세요. 예를 들면 en, zh-Hant-TW 또는 ja 등이 있습니다.
일반(태그되지 않은) 출력. enableTaggedPdf() 없이는 일반 출력에서 크기를 줄이기 위해 미리 정의된 CMap 글꼴의 /ToUnicode CMap이 생략될 수 있습니다. 그러면 해당 글꼴의 추출 결과는 신뢰할 수 없게 됩니다. 추출 가능성이 중요하다면 문서에 태그를 지정하세요.

성능

태그 지정은 구조 트리를 추가하고 /ToUnicode CMap을 유지하므로 출력 크기가 다소 증가합니다. 비용은 콘텐츠 양에 비례하며, 단일 패스 렌더링 모델은 변경하지 않습니다.

보안 참고 사항

태그된 텍스트 콘텐츠는 설계상 기계 판독이 가능합니다. 추출 가능한 텍스트는 파일을 가진 누구나 추출할 수 있으므로, 비밀 정보를 문서 텍스트에 넣어도 숨겨진 상태로 유지될 것이라고 기대하지 마세요. 이것은 기밀성 제어가 아니라 생산자 정확성 레시피입니다. 기밀성이 필요하다면 암호화 레시피를 참조하세요.

준수

진술	사양	조항
ToUnicode CMap은 텍스트 추출을 위해 문자 코드를 유니코드로 매핑합니다.	ISO 32000-2	§9.10.2
텍스트 표시 연산자는 콘텐츠 스트림에서 페이지에 문자열을 배치합니다.	ISO 32000-2	§9.4.3
태그된 구조 트리는 추출을 위한 논리적 읽기 순서를 기록합니다.	ISO 32000-2	§14.8

이 레시피는 추출 가능한 텍스트 콘텐츠를 생성합니다. PDF/UA-2 준수를 주장하지는 않으며, 해당 여부는 검사기가 판정할 사항입니다. 접근성 레시피를 참조하세요.