Images, tableaux et listes

Le texte seul suffit rarement à produire un document abouti. Dans ce tutoriel, tu ajoutes trois briques du quotidien : une image, un tableau et une liste à puces. Tu écris deux petits scripts, et chacun produit un vrai fichier PDF (Portable Document Format) que tu peux ouvrir immédiatement.

Ce que tu vas construire

01-image.php — un PDF d’une page avec un titre et une image carrée ambre, placée à un endroit précis de la page.
02-table-and-lists.php — un PDF d’une page avec un petit tableau de livres et une liste à puces en dessous.

Les deux scripts sont des programmes complets. Continue d’utiliser le dossier de projet du premier tutoriel et enregistre chaque script à côté de composer.json.

Étape 1 : Placer une image sur la page

Ce script transporte sa propre image. Une minuscule image PNG (Portable Network Graphics) de 8 x 8 pixels voyage à l’intérieur du script sous la forme d’une chaîne Base64. Base64 est une façon d’écrire des données binaires en texte brut, ce qui lui permet de tenir dans du code source. Dans un vrai projet, tu sauterais cette partie, car ton fichier image existe déjà sur le disque.

Enregistre ceci sous 01-image.php et exécute-le avec php 01-image.php :

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// A tiny 8 x 8 pixel amber PNG, stored as text inside this script.
// In a real project the image file already exists on disk, so you
// would skip this block and point image() at your own file.
$pngBase64 = 'iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAAEUlEQVR42mP4Oo8bK2IYWhIAq6BngWh/dt4AAAAASUVORK5CYII=';

@mkdir(__DIR__ . '/out');

$pngPath = __DIR__ . '/out/amber-square.png';
$pngBytes = base64_decode($pngBase64, true);
if ($pngBytes === false) {
    fwrite(STDERR, "The embedded image data is damaged.\n");
    exit(1);
}
file_put_contents($pngPath, $pngBytes);

$document = Document::createStandalone();
$document->setTitle('Tutorial: images');
$document->addPage();

$document->setFont('helvetica', 'B', 20);
$document->cell(0, 26, 'A picture inside a PDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 18, 'The amber square below comes from a tiny PNG file.', newLine: true);

// Place the image 72 points (one inch) from the left edge and
// 160 points down from the top, printed as a 96 x 96 point square.
$document->image($pngPath, x: 72, y: 160, width: 96, height: 96);

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

echo "Wrote out/image.pdf\n";

Tu devrais voir Wrote out/image.pdf à l’écran. Ouvre out/image.pdf et tu y trouveras le titre, une ligne de texte et un carré ambre.

Ce qui vient de se passer

Le script commence par décoder la chaîne Base64 pour retrouver les octets de l’image, puis les écrit dans out/amber-square.png. Ce n’est là que l’astuce qui rend le tutoriel autonome. La leçon commence à l’appel image(), qui lit de la même façon n’importe quel fichier PNG ou JPEG (Joint Photographic Experts Group) existant.
@mkdir(__DIR__ . '/out') crée le dossier de sortie. Le signe @ masque l’avertissement anodin que tu obtiendrais lorsque le dossier existe déjà, ce qui permet d’exécuter le script deux fois de suite.
image() prend un chemin de fichier, une position et une taille d’impression. Les positions et les tailles sont mesurées en points, et 72 points valent un pouce. L’origine de la page est le coin supérieur gauche, donc y: 160 signifie 160 points vers le bas depuis le haut.
Les pixels et les points sont deux choses différentes. L’image ne fait que 8 x 8 pixels, mais width: 96, height: 96 l’imprime en un carré d’un pouce et un tiers de côté. C’est toi qui choisis la taille d’impression ; le nombre de pixels, non.
image() place l’image à l’endroit exact que tu indiques. Elle ne déplace pas la position d’écriture qu’utilise cell(). Écrire le texte d’abord, puis placer les images, évite que les deux ne se chevauchent.
NextPDF lit l’image uniquement depuis un fichier local, jamais depuis une adresse web. Il vérifie que le fichier est une image réelle et prise en charge avant de l’intégrer. Cette protection te couvre lorsque les noms de fichiers proviennent des utilisateurs.

Étape 2 : Ajouter un tableau et une liste à puces

Les tableaux et les listes sont du contenu structuré. La façon la plus rapide de décrire une structure est le HTML (Hypertext Markup Language), le même balisage que celui des pages web. NextPDF affiche directement sur la page PDF un sous-ensemble pris en charge de HTML. Aucun navigateur n’intervient.

Enregistre ceci sous 02-table-and-lists.php et exécute-le avec php 02-table-and-lists.php :

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Tutorial: tables and lists');
$document->addPage();

$document->setFont('helvetica', 'B', 20);
$document->cell(0, 26, 'A reading list, two ways', newLine: true);
$document->ln(8);

$html = <<<'HTML'
<h2>The books as a table</h2>
<table border="1" cellpadding="6" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 50%;">Title</th>
            <th style="width: 20%; text-align: center;">Year</th>
            <th style="width: 30%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Office</td>
            <td style="text-align: center;">2019</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Pixels</td>
            <td style="text-align: center;">2023</td>
            <td style="text-align: right;">208</td>
        </tr>
    </tbody>
</table>

<h2>Why these two books</h2>
<ul>
    <li>Short chapters that fit into a lunch break</li>
    <li>Worked examples on every page</li>
    <li>No jargon without an explanation</li>
</ul>
HTML;

$document->writeHtml($html);

$document->save(__DIR__ . '/out/table-and-lists.pdf');

echo "Wrote out/table-and-lists.pdf\n";

Tu devrais voir Wrote out/table-and-lists.pdf. Le PDF contient un titre, un tableau à trois colonnes avec une ligne d’en-tête sombre, et une liste à puces.

Ce qui vient de se passer

Le script mélange les deux styles d’écriture sur une même page. cell() imprime le grand titre à la position d’écriture courante. writeHtml() fait ensuite couler le tableau et la liste plus bas sur la page, sous le titre.
ln(8) ajoute un petit espace vertical, de huit points de haut, entre le titre et le contenu HTML. Sans lui, les deux seraient collés l’un à l’autre.
Le tableau utilise du balisage de tableau ordinaire : <thead> pour la ligne d’en-tête, <tbody> pour les lignes de données, <th> pour les cellules d’en-tête et <td> pour les cellules de données. border="1" trace les lignes de la grille, et cellpadding="6" ajoute de l’espace à l’intérieur de chaque cellule.
Les largeurs de colonnes sont des pourcentages, comme width: 50%. Elles se répartissent la largeur totale du tableau, si bien que la mise en page survit à un changement de format de page. La recette Mettre en page un tableau HTML traite en profondeur des en-têtes, des pieds de page et du dimensionnement des colonnes.
Les attributs style utilisent des déclarations CSS (Cascading Style Sheets), le langage de mise en forme du web. Les couleurs, l’alignement et les largeurs fonctionnent comme illustré ici. Avant de compter sur d’autres propriétés, consulte la matrice de prise en charge CSS.
La liste à puces n’est qu’un <ul> avec un <li> par élément. NextPDF dessine les puces et l’indentation pour toi.

En cas de problème

Une erreur mentionnant ImageProcessingException signifie que le fichier image n’a pas pu être lu ou décodé. Vérifie le chemin, et vérifie que le fichier est dans un format pris en charge tel que PNG ou JPEG.
Une erreur mentionnant PageLayoutException signifie qu’une position ou une taille a été rejetée. La largeur et la hauteur doivent être supérieures à zéro, et le chemin doit pointer vers un fichier local, pas vers une adresse web.
Les deux erreurs sont décrites dans la référence des erreurs du moteur.
Si le tableau s’affiche bizarrement, vérifie d’abord le balisage. Chaque ligne <tr> et chaque cellule <td> a besoin de sa balise fermante.
Pour tout le reste, commence par le guide de dépannage.

Et ensuite

Tes pages peuvent désormais porter des images, des tableaux et des listes. Dans le tutoriel suivant tu laisses un document dépasser une seule page tout en le gardant net grâce aux en-têtes, aux pieds de page et aux numéros de page. Pour approfondir les sujets d’aujourd’hui, la recette Intégrer des images dans un document traite des formats d’image et des règles de dimensionnement.

Images, tableaux et listes

Ce que tu vas construire

Étape 1 : Placer une image sur la page

Ce qui vient de se passer

Étape 2 : Ajouter un tableau et une liste à puces

Why these two books

Ce qui vient de se passer

En cas de problème

Et ensuite

Étape 1 : Placer une image sur la page

Étape 2 : Ajouter un tableau et une liste à puces