HTML vers PDF, la voie simple

Jusqu’ici dans ce parcours, tu as construit tes pages appel après appel. Beaucoup de documents sont plus rapides à décrire sous forme de balisage, le format texte à base de balises utilisé pour les pages web. Dans ce tutoriel, tu confies à NextPDF du langage de balisage hypertexte (HTML), et le moteur dessine la page pour toi.

Ce que tu vas construire

Un rapport d’une page rendu à partir d’une seule chaîne HTML. Il comporte un titre coloré, un court paragraphe et un tableau avec une ligne de totaux. Tu le stylises avec les feuilles de style en cascade (CSS), le langage de règles qui contrôle l’apparence du balisage. Dans les tutoriels précédents, tu as utilisé l’interface de programmation applicative (API) fluide, les appels de méthode chaînés. Ici, tu décris plutôt la mise en page sous forme de balisage, et le même moteur la rend.

Étape 1 : Rendre un rapport mis en forme à partir de HTML

Crée un fichier nommé 01-html.php dans le dossier de ton projet, à côté de vendor. Colle-y ce script complet :

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Monthly reading report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Monthly reading report</h1>

<p>This report was rendered from <strong>HTML</strong> with inline
<em>CSS</em>. The table below lists two books and their page counts.</p>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 55%;">Title</th>
            <th style="width: 20%; text-align: center;">Format</th>
            <th style="width: 25%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Trail</td>
            <td style="text-align: center;">Hardcover</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Bytes</td>
            <td style="text-align: center;">Paperback</td>
            <td style="text-align: right;">248</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="font-weight: bold;">
            <td colspan="2" style="text-align: right;">Total pages:</td>
            <td style="text-align: right;">560</td>
        </tr>
    </tfoot>
</table>
HTML;

$document->writeHtml($html);

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

echo "Wrote out/reading-report.pdf\n";

Exécute le script depuis le dossier du projet :

php 01-html.php

Tu devrais voir une seule ligne en sortie :

Wrote out/reading-report.pdf

Ouvre out/reading-report.pdf dans n’importe quel lecteur de format de document portable (PDF). Le titre est bleu foncé, et la ligne d’en-tête du tableau est remplie de la même couleur.

Ce qui vient de se passer

@mkdir(__DIR__ . '/out'); crée le dossier de sortie. Le signe @ masque l’avertissement lorsque le dossier existe déjà, pour que les exécutions répétées restent silencieuses.
Document::createStandalone(), setTitle() et addPage() fonctionnent exactement comme dans les tutoriels précédents. Passer au balisage ne change rien à la configuration du document.
writeHtml() lit ta chaîne une seule fois, de haut en bas, et dessine chaque élément à la position courante. Les titres et les paragraphes deviennent du texte mis en forme. Le tableau devient des lignes mesurées de cellules bordées.
Les attributs style en ligne contiennent le CSS. Le moteur comprend les propriétés courantes telles que color, background-color, text-align et width.
Aucun navigateur ni logiciel supplémentaire n’entre en jeu. Le pipeline est du PHP pur à l’intérieur du moteur, donc le script s’exécute partout où fonctionne ton installation Composer.

Le moteur prend en charge un sous-ensemble pratique de HTML et de CSS, pas tout ce qu’un navigateur accepte. Tout ce qui se trouve hors de ce sous-ensemble est ignoré silencieusement plutôt que de déclencher une erreur. La matrice de prise en charge CSS consigne exactement ce qui est couvert. Pour un parcours plus approfondi de ce pipeline, consulte Rendre du HTML dans une page PDF.

Quand utiliser HTML et quand utiliser l’API fluide

Les deux voies s’appuient sur le même moteur, choisis donc celle qui convient au document.

Choisis writeHtml() quand le document se lit comme une page web : des titres, des paragraphes, des listes et des tableaux. Le balisage est plus rapide à écrire et plus facile à modifier pour tes coéquipiers.
Choisis l’API fluide quand tu as besoin d’un placement exact, comme des positions fixes ou des cellules mesurées avec précision. Le balisage te donne le flux ; les appels fluides te donnent le contrôle.
Vérifie la matrice de prise en charge CSS avant de compter sur une propriété. Quand un style n’est pas couvert, construis plutôt cette partie avec des appels fluides.

La limite de sécurité

En conditions réelles, le HTML provient souvent de l’extérieur de ton code, par exemple d’un formulaire ou d’une base de données. Traite-le comme une entrée non fiable, et valide-le ou nettoie-le avant le rendu. Par défaut, le pipeline intégré n’exécute aucun script et ne récupère aucune ressource distante. Ce comportement par défaut garde le moteur de rendu prudent même quand le balisage ne l’est pas. Si tu as besoin d’options de rendu de qualité navigateur, consulte Choisis ta voie.

En cas de problème

Failed to open stream: No such file or directory signifie généralement que le script ne trouve pas vendor/autoload.php. Exécute-le depuis le dossier où tu as lancé Composer.
Un style manquant est généralement une propriété hors du sous-ensemble pris en charge. Le moteur ignore ce qu’il ne prend pas en charge plutôt que d’échouer. Compare ton balisage à la matrice de prise en charge CSS.
Une exception pendant le rendu indique le problème exact. Recherche-la dans la référence erreurs de rendu et d’entrée/sortie.

Pour tout le reste, commence par le guide de dépannage.

Et ensuite

Tu sais maintenant construire des documents appel par appel et à partir de balisage. Termine le parcours avec Où aller ensuite. Il cartographie le livre de recettes, la référence et les guides que tu utiliseras après ce parcours.