Buat konten teks yang dapat diekstraksi oleh alat hilir

Sekilas

NextPDF Core berperan sebagai produsen PDF. Core tidak menyediakan pembaca PDF-ke-teks publik. Dalam konteks Core, “ekstraksi konten teks” berarti Anda menyusun dokumen agar teksnya dapat diekstraksi. Glif membawa CMap /ToUnicode, dan dokumen memiliki struktur logis bertanda. Pembaca yang memenuhi standar atau alat ekstraksi hilir kemudian dapat memulihkan teks Unicode sesuai urutan baca.

Membaca teks dari PDF pihak ketiga mana pun adalah tanggung jawab konsumen. Untuk tugas itu, gunakan sidecar modul Inspect atau alat eksternal, bukan antarmuka produsen Core.

Pemasangan

composer require nextpdf/core:^3

Tinjauan konseptual

Operator penampil teks dalam aliran konten menempatkan teks pada halaman (ISO 32000-2 §9.4.3). Kode glif bukanlah Unicode. CMap /ToUnicode memungkinkan pembaca memetakan kode tersebut kembali ke Unicode untuk ekstraksi (ISO 32000-2 §9.10.2). Pohon struktur bertanda mencatat urutan baca logis, sehingga proses ekstraksi dapat memulihkan teks sesuai urutan dokumen, bukan urutan penggambaran (ISO 32000-2 §14.8).

enableTaggedPdf() membangun pohon struktur tersebut dan mempertahankan CMap /ToUnicode untuk fon subset yang tersemat. Gabungan fitur tersebut membuat keluaran dapat diekstraksi secara andal.

Antarmuka API

Document::enableTaggedPdf(string $lang = 'en') membangun pohon struktur dan menetapkan mode konformitas yang mempertahankan CMap /ToUnicode. Document::setLanguage(string $lang) mencatat tag bahasa BCP 47. Panggil kedua metode ini sebelum Anda menulis konten. Setelah itu, tulis teks dengan antarmuka setFont() / cell() / multiCell() seperti biasa.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Program mandiri ini berjalan di dalam harness. Contoh ini mencerminkan examples/38-extract-text-content.php. Program ini membuat dokumen bertanda dengan teks yang membawa CMap /ToUnicode dan urutan baca logis. Ekstraktor hilir kemudian dapat memulihkan teks Unicode sesuai urutan.

<?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 yang diharapkan:

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

Kasus tepi & jebakan

Produsen, bukan pembaca. Core tidak memiliki extractText() publik. Membaca teks dari PDF pihak ketiga yang sudah ada adalah tugas konsumen. Gunakan modul Inspect dengan sidecar Spectrum, atau gunakan alat ekstraksi eksternal. Resep ini membuat keluaran Anda dapat diekstraksi.
Konfigurasikan penandaan terlebih dahulu. Panggil enableTaggedPdf() sebelum Anda menulis konten, agar pohon struktur menangkap teks dalam urutan baca. Jika dipanggil setelah konten ditambahkan, metode ini tidak akan menandai konten sebelumnya.
Tag bahasa tidak valid. enableTaggedPdf() memvalidasi tag BCP 47 dan melemparkan InvalidConfigException ketika tag tidak valid. Gunakan tag terdaftar, misalnya en, zh-Hant-TW, atau ja.
Keluaran biasa (tanpa tanda). Tanpa enableTaggedPdf(), keluaran biasa dapat menekan CMap /ToUnicode untuk fon dengan CMap terdefinisi demi mengurangi ukuran. Ekstraksi kemudian menjadi tidak andal untuk fon tersebut. Tandai dokumen ketika Anda membutuhkan teks yang dapat diekstraksi.

Kinerja

Penandaan menambahkan pohon struktur dan mempertahankan CMap /ToUnicode, sehingga ukuran keluaran meningkat secara moderat. Overhead-nya meningkat mengikuti volume konten dan tidak mengubah model rendering satu-lintasan.

Catatan keamanan

Konten teks bertanda memang dirancang agar dapat dibaca mesin. Jangan menempatkan rahasia di dalam teks dokumen dan berharap rahasia itu tetap tersembunyi. Siapa pun yang memiliki berkasnya dapat mengekstraksi teks yang dapat diekstraksi. Resep ini membahas kebenaran sisi produsen, bukan kontrol kerahasiaan. Untuk kerahasiaan, lihat resep enkripsi.

Konformitas

Pernyataan	Spesifikasi	Klausa
CMap ToUnicode memetakan kode karakter ke Unicode untuk ekstraksi teks.	ISO 32000-2	§9.10.2
Operator penampil teks menempatkan string pada halaman di dalam aliran konten.	ISO 32000-2	§9.4.3
Pohon struktur bertanda mencatat urutan baca logis untuk ekstraksi.	ISO 32000-2	§14.8

Resep ini menghasilkan konten teks yang dapat diekstraksi. Resep ini tidak mengeklaim konformitas PDF/UA-2, yang ditentukan oleh pemeriksa. Lihat resep aksesibilitas.