Texto, fuentes y aspectos básicos de la página

En el primer tutorial se renderizó una página con una sola línea de texto. Esta vez se toma el control de la página en sí y del texto que contiene. Se elige un tamaño de página, se escriben títulos y párrafos, y se les aplica estilo con las fuentes integradas del motor.

Qué se va a construir

Se escriben dos scripts pequeños. Cada uno produce un archivo en formato de documento portátil (PDF) de una sola página:

• 01-text-basics.php renderiza una página A4 en orientación vertical con un título de color, párrafos ajustados y tres muestras de alineación.
• 02-fonts.php renderiza una página de muestrario que compara dos familias de fuentes integradas en varios tamaños.

Todo funciona únicamente con el paquete nextpdf/core. No hacen falta archivos de fuentes, ni extensiones adicionales, ni red. Si todavía no hay un proyecto configurado, seguir primero el primer tutorial y luego volver.

Paso 1: Aplicar estilo al texto en una página A4

Cada página tiene un tamaño y una orientación. A4 es el tamaño de papel internacional habitual, y Letter es su equivalente en Estados Unidos. La orientación es vertical (en pie) u horizontal (de lado). Ambas opciones se pasan a addPage() al iniciar una página.

Después, tres métodos se encargan de la escritura. setFont() elige el tipo de letra y el tamaño del texto que sigue. cell() escribe una línea dentro de una caja invisible. multiCell() ajusta el texto más largo en tantas líneas como necesite. En ambos métodos, un ancho de 0 significa «usar todo hasta el margen derecho».

Otras dos llamadas se ocupan de la apariencia. setTextColor() toma valores de rojo, verde y azul de 0 a 255, y se aplica hasta que se vuelve a cambiar. El enum Alignment, una lista fija de opciones con nombre, ofrece Left, Center, Right y Justify.

Crear 01-text-basics.php en la carpeta del proyecto:

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Contracts\Orientation;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Text basics');
$document->addPage(PageSize::A4(), Orientation::Portrait);

// A colored heading. The values are red, green, and blue, each 0 to 255.
$document->setFont('helvetica', 'B', 20);
$document->setTextColor(30, 64, 175);
$document->cell(0, 14, 'Project kickoff notes', newLine: true);
$document->ln(4);

// Back to black for the body text.
$document->setTextColor(0, 0, 0);
$document->setFont('helvetica', '', 11);
$document->multiCell(
    0,
    7,
    'Welcome to the second tutorial. This paragraph is written with '
        . 'multiCell(), so the engine wraps the words onto as many lines '
        . 'as the page width requires.',
);
$document->ln(4);

$document->multiCell(
    0,
    7,
    'Justified text stretches the spaces so both edges line up. It is a '
        . 'good fit for report bodies and other long passages.',
    align: Alignment::Justify,
);
$document->ln(6);

// One line each: left, centered, and right.
$document->setFont('helvetica', 'I', 11);
$document->cell(0, 8, 'Left-aligned line', newLine: true, align: Alignment::Left);
$document->cell(0, 8, 'Centered line', newLine: true, align: Alignment::Center);
$document->cell(0, 8, 'Right-aligned line', newLine: true, align: Alignment::Right);

$document->save(__DIR__ . '/out/text-basics.pdf');

echo "Wrote out/text-basics.pdf\n";

Ejecutarlo con php 01-text-basics.php. El script imprime Wrote out/text-basics.pdf, y el archivo aparece en la nueva carpeta out/.

Qué acaba de pasar

addPage(PageSize::A4(), Orientation::Portrait) creó la página antes de escribir cualquier texto. Al pasar Orientation::Landscape en su lugar, la misma página gira de lado. Otros tamaños con nombre, como PageSize::A5() o PageSize::Letter(), funcionan igual.

setFont('helvetica', 'B', 20) seleccionó Helvetica en negrita a 20 puntos. Un punto (pt) es la unidad de impresión tradicional; 72 puntos equivalen a una pulgada. El título es azul porque setTextColor(30, 64, 175) estaba activo cuando la llamada a cell() lo escribió. La siguiente llamada setTextColor(0, 0, 0) volvió al negro para todo lo que viene después.

Las dos llamadas a multiCell() ajustaron sus párrafos automáticamente. La versión justificada estira el espaciado entre palabras para que ambos bordes queden alineados, salvo en la última línea del párrafo. Entre bloques, ln() desplazó hacia abajo la posición de escritura para dar un poco de espacio. Por último, save() construyó el archivo y lo escribió en out/.

Para conocer todos los parámetros que aceptan estos métodos, consultar Componer texto con fuentes y alineación.

Paso 2: Elegir entre las fuentes integradas

El motor incluye de serie tres familias de texto: Helvetica, Times y Courier. Helvetica es una tipografía de palo seco (sans serif), es decir, sus letras carecen de los pequeños remates terminales (serifas). Times es una tipografía con serifas que se lee bien en pasajes largos, de aspecto impreso. Courier es de ancho fijo, por lo que resulta adecuada para listados de código y recibos. Como estas familias vienen integradas, los scripts no necesitan ningún archivo de fuentes.

El argumento de estilo de setFont() combina indicadores de una sola letra: 'B' para negrita, 'I' para cursiva y 'U' para subrayado. Una cadena vacía significa normal, y los indicadores se combinan, de modo que 'BI' da negrita cursiva.

Las familias integradas cubren el texto de base latina. Para otros sistemas de escritura o para la tipografía de una marca propia, se registra un archivo de fuente, tal como muestra la receta Incrustar y subdividir fuentes (la subdivisión conserva solo los caracteres que realmente se usaron, de modo que los archivos se mantienen pequeños). La matriz de compatibilidad de fuentes enumera todos los formatos de fuente que acepta el motor.

Crear 02-fonts.php junto al primer script:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Font sampler');
$document->addPage();

$document->setFont('helvetica', 'B', 20);
$document->cell(0, 14, 'Built-in font sampler', newLine: true);
$document->ln(4);

// Helvetica: a sans-serif face, a solid default for labels and headings.
$document->setFont('helvetica', 'B', 14);
$document->cell(0, 10, 'Helvetica', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('helvetica', '', (float) $size);
    $document->cell(0, $size * 0.8, "Helvetica sample at {$size}pt.", newLine: true);
}
$document->setFont('helvetica', 'BI', 12);
$document->cell(0, 9, 'Helvetica bold italic for emphasis.', newLine: true);
$document->ln(6);

// Times: a serif face that suits long, print-like passages.
$document->setFont('times', 'B', 14);
$document->cell(0, 10, 'Times', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('times', '', (float) $size);
    $document->cell(0, $size * 0.8, "Times sample at {$size}pt.", newLine: true);
}
$document->setFont('times', 'I', 12);
$document->cell(0, 9, 'Times italic for quotations.', newLine: true);

$document->save(__DIR__ . '/out/font-sampler.pdf');

echo "Wrote out/font-sampler.pdf\n";

Ejecutarlo con php 02-fonts.php y abrir out/font-sampler.pdf. Se ve cómo la misma frase de muestra cambia de aspecto entre las dos familias y crece a lo largo de tres tamaños.

Qué acaba de pasar

addPage() sin argumentos usó la configuración de página predeterminada en orientación vertical, de modo que no todos los scripts tienen que especificar el tamaño. Cada llamada a setFont() cambió la familia, el estilo o el tamaño activos a mitad de página, y una fuente permanece activa hasta la siguiente llamada a setFont().

Los bucles convierten el tamaño con (float) porque setFont() espera un número decimal. Las alturas de línea escalan con el tamaño de la fuente ($size * 0.8), de modo que el texto más grande tiene líneas más altas y nada se superpone. Probar a reemplazar 'times' por 'courier' y ejecutar el script de nuevo para ver la tercera familia.

Si algo salió mal

• Un error de tipo «class not found» o de autoload suele indicar que el script no encontró vendor/autoload.php. Ejecutarlo dentro de la carpeta del proyecto que contiene vendor/.
• Un nombre de familia mal escrito lanza una excepción que indica la fuente que no se pudo encontrar. Comprobar la ortografía: helvetica, times, courier.
• El centro de resolución de problemas reúne soluciones habituales, y Fuentes y etiquetado trata los problemas de fuentes en profundidad.
• Todas las excepciones del motor están documentadas en la referencia de errores, con el contexto que aportan y la acción de recuperación.

Siguiente

Ahora se puede dar forma a las páginas, aplicar estilo al texto y elegir fuentes con intención. En el siguiente tutorial se colocan imágenes en la página y se organiza el contenido con tablas y listas.