Componer texto con fuentes y alineación

Vista rápida

Esta receta muestra cómo colocar texto y definir la familia de fuentes, el estilo, el tamaño y la alineación. Tres métodos realizan el trabajo: setFont(), cell() y multiCell(). El código se basa en examples/04-text-and-fonts.php.

Instalación

composer require nextpdf/core:^3

Esta restricción instala el paquete nextpdf/core. El ejemplo se ejecuta con PHP 8.4.

Panorama conceptual

setFont($family, $style, $size) selecciona la cara activa, es decir, la fuente que usará la siguiente llamada de texto. El argumento $style combina tres marcas: B (negrita), I (cursiva) y U (subrayado). La marca U es una decoración de texto; las demás seleccionan la variante de fuente. Las familias Helvetica, Times y Courier se resuelven en las 14 fuentes Type 1 estándar mencionadas en ISO 32000-2. Un perfil de conformidad puede anular este comportamiento y forzar la incrustación de una fuente sustituta.

cell() escribe una sola línea dentro de un cuadro. multiCell() ajusta el texto en una columna con el ancho y la altura de línea indicados. El texto se ubica en el espacio de texto, y la matriz de texto asigna el espacio de texto al espacio de usuario (ISO 32000-2). Se trabaja en unidades de usuario, y el motor emite la matriz correspondiente.

La alineación se define con la enumeración Alignment: Left, Center, Right, Justify. Para multiCell(), la justificación distribuye el espacio entre las palabras a lo largo de la línea.

Superficie de la API

setFont(string $family, string $style = '', float $size = 12.0): static — NextPDF\Core\Concerns\HasTypography.
cell(float $width, float $height, string $text = '', bool|string $border = false, bool $newLine = false, Alignment $align = Alignment::Left, bool $fill = false): static — NextPDF\Core\Concerns\HasTextOutput.
multiCell(float $width, float $height, string $text, bool|string $border = false, Alignment $align = Alignment::Left): static — mismo trait.
Alignment — NextPDF\Contracts\Alignment (Left, Center, Right, Justify).

La tabla completa de PHPDoc se genera a partir del código fuente.

Ejemplo de código — Inicio rápido

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Heading', newLine: true);

$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Word-wrapped justified body text.', align: Alignment::Justify);

$doc->save(__DIR__ . '/out.pdf');

Ejemplo de código — Producción

Este ejemplo es autónomo y el arnés de pruebas puede ejecutarlo. Corresponde a examples/04-text-and-fonts.php y muestra variantes de estilo, una gama de tamaños, texto justificado con ajuste de palabras y las tres alineaciones.

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Text and Fonts');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Text and Font Styles', newLine: true);
$doc->ln(5);

$doc->setFont('helvetica', '', 12);
$doc->cell(0, 8, 'Normal text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, 'Bold text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'I', 12);
$doc->cell(0, 8, 'Italic text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'BI', 12);
$doc->cell(0, 8, 'Bold-Italic text in Helvetica 12pt.', newLine: true);
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Font Sizes', newLine: true);
foreach ([8, 10, 12, 14, 18] as $size) {
    $doc->setFont('helvetica', '', (float) $size);
    $doc->cell(0, $size * 0.8, "This is {$size}pt text.", newLine: true);
}
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Multi-Line Text (Word Wrap)', newLine: true);
$doc->setFont('helvetica', '', 11);
$paragraph = 'NextPDF is a modern PDF 2.0 library for PHP. It provides a '
    . 'fluent API for document creation. This paragraph demonstrates '
    . 'automatic word wrapping and justified alignment with multiCell().';
$doc->multiCell(0, 7, $paragraph, align: Alignment::Justify);
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Text Alignment', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->cell(0, 8, 'Left-aligned text', newLine: true, align: Alignment::Left);
$doc->cell(0, 8, 'Center-aligned text', newLine: true, align: Alignment::Center);
$doc->cell(0, 8, 'Right-aligned text', newLine: true, align: Alignment::Right);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/compose-text-and-fonts.pdf');

echo "Wrote compose-text-and-fonts.pdf\n";

STDOUT esperado:

Wrote compose-text-and-fonts.pdf

Casos límite y problemas comunes

Ancho 0 significa ancho restante. Al pasar 0, cell(0, ...) y multiCell(0, ...) usan como ancho el espacio restante hasta el margen derecho. Para un cuadro de ancho fijo, pasar un ancho explícito.
Orden de la cadena de estilo. 'BI' e 'IB' seleccionan la misma variante negrita-cursiva, porque el analizador ignora el orden de las marcas. La marca 'U' representa una decoración de texto, no una variante de fuente.
Cobertura de glifos de las fuentes estándar. Las 14 fuentes estándar representan todo el repertorio de WinAnsiEncoding (Windows-1252). Esto cubre el latín acentuado de Europa Occidental, el signo del euro y los signos de puntuación tipográfica habituales: las rayas corta y larga, las comillas tipográficas, el bullet, los puntos suspensivos y el signo de marca registrada. Para escrituras ajenas a ese conjunto, como el chino, el japonés, el coreano, el árabe, el hebreo, el griego, el cirílico o el tailandés, registrar y seleccionar una cara TrueType. Consulta Incrustar fuentes y crear subconjuntos.
Altura de línea comparada con el tamaño de fuente. La altura de cada línea de multiCell() es el tamaño de fuente multiplicado por la relación de altura de línea predeterminada del perfil de métricas. Una altura demasiado pequeña puede hacer que las líneas se superpongan.
Justificación en la última línea. Un multiCell() justificado no estira la línea final de un párrafo. Esto coincide con la composición tipográfica convencional.

Rendimiento

La emisión de texto es lineal respecto al número de glifos, O(n). El presupuesto es wall_ms: 1000, peak_mb: 64. Es más bajo que en las recetas de HTML porque no hay cascada ni árbol de diseño. Las fuentes estándar no se incrustan, lo que mantiene reducido el tamaño de la salida.

Notas de seguridad

El contenido de texto se renderiza, no se interpreta. Validar la longitud de las cadenas proporcionadas por el usuario para mantener acotado el tamaño de la salida. Esta ruta no ejecuta ningún script ni obtiene ningún recurso remoto.

Conformidad

Declaración	Especificación	Cláusula	reference_id
Las familias Helvetica, Times y Courier están entre las 14 fuentes Type 1 estándar.	ISO 32000-2	iso32000_2_sec9#x1.x29
Las familias standard-14 admiten todo el conjunto de caracteres latinos (WinAnsiEncoding, página de códigos 1252 de Windows).	ISO 32000-2	Annex D.2 (iso32000_2_annexes#x1.x17.p4)	eb9220f88dfadad27a0be2206b64e68d8ea301d6d46e08142d43859c05fac6e4
Las coordenadas de texto están en el espacio de texto, asignadas al espacio de usuario por la matriz de texto.	ISO 32000-2	iso32000_2_sec8#x1.x10.p2

Esta receta muestra cómo NextPDF compone texto con las fuentes estándar. Su cobertura de glifos es todo el repertorio de WinAnsiEncoding (Windows-1252): latín de Europa Occidental más los signos de puntuación tipográfica habituales. El texto en otras escrituras requiere una cara incrustada.

Contexto comercial

No aplica.