Testo, font e nozioni di base sulle pagine

Nel primo tutorial è stata generata una pagina con una sola riga di testo. Questa volta si prende il controllo della pagina stessa e del testo che vi compare. Si sceglierà un formato di pagina, si scriveranno intestazioni e paragrafi e li si formatterà con i font incorporati del motore.

Cosa si costruirà

Si scriveranno due piccoli script. Ciascuno produce un file Portable Document Format (PDF) di una sola pagina:

• 01-text-basics.php genera una pagina A4 in orientamento verticale con un’intestazione colorata, paragrafi con a capo automatico e tre esempi di allineamento.
• 02-fonts.php genera una pagina di campionario che confronta due famiglie di font incorporate a diverse dimensioni.

Tutto funziona con il solo pacchetto nextpdf/core. Non servono file di font, né estensioni aggiuntive, né una connessione di rete. Se non si dispone ancora di un progetto configurato, seguire prima il primo tutorial e poi tornare qui.

Passaggio 1: formattare il testo su una pagina A4

Ogni pagina ha un formato e un orientamento. A4 è il formato di carta internazionale più diffuso, mentre Letter è il suo equivalente statunitense. L’orientamento è verticale (portrait, in piedi) oppure orizzontale (landscape, coricato). Entrambe le scelte si passano a addPage() quando si avvia una pagina.

A occuparsi della scrittura sono poi tre metodi. setFont() seleziona il tipo di carattere e la dimensione per il testo che segue. cell() scrive una riga all’interno di un riquadro invisibile. multiCell() manda a capo il testo più lungo su tutte le righe necessarie. In entrambi i metodi, una larghezza pari a 0 significa «usare tutto lo spazio fino al margine destro».

Altre due chiamate ne curano l’aspetto. setTextColor() accetta i valori di rosso, verde e blu da 0 a 255 e resta attivo finché non lo si modifica di nuovo. L’enum Alignment, un elenco fisso di scelte con nome, offre Left, Center, Right e Justify.

Creare 01-text-basics.php nella cartella del progetto:

<?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";

Eseguirlo con php 01-text-basics.php. Lo script stampa Wrote out/text-basics.pdf e il file compare nella nuova cartella out/.

Cosa è appena successo

addPage(PageSize::A4(), Orientation::Portrait) ha creato la pagina prima che venisse scritto qualsiasi testo. Passando invece Orientation::Landscape, la stessa pagina ruota in orizzontale. Altri formati con nome, come PageSize::A5() o PageSize::Letter(), funzionano allo stesso modo.

setFont('helvetica', 'B', 20) ha selezionato l’Helvetica grassetto a 20 punti. Il punto (pt) è la tradizionale unità tipografica: 72 punti equivalgono a un pollice. L’intestazione è blu perché setTextColor(30, 64, 175) era attivo quando la chiamata cell() l’ha scritta. Il successivo setTextColor(0, 0, 0) ha ripristinato il nero per tutto ciò che segue.

Le due chiamate a multiCell() hanno mandato a capo i rispettivi paragrafi automaticamente. Quella giustificata dilata la spaziatura tra le parole in modo che entrambi i bordi risultino allineati, tranne sull’ultima riga del paragrafo. Tra un blocco e l’altro, ln() ha spostato la posizione di scrittura verso il basso per aggiungere un po’ di respiro. Infine, save() ha costruito il file e lo ha scritto in out/.

Per ogni parametro accettato da questi metodi, vedere Comporre il testo con font e allineamento.

Passaggio 2: scegliere tra i font incorporati

Il motore include tre famiglie di testo incorporate: Helvetica, Times e Courier. Helvetica è un carattere sans-serif, ossia le sue lettere non hanno i piccoli tratti terminali (le grazie, o serif). Times è un carattere con grazie che si legge bene in lunghi passaggi dall’aspetto tipografico. Courier è a larghezza fissa, quindi si presta a listati di codice e ricevute. Poiché queste famiglie sono incorporate, gli script non necessitano di alcun file di font.

L’argomento dello stile di setFont() combina flag di una singola lettera: 'B' per il grassetto, 'I' per il corsivo e 'U' per il sottolineato. Una stringa vuota indica lo stile normale e i flag si combinano, quindi 'BI' produce il grassetto corsivo.

Le famiglie incorporate coprono il testo latino di base. Per altri sistemi di scrittura o per il carattere del proprio marchio, si registra un file di font, come illustra la ricetta Incorporare e creare sottoinsiemi di font (la creazione di sottoinsiemi conserva solo i caratteri effettivamente utilizzati, così i file restano piccoli). La matrice di supporto dei font elenca ogni formato di font accettato dal motore.

Creare 02-fonts.php accanto al primo 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";

Eseguirlo con php 02-fonts.php e aprire out/font-sampler.pdf. Si vede la stessa frase di esempio cambiare aspetto tra le due famiglie e crescere attraverso tre dimensioni.

Cosa è appena successo

addPage() senza argomenti ha usato la configurazione di pagina predefinita in orientamento verticale, così non tutti gli script devono specificare il formato. Ogni chiamata a setFont() ha cambiato famiglia, stile o dimensione attivi a metà pagina, e un font resta attivo fino alla successiva chiamata a setFont().

I cicli convertono la dimensione con (float) perché setFont() si aspetta un numero decimale. Le altezze di riga scalano con la dimensione del font ($size * 0.8), così il testo più grande ha righe più alte e nulla si sovrappone. Provare a sostituire 'times' con 'courier' ed eseguire di nuovo lo script per vedere la terza famiglia.

Se qualcosa è andato storto

• Un errore «class not found» o di autoload di solito significa che lo script non ha trovato vendor/autoload.php. Eseguirlo all’interno della cartella del progetto che contiene vendor/.
• Un nome di famiglia digitato in modo errato genera un’eccezione che indica il font non trovato. Controllare l’ortografia: helvetica, times, courier.
• L’hub di risoluzione dei problemi raccoglie le soluzioni più comuni e Font e tagging tratta in dettaglio i problemi relativi ai font.
• Ogni eccezione del motore è documentata nel riferimento degli errori, con il contesto che fornisce e l’azione di ripristino.

Passi successivi

Ora si è in grado di dare forma alle pagine, formattare il testo e scegliere i font con criterio. Nel prossimo tutorial si collocano immagini sulla pagina e si organizzano i contenuti con tabelle ed elenchi.