Producir contenido de texto extraíble para herramientas posteriores

En resumen

NextPDF Core es un productor de PDF. No incluye un lector público de PDF a texto. En el contexto de Core, «extraer contenido de texto» significa crear el documento de modo que su texto sea extraíble. Los glifos llevan un CMap /ToUnicode, y el documento tiene una estructura lógica etiquetada. Un lector conforme o una herramienta de extracción posterior puede recuperar entonces el texto Unicode en orden de lectura.

Extraer texto de un PDF arbitrario de terceros es una responsabilidad del consumidor. Ese trabajo corresponde al sidecar del módulo Inspect o a una herramienta externa, no a la superficie de producción de Core.

Instalación

composer require nextpdf/core:^3

Visión conceptual

Los operadores de visualización de texto del flujo de contenido colocan texto en una página (ISO 32000-2 §9.4.3). Los códigos de glifo no son Unicode. Un CMap /ToUnicode permite que un lector asocie esos códigos con Unicode para la extracción (ISO 32000-2 §9.10.2). Un árbol de estructura etiquetado registra el orden de lectura lógico, de modo que la extracción recupera el texto en el orden del documento, no en el orden de pintado (ISO 32000-2 §14.8).

enableTaggedPdf() construye ese árbol de estructura y conserva el CMap /ToUnicode para las fuentes incrustadas como subconjuntos. Esa combinación hace que la salida sea extraíble de forma fiable.

Superficie de la API

Document::enableTaggedPdf(string $lang = 'en') construye el árbol de estructura y establece el modo de conformidad que conserva el CMap /ToUnicode. Document::setLanguage(string $lang) registra el idioma natural BCP-47. Hay que llamar a ambos antes de escribir contenido. Después, escribir el texto con la superficie habitual de setFont() / cell() / multiCell().

Ejemplo de código — Inicio rápido

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

Ejemplo de código — Producción

Este es el programa autónomo que ejecuta el arnés. Corresponde a examples/38-extract-text-content.php. Crea un documento etiquetado cuyo texto lleva un CMap /ToUnicode y un orden de lectura lógico, para que un extractor posterior recupere el texto Unicode en orden.

<?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 esperado:

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

Casos límite y trampas

Productor, no lector. Core no tiene ningún extractText() público. Leer texto de un PDF de terceros existente es una tarea del consumidor. Usar el módulo Inspect con el sidecar Spectrum, o una herramienta de extracción externa. Esta recipe hace que la salida que se produce sea extraíble.
Configurar primero el etiquetado. Llamar a enableTaggedPdf() antes de escribir contenido, para que el árbol de estructura capture el texto en orden de lectura. Una llamada hecha después de añadir contenido no etiqueta el contenido previo.
Etiqueta de idioma no válida. enableTaggedPdf() valida la etiqueta BCP-47 y lanza InvalidConfigException si no es válida. Usar una etiqueta registrada, por ejemplo en, zh-Hant-TW o ja.
Salida sin etiquetar (plana). Sin enableTaggedPdf(), la salida plana puede suprimir el CMap /ToUnicode para las fuentes con CMap predefinido a fin de reducir el tamaño. La extracción es entonces poco fiable para esas fuentes. Etiquetar el documento cuando importe que el texto sea extraíble.

Rendimiento

El etiquetado añade el árbol de estructura y conserva los CMaps /ToUnicode, lo que aumenta de forma moderada el tamaño de la salida. El coste es proporcional al volumen de contenido y no cambia el modelo de renderizado de una sola pasada.

Notas de seguridad

El contenido de texto etiquetado es, por diseño, legible por máquina. No colocar secretos en el texto del documento esperando que permanezcan ocultos, porque cualquiera que tenga el archivo puede extraer ese texto. Esta es una recipe de corrección del productor, no un control de confidencialidad. Para la confidencialidad, consultar la recipe de cifrado.

Conformidad

Afirmación	Especificación	Cláusula
Un CMap ToUnicode asigna códigos de carácter a Unicode para la extracción de texto.	ISO 32000-2	§9.10.2
Los operadores de visualización de texto colocan cadenas en la página dentro del flujo de contenido.	ISO 32000-2	§9.4.3
Un árbol de estructura etiquetado registra el orden de lectura lógico para la extracción.	ISO 32000-2	§14.8

Esta recipe produce contenido de texto extraíble. No afirma conformidad con PDF/UA-2; esa determinación corresponde a un verificador. Consultar la recipe de accesibilidad.