Fuentes: tipos de valor, incrustación y respaldo

De un vistazo

En NextPDF, una fuente se representa como el objeto de valor inmutable FontInfo más el tipo de tecnología que determina cómo la incrusta el motor. El motor incrusta cada fuente que utiliza. Una referencia heredada a las Base 14 recurre a un sustituto incluido y compatible en métricas.

Instalación

composer require nextpdf/core:^3

Panorama conceptual

FontInfo es el único objeto de valor inmutable que reúne todo lo que el motor necesita para incrustar una fuente: la familia y el estilo, el nombre PostScript, los indicadores del descriptor, las métricas escaladas a un em de 1000 unidades, los anchos de carácter, el mapa de glifo a Unicode, el cmap directo (Unicode a identificador de glifo), los bytes en bruto de la fuente y —cuando están presentes— los ejes de variación, las instancias con nombre, los selectores de variación, los pares de kerning y las métricas verticales. Es final readonly. La firma del constructor y las propiedades públicas están congeladas, de modo que una fuente analizada es un hecho estable y compartible. FontInfo::encodeText() es el único método que realiza trabajo. Pasa por el resolutor de codificación y devuelve un EncodedGlyphRun.

FontType enumera las tecnologías que incrusta el motor: TrueType (codificación de un solo byte), TrueTypeUnicode (codificación CID multibyte para escrituras ricas en Unicode), OpenType (contornos Compact Font Format), Type1 (PostScript Type 1, registrado a partir de un par PFB y AFM) y CidFont0 (una fuente CID basada en PostScript). El tipo que asigna el analizador determina la forma del diccionario de fuente que emite el escritor.

El motor incrusta el programa de fuente para que el documento se represente igual en cualquier visor, sin depender de las fuentes del sistema instaladas — ISO 32000-2 §9. Un programa TrueType se incrusta mediante la entrada FontFile2 del descriptor de fuente y debe incluir las tablas glyf, head, hhea, hmtx, loca y maxp — ISO 32000-2 §9.6.5 (resumen RAG truncado por el límite de licencia; registrado en _downgraded-claims-o3.md). Un programa OpenType con una tabla de contornos Compact Font Format se incrusta mediante FontFile3 — ISO 32000-2 §9.6.5 (resumen RAG truncado; ver el mismo registro). El subdivisor reconstruye exactamente este conjunto de tablas requerido, de modo que el subconjunto incrustado sigue siendo un programa conforme.

El respaldo cubre el caso heredado de las Base 14. Base14SubstituteFonts asigna una clave Base 14 normalizada — helvetica, helveticab, times, courier y el resto — a un archivo Liberation Fonts incluido. Liberation Sans, Serif y Mono son compatibles en métricas con Helvetica o Arial, Times Roman y Courier. Cada una es una cara TrueType incrustada, de modo que representa todo el repertorio latino de WinAnsiEncoding (Windows-1252) que requiere una referencia de las standard-14: latín acentuado, el signo del euro y los signos de puntuación tipográfica habituales (ISO 32000-2 Annex D.2). Symbol y ZapfDingbats no disponen de ningún reemplazo permisivo y compatible en métricas, y deliberadamente no se sustituyen; un documento que los necesite debe registrar una fuente incrustable. El resolutor no tiene efectos secundarios: solo indica qué archivo corresponde a una clave. El registro con el registry sigue siendo responsabilidad de quien llama, lo que preserva la semántica de bloqueo y el flujo de calentamiento.

Superficie de la API

Tipo	Clase	Miembros clave	Estabilidad	Desde
FontInfo	clase final readonly	$family, $style, $type, $unitsPerEm, $widths, $unicodeMap, $cmapForward, $fileData, $variationAxes, $kernPairs, getKey(), encodeText()	estable	1.0.0
FontType	enum (string)	TrueType, TrueTypeUnicode, OpenType, Type1, CidFont0	estable	1.0.0
Base14SubstituteFonts	clase final (interna)	clave Base 14 normalizada a ruta de archivo Liberation incluido	estable	2.7.0
ShaperFactory	clase final	default(), create(), wouldUseRealShaper()	estable	3.2.0
ShapingResult	clase final readonly	$glyphRuns, $originalText, $script, $direction, $shaperImpl	estable	3.2.0

Base14SubstituteFonts es @internal — solo para uso del framework, sin compatibilidad con versiones anteriores en su superficie.

Ejemplo de código — Inicio rápido

examples/35-cjk-cmap-demo.php

<?php

declare(strict_types=1);

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

use NextPDF\Typography\FontRegistry;
use NextPDF\Typography\FontType;

$registry = new FontRegistry();
$font = $registry->register('/path/to/NotoSansTC-Regular.ttf', alias: 'NotoSansTC');

// FontInfo is the immutable parsed fact about the face.
echo $font->family, ' / ', $font->type->value, "\n"; // e.g. "Noto Sans TC / TrueTypeUnicode"
assert($font->type === FontType::TrueTypeUnicode);

El analizador rellena FontInfo y asigna el FontType. Una cara TrueType con cmap Unicode se convierte en TrueTypeUnicode, que el escritor emite como una fuente compuesta Type 0.

Ejemplo de código — Producción

examples/font/base14-fallback.php

<?php

declare(strict_types=1);

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

use NextPDF\Typography\Base14SubstituteFonts;
use NextPDF\Typography\FontRegistry;

final readonly class Base14EmbeddingResolver
{
    public function __construct(private FontRegistry $registry) {}

    /**
     * Register an embeddable substitute for a legacy Base 14 key so the
     * output document embeds every font (PDF/A-4 and PDF/UA-2 require it).
     */
    public function ensureEmbeddable(string $base14Key): void
    {
        $path = Base14SubstituteFonts::resolve($base14Key);

        if ($path === null) {
            // Symbol / ZapfDingbats have no permissive substitute — the
            // caller must supply its own embeddable font.
            throw new \RuntimeException("No bundled substitute for {$base14Key}");
        }

        if (!$this->registry->has($base14Key)) {
            $this->registry->register($path, alias: $base14Key);
        }
    }
}

El resolutor no tiene efectos secundarios. El registro se mantiene explícito para que se cumplan los contratos de bloqueo y calentamiento del registry. Symbol y ZapfDingbats no devuelven ninguna ruta por diseño.

Casos límite y trampas

• Symbol y ZapfDingbats no se sustituyen intencionadamente. Un resultado nulo para esas claves es el comportamiento documentado, no un error por fuente faltante.
• FontInfo es final readonly. Una fuente analizada debe tratarse como un valor: no se debe esperar que los anchos o las métricas muten in situ; hay que volver a registrarla si cambia el origen.
• Una fuente Type 1 necesita tanto el contorno PFB como las métricas AFM. FontRegistry::registerType1() toma el par; la detección automática deriva la ruta del AFM a partir de la ruta del PFB por la extensión.
• FontType::TrueType frente a FontType::TrueTypeUnicode es la distinción entre un solo byte y multibyte. El resolutor de codificación se basa en el cmap directo ya rellenado, no en el nombre de la familia, así que una cara TrueType Unicode se enruta automáticamente a la vía Identity-H.
• Los ejes de fuente variable y las instancias con nombre se analizan en FontInfo cuando están presentes, pero el ejemplo CJK desarrollado usa deliberadamente la cara estática para mantener determinista el FontInfo analizado.

Rendimiento

El registry asigna FontInfo una vez por fuente y por proceso, y a partir de entonces se comparte por referencia. Contiene los bytes en bruto de la fuente, que son el coste de memoria dominante. Un worker debe calentar solo las fuentes que necesita y supervisar memoryUsage(). El resolutor de sustitutos de las Base 14 es una búsqueda en un mapa en tiempo constante, sin E/S hasta que quien llama registra el archivo resuelto. El performance_budget de 1500 ms de tiempo de reloj y un pico de 64 MB cubre el calentamiento de un conjunto típico de fuentes más el renderizado. La huella de memoria por fuente crece con el tamaño del archivo de fuente, no con el recuento de glifos, hasta que se ejecuta el subdivisor.

Notas de seguridad

FontInfo en sí es inerte: contiene datos analizados sin comportamiento más allá de la transformación pura encodeText(). La superficie de ataque está aguas arriba, en el momento del análisis: bytes de fuente arbitrarios que llegan al analizador TrueType o Type 1. Los analizadores comprueban los límites de cada desplazamiento binario y rechazan los envoltorios de flujo y los bytes nulos en las rutas. La entrada de fuente no confiable debe pasar por una política de recursos externos que acote el tamaño y el recuento de glifos antes del registro. Los sustitutos Liberation incluidos son recursos de confianza distribuidos con el paquete, así que la vía de respaldo no introduce ninguna nueva entrada no confiable.

Conformidad

Afirmación	Estándar	Cláusula	Evidencia
Cada fuente que usa el documento se incrusta para que el documento se represente sin depender de las fuentes del sistema.	ISO 32000-2	§9
Un programa TrueType se incrusta mediante FontFile2 con las tablas glyf, head, hhea, hmtx, loca y maxp.	ISO 32000-2	§9.6.5	Resumen RAG truncado por el límite de licencia; prefijo 7b26f37996239b2a, ver _downgraded-claims-o3.md
Un programa OpenType (CFF) se incrusta mediante FontFile3.	ISO 32000-2	§9.6.5	Resumen RAG truncado por el límite de licencia; prefijo 801549ee00623baf, ver _downgraded-claims-o3.md

La primera cláusula está respaldada por el resumen y corroborada por B1. Las cláusulas de FontFile2 y FontFile3 están parafraseadas. Sus resúmenes RAG completos no se devolvieron (truncamiento por el límite de licencia) y están corroborados por FontSubsetter (que reconstruye exactamente el conjunto glyf/head/hhea/hmtx/loca/maxp) y el enum FontType. NextPDF no reproduce texto normativo. Base14SubstituteFonts cita ISO 32000-2 §9.6.2.2 (manejo estándar de fuentes Type 1), ISO 14289-2:2024 §8.4.5.5.1 (incrustación de fuentes PDF/UA-2) e ISO 19005-4:2020 §6.3.5 (incrustación de fuentes PDF/A-4) en el código fuente. Las páginas de accesibilidad y conformidad recogen la conformidad completa del perfil.

Contexto comercial

Un pack comercial de licenciamiento de fuentes y un servicio de subdivisión dinámica se basan en el FontInfo del Core y el registry. El módulo de fuentes del Core incrusta, divide en subconjuntos y recurre al respaldo libre de licencias. La omisión de un enlace de conversión es intencionada.

Véase también

• Tipografía: registry, subdivisión, CMap, codificación, BiDi — el registry y la subdivisión que producen y consumen FontInfo.
• Texto: shaping, salto de línea, BiDi — el punto de integración de shaping que consume la secuencia codificada.
• Contratos / Tipografía — el contrato FontRegistryInterface.