Composer du texte avec des polices et l'alignement

En bref

Cette recette place du texte et définit la famille de police, le style, la taille et l’alignement. Trois méthodes s’en chargent : setFont(), cell() et multiCell(). Le code reprend examples/04-text-and-fonts.php.

Installation

composer require nextpdf/core:^3

Cette contrainte installe le package nextpdf/core. L’exemple s’exécute avec PHP 8.4.

Vue d’ensemble conceptuelle

setFont($family, $style, $size) sélectionne la fonte active, c’est-à-dire la police utilisée par le prochain appel de texte. L’argument $style combine trois indicateurs : B (gras), I (italique) et U (soulignement). L’indicateur U correspond à une décoration de texte ; les autres sélectionnent la variante de police. Les familles Helvetica, Times et Courier correspondent aux 14 polices Type 1 standard citées dans ISO 32000-2. Un profil de conformité peut toutefois prendre le dessus et forcer l’incorporation d’une police de substitution.

cell() écrit une seule ligne à l’intérieur d’une boîte. multiCell() répartit le texte sur plusieurs lignes dans une colonne, selon la largeur et la hauteur de ligne indiquées. Le texte se situe dans l’espace texte, et la matrice de texte fait correspondre l’espace texte à l’espace utilisateur (ISO 32000-2). Tu travailles en unités utilisateur ; le moteur émet la matrice pour toi.

Définis l’alignement avec l’énumération Alignment : Left, Center, Right, Justify. Pour multiCell(), la justification répartit l’espace entre les mots sur toute la ligne.

Surface de l’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 — même trait.
Alignment — NextPDF\Contracts\Alignment (Left, Center, Right, Justify).

Le tableau PHPDoc complet est généré à partir du code source.

Exemple de code — Démarrage rapide

<?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');

Exemple de code — Production

Cet exemple est autonome et le harnais de test peut l’exécuter. Il reprend examples/04-text-and-fonts.php et montre des variantes de style, une plage de tailles, du texte justifié avec retour automatique à la ligne et les trois alignements.

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

Sortie STDOUT attendue :

Wrote compose-text-and-fonts.pdf

Cas limites et pièges

Une largeur de 0 désigne la largeur restante. Quand tu passes 0, cell(0, ...) et multiCell(0, ...) fixent la largeur à l’espace disponible jusqu’à la marge de droite. Pour une boîte à largeur fixe, passe une largeur explicite.
Ordre des caractères de la chaîne de style. 'BI' et 'IB' sélectionnent la même variante gras-italique, car l’analyseur ignore l’ordre des indicateurs. L’indicateur 'U' est un indicateur de décoration, pas une variante de police.
Couverture de glyphes des polices standard. Les 14 polices standard restituent l’intégralité du répertoire WinAnsiEncoding (Windows-1252). Cela couvre le latin accentué d’Europe occidentale, le signe euro et la ponctuation typographique courante — tirets demi-cadratin et cadratin, guillemets courbes, puce, points de suspension et signe « marque de commerce ». Pour les écritures hors de ce jeu, comme le chinois, le japonais, le coréen, l’arabe, l’hébreu, le grec, le cyrillique ou le thaï, enregistre et sélectionne une fonte TrueType. Voir Incorporer et sous-ensembler des polices.
Hauteur de ligne par rapport à la taille de police. La hauteur par ligne de multiCell() correspond à la taille de police multipliée par le rapport de hauteur de ligne par défaut du profil métrique. Une hauteur trop petite peut faire se chevaucher les lignes.
Justification sur la dernière ligne. Un multiCell() justifié n’étire pas la dernière ligne d’un paragraphe. Cela correspond à la composition typographique classique.

Performance

L’émission du texte est linéaire par rapport au nombre de glyphes, en O(n). Le budget est wall_ms: 1000, peak_mb: 64. Ce budget est inférieur à celui des recettes HTML, car il n’y a ni cascade ni arbre de mise en page. Les polices standard ne sont pas incorporées, ce qui maintient une sortie légère.

Notes de sécurité

Le contenu textuel est rendu, pas interprété. Valide la longueur des chaînes fournies par l’utilisateur afin de garder la taille de sortie bornée. Ce chemin de code n’exécute aucun script et ne récupère aucune ressource distante.

Conformité

Énoncé	Spécification	Article	reference_id
Les familles Helvetica, Times et Courier figurent parmi les 14 polices Type 1 standard.	ISO 32000-2	iso32000_2_sec9#x1.x29
Les familles standard-14 prennent en charge l’intégralité du jeu de caractères latin (WinAnsiEncoding, page de code Windows 1252).	ISO 32000-2	Annex D.2 (iso32000_2_annexes#x1.x17.p4)	eb9220f88dfadad27a0be2206b64e68d8ea301d6d46e08142d43859c05fac6e4
Les coordonnées de texte sont dans l’espace texte, mises en correspondance avec l’espace utilisateur par la matrice de texte.	ISO 32000-2	iso32000_2_sec8#x1.x10.p2

Cette recette montre comment NextPDF compose du texte avec les polices standard. Leur couverture de glyphes correspond à l’intégralité du répertoire WinAnsiEncoding (Windows-1252) — latin d’Europe occidentale et ponctuation typographique courante. Le texte d’autres écritures nécessite une fonte incorporée.

Contexte commercial

Sans objet.