Texte, polices et bases de la page

Dans le premier tutoriel, tu as généré une page avec une seule ligne de texte. Cette fois, tu prends le contrôle de la page elle-même et du texte qui s’y trouve. Tu vas choisir une taille de page, écrire des titres et des paragraphes, et les mettre en forme avec les polices intégrées du moteur.

Ce que tu vas construire

Tu vas écrire deux petits scripts. Chacun produit un fichier PDF (Portable Document Format) d’une page :

• 01-text-basics.php génère une page A4 en portrait avec un titre coloré, des paragraphes mis à la ligne automatiquement et trois exemples d’alignement.
• 02-fonts.php génère une page d’échantillons qui compare deux familles de polices intégrées à plusieurs tailles.

Tout fonctionne avec le seul paquet nextpdf/core. Tu n’as besoin d’aucun fichier de police, d’aucune extension supplémentaire et d’aucun accès réseau. Si tu n’as pas encore de projet configuré, suis d’abord le premier tutoriel, puis reviens ici.

Étape 1 : Mettre en forme le texte sur une page A4

Chaque page a une taille et une orientation. A4 est le format de papier international courant, et Letter en est l’équivalent américain. L’orientation est soit portrait (à la verticale), soit paysage (à l’horizontale). Tu passes les deux choix à addPage() quand tu démarres une page.

Trois méthodes se chargent ensuite de l’écriture. setFont() choisit la police et la taille du texte qui suit. cell() écrit une ligne à l’intérieur d’une boîte invisible. multiCell() répartit un texte plus long sur autant de lignes que nécessaire. Dans les deux méthodes, une largeur de 0 signifie « utiliser tout l’espace jusqu’à la marge droite ».

Deux autres appels gèrent l’apparence. setTextColor() prend des valeurs de rouge, de vert et de bleu de 0 à 255, et elle s’applique jusqu’à ce que tu la changes de nouveau. L’énumération Alignment, une liste fixe de choix nommés, propose Left, Center, Right et Justify.

Crée 01-text-basics.php dans le dossier de ton projet :

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

Exécute-le avec php 01-text-basics.php. Le script affiche Wrote out/text-basics.pdf, et le fichier apparaît dans le nouveau dossier out/.

Ce qui vient de se passer

addPage(PageSize::A4(), Orientation::Portrait) a créé la page avant que le moindre texte ne soit écrit. Passe plutôt Orientation::Landscape, et la même page bascule à l’horizontale. D’autres tailles nommées, comme PageSize::A5() ou PageSize::Letter(), fonctionnent de la même façon.

setFont('helvetica', 'B', 20) a sélectionné Helvetica en gras à 20 points. Le point (pt) est l’unité traditionnelle de l’imprimerie ; 72 points valent un pouce. Le titre est bleu parce que setTextColor(30, 64, 175) était actif quand l’appel à cell() l’a écrit. Le setTextColor(0, 0, 0) suivant est revenu au noir pour tout ce qui vient après.

Les deux appels à multiCell() ont mis leurs paragraphes à la ligne automatiquement. Celui qui est justifié étire l’espacement entre les mots pour que les deux bords s’alignent, sauf sur la dernière ligne du paragraphe. Entre les blocs, ln() a déplacé la position d’écriture vers le bas pour aérer la page. Enfin, save() a construit le fichier et l’a écrit dans out/.

Pour tous les paramètres que ces méthodes acceptent, consulte Composer du texte avec des polices et de l’alignement.

Étape 2 : Choisir parmi les polices intégrées

Le moteur intègre trois familles de texte : Helvetica, Times et Courier. Helvetica est une police sans empattement, c’est-à-dire que ses lettres n’ont pas de petites terminaisons (empattements). Times est une police à empattements qui se lit bien dans les longs passages proches de l’imprimé. Courier a une chasse fixe, elle convient donc aux listings de code et aux reçus. Comme ces familles sont intégrées, tes scripts n’ont besoin d’aucun fichier de police.

L’argument de style de setFont() combine des indicateurs d’une seule lettre : 'B' pour le gras, 'I' pour l’italique et 'U' pour le soulignement. Une chaîne vide signifie normal, et les indicateurs se combinent, donc 'BI' donne du gras italique.

Les familles intégrées couvrent le texte fondé sur l’alphabet latin. Pour d’autres systèmes d’écriture ou ta propre police de marque, tu enregistres un fichier de police, comme le montre la recette Intégrer et sous-ensembler des polices (le sous-ensemblage ne conserve que les caractères que tu as réellement utilisés, ce qui limite la taille des fichiers). La matrice de prise en charge des polices liste tous les formats de police que le moteur accepte.

Crée 02-fonts.php à côté du premier 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";

Exécute-le avec php 02-fonts.php et ouvre out/font-sampler.pdf. Tu vois la même phrase d’exemple changer d’aspect entre les deux familles et grandir au fil de trois tailles.

Ce qui vient de se passer

addPage() sans argument a utilisé la configuration de page par défaut en orientation portrait, de sorte que chaque script n’a pas à détailler la taille. Chaque appel à setFont() a changé la famille, le style ou la taille active en cours de page, et une police reste active jusqu’au prochain appel à setFont().

Les boucles convertissent la taille avec (float) parce que setFont() attend un nombre décimal. Les hauteurs de ligne évoluent avec la taille de la police ($size * 0.8), donc plus le texte est grand, plus les lignes sont hautes, et rien ne se chevauche. Essaie de remplacer 'times' par 'courier' et de relancer le script pour voir la troisième famille.

Si quelque chose a mal tourné

• Une erreur « class not found » ou d’autoload signifie généralement que le script n’a pas trouvé vendor/autoload.php. Exécute-le dans le dossier du projet qui contient vendor/.
• Un nom de famille mal orthographié lève une exception qui nomme la police introuvable. Vérifie l’orthographe : helvetica, times, courier.
• La base de connaissances de dépannage rassemble les correctifs courants, et Polices et balisage traite les problèmes de police en profondeur.
• Chaque exception du moteur est documentée dans la référence des erreurs, avec le contexte qu’elle transporte et l’action de récupération.

La suite

Tu sais maintenant façonner des pages, mettre en forme le texte et choisir des polices avec intention. Dans le tutoriel suivant, tu places des images sur la page et tu organises le contenu avec des tableaux et des listes.