Installer NextPDF et générer ton premier PDF

NextPDF est une bibliothèque PHP qui crée des fichiers PDF (Portable Document Format). Dans ce tutoriel, tu l’installes dans un dossier vide et tu rends ton premier document d’une seule page. Il te faut un terminal et une dizaine de minutes.

Ce que tu vas construire

Tu vas construire un tout petit projet qui contient un seul script, 01-hello.php. Le script rend une seule page avec une ligne de titre en gras et un paragraphe. Il enregistre le résultat dans out/hello.pdf. Au passage, tu apprends deux commandes qui confirment que ton installation est saine.

Cette page enseigne une seule voie d’installation : un dossier vide et le paquet du moteur. D’autres voies existent, comme les adaptateurs de frameworks, les moteurs de rendu basés sur le navigateur et le client Python. Elles se trouvent dans Installation et Choisir ta voie. Tu n’en as pas besoin aujourd’hui.

Étape 1 : Créer un projet et installer NextPDF

Composer est le gestionnaire de paquets de PHP. Il télécharge des bibliothèques dans ton projet et génère un autoloader. Un autoloader est un petit fichier PHP qui trouve pour toi les classes des bibliothèques, si bien que tu n’écris jamais de longues listes d’includes.

Ouvre un terminal et exécute ces trois commandes :

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

Composer affiche sa progression pendant qu’il résout et télécharge les paquets. Les lignes exactes varient selon ta version de Composer et ton cache local. Une installation réussie se termine sans message d’erreur et ressemble à peu près à ceci :

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

Ce qui vient de se passer

Composer a créé trois choses dans ton dossier. composer.json indique que ton projet dépend du moteur. composer.lock fige la version exacte qu’il a installée, de sorte qu’une installation ultérieure résout le même code. Le dossier vendor/ contient les paquets téléchargés, y compris vendor/autoload.php. Ton script charge ce seul fichier, et toutes les classes du moteur deviennent disponibles.

Composer a aussi vérifié ta configuration PHP pendant l’installation. Le moteur déclare les extensions PHP dont il a besoin. Les extensions sont des modules optionnels intégrés à PHP. Si l’une d’elles manque, Composer s’arrête et la nomme au lieu de te laisser avec une installation cassée.

Étape 2 : Générer ton premier PDF

Crée un fichier nommé 01-hello.php à côté de composer.json. Colles-y ce programme complet :

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

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

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

Exécute-le :

php 01-hello.php

Tu devrais voir exactement une ligne :

Wrote out/hello.pdf

Ouvre out/hello.pdf dans n’importe quel lecteur de PDF. Tu verras la ligne de titre en gras avec le paragraphe en dessous, et la plupart des lecteurs affichent « Hello from NextPDF » dans le titre de leur fenêtre.

Ce qui vient de se passer

Parcours le script de haut en bas :

• require charge l’autoloader de Composer, si bien que la classe Document est résolue.
• @mkdir crée le dossier out/. Le @ en tête garde le script silencieux lorsque le dossier existe déjà, ce qui te permet de le relancer.
• Document::createStandalone() renvoie un document neuf. Il est conçu pour de courts scripts en ligne de commande exactement comme celui-ci.
• setTitle() définit le titre du document, que les lecteurs affichent dans le titre de la fenêtre.
• addPage() ajoute une page vide et place le curseur en haut à gauche.
• setFont() choisit une famille de police, un style et une taille en points. Le point est l’unité standard des tailles de police à l’impression. 'B' signifie gras, et '' signifie normal. La famille nommée helvetica est intégrée, donc tu n’as besoin d’aucun fichier de police.
• cell() écrit une ligne de texte à l’emplacement du curseur. Une largeur de 0 signifie « s’étirer jusqu’à la marge de droite ». newLine: true déplace ensuite le curseur vers le bas, comme si tu appuyais sur Entrée.
• save() construit le PDF final et l’écrit sur le disque.

Un document produit un fichier. Quand tu as besoin d’un deuxième PDF, crée un nouveau document plutôt que de réutiliser l’ancien.

Étape 3 : Vérifier ton installation

Deux vérifications rapides confirment que cette installation continuera de fonctionner au-delà d’un seul script.

D’abord, liste les extensions dont dispose ton PHP :

php -m

Cherche dans la liste curl, gd, intl, mbstring, openssl et zlib. Le moteur s’appuie sur ces six-là. Composer les a déjà vérifiées à l’étape 1, elles devraient donc toutes apparaître.

Ensuite, exécute le bilan de santé du moteur :

vendor/bin/nextpdf doctor

Sous Windows, appelle plutôt vendor\bin\nextpdf doctor. La commande inspecte ta version de PHP, tes extensions, ton dossier temporaire et ta configuration. Chaque vérification affiche [OK], [WARN] ou [FAIL], suivi d’un verdict global unique.

Ce qui vient de se passer

Lis d’abord le bloc Extensions. Six lignes [OK] nommant curl, gd, intl, mbstring, openssl et zlib signifient que ton installation est prête pour tous les tutoriels qui suivent.

Le rapport liste aussi les capacités du moteur. Sur l’installation Core gratuite, les capacités qui appartiennent aux paquets commerciaux affichent [FAIL] avec un message nommant le paquet qui les fournit. C’est attendu ici, et cela peut faire passer le verdict global à UNHEALTHY alors même que ta configuration Core est correcte. Pour ces tutoriels, le bloc Extensions est le signal qui compte.

Si quelque chose n’a pas fonctionné

Compare d’abord ton symptôme à ces cas courants :

• composer: command not found signifie que Composer est absent ou n’est pas dans ton PATH. Installe-le depuis getcomposer.org, puis répète l’étape 1.
• Failed opening required '.../vendor/autoload.php' signifie que le script s’est exécuté en dehors du dossier du projet, ou que l’installation ne s’est pas terminée. Place-toi dans le dossier de l’étape 1 et exécute composer install.
• Si Composer s’arrête pendant l’étape 1 et nomme une extension PHP manquante, active cette extension dans ton php.ini. Confirme-le avec php -m, puis répète l’installation.
• Une ligne [FAIL] dans le bloc Extensions du doctor nomme une extension PHP manquante. Active-la dans php.ini, confirme avec php -m, puis relance le doctor. Les lignes [FAIL] de capacité qui nomment un paquet commercial sont attendues sur l’installation Core et ne nécessitent aucune action ici.

Pour tout le reste, commence par la base de connaissances de dépannage. Si un script lève une exception, cherche sa classe dans la référence des erreurs ; la plupart des erreurs de débutant apparaissent sous erreurs générales.

Et ensuite

Tu disposes d’une installation qui fonctionne et de ton premier fichier rendu. Continue avec Texte, polices et bases des pages pour maîtriser les tailles de page, les polices intégrées, les couleurs et l’alignement.