Ton premier PDF

En bref

Dans ce tutoriel, tu génères deux fichiers PDF. Pour le premier fichier, tu écris du texte directement avec l’API fluide du core (Application Programming Interface). Pour le second, tu restitues un fragment HTML (HyperText Markup Language) et CSS (Cascading Style Sheets) sur une page. À la fin, tu disposes d’un script fonctionnel que tu peux adapter à un vrai document. Tu sais aussi où trouver les variantes pour les frameworks et la variante serveur.

Les deux approches s’appuient sur le même moteur. Ce que tu apprends ici se transpose donc à chaque distribution.

Le schéma ci-dessous montre les deux approches de création et les trois surfaces de déploiement qui les réutilisent.

From your code to a PDF file

Avant de commencer

Tu as besoin de deux choses : le moteur du core installé et un endroit où exécuter un script PHP.

1. Vérifie que PHP 8.4 est bien le runtime actif :

   php --version

2. Installe le moteur du core dans ton projet, s’il n’est pas déjà présent :

   composer require nextpdf/core

3. Crée un fichier de travail nommé first-pdf.php à la racine du projet.

Les 14 polices standard fonctionnent sans configuration

La police de corps par défaut correspond à l’une des 14 polices Type 1 standard nommées dans ISO 32000-2. Ton premier document n’a donc besoin d’aucun fichier de police. Tu pourras enregistrer et incorporer des polices personnalisées plus tard, dès qu’une maquette les réclame.

Générer un PDF depuis PHP

Commence par l’API fluide. Document::createStandalone() renvoie un document prêt à l’emploi. Tu ajoutes une page, définis une police, écris des cellules, puis tu enregistres le résultat. Chaque méthode d’écriture renvoie le document, si bien que les appels se lisent de haut en bas.

1. Mets ce code dans first-pdf.php. Le script déclare les types stricts, charge l’autoloader et construit un document d’une page :

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('My first NextPDF document');
   $document->addPage();
   
   $document->setFont('helvetica', 'B', 24);
   $document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
   
   $document->setFont('helvetica', '', 12);
   $document->cell(0, 10, 'This is the first PDF I generated with PHP.', newLine: true);
   
   $document->save(__DIR__ . '/first-pdf.pdf');
   
   echo "Wrote first-pdf.pdf\n";

2. Exécute le script :

   php first-pdf.php

3. Vérifie la sortie. Tu devrais voir cette ligne dans la sortie standard, ainsi qu’un nouveau fichier nommé first-pdf.pdf à côté du script :

   Wrote first-pdf.pdf

Tu viens de générer un fichier PDF 2.0 valide. Ouvre-le dans n’importe quelle visionneuse : tu verras le titre avec la ligne en dessous.

save ou output

save() écrit le document vers un chemin de fichier. Pour envoyer plutôt les octets vers un navigateur, appelle output(). Pour capturer les octets en mémoire, appelle getPdfData(). Un document est à usage unique : une fois que tu l’as écrit, crée une nouvelle instance pour le document suivant plutôt que de le réutiliser.

Restituer du HTML en PDF

Écrire des cellules te donne un contrôle précis. Pour la plupart des documents, cependant, il est plus rapide de les décrire en HTML et CSS. Le moteur du core inclut un pipeline HTML en pur PHP. Sa méthode writeHtml() restitue un fragment sur la page courante. Elle n’utilise aucun navigateur ni aucun service externe.

1. Crée un second fichier, html-pdf.php, qui restitue un fragment HTML :

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('HTML to PDF');
   $document->addPage();
   
   $html = <<<'HTML'
   <h1 style="color: #1E3A8A;">HTML rendering in NextPDF</h1>
   <p>NextPDF renders <strong>HTML content</strong> directly into PDF pages.</p>
   <ul>
       <li>Headings, paragraphs, and lists</li>
       <li>Inline <strong>bold</strong> and <em>italic</em></li>
       <li>Inline styles such as color and font-size</li>
   </ul>
   HTML;
   
   $document->writeHtml($html);
   
   $document->save(__DIR__ . '/html-pdf.pdf');
   
   echo "Wrote html-pdf.pdf\n";

2. Exécute-le :

   php html-pdf.php

3. Vérifie la ligne de sortie et le nouveau fichier :

   Wrote html-pdf.pdf

Traite l’entrée HTML comme non fiable

Quand le HTML provient d’un utilisateur, d’un formulaire ou de toute source externe, valide-le et assainis-le avant de le passer à writeHtml(). Le recipe Restituer du HTML dans une page PDF couvre toute la posture de sécurité et le modèle de diffusion.

Le moteur restitue le sous-ensemble de HTML et de CSS qu’il prend en charge. Avant de te fier à une propriété, vérifie-la dans la matrice de prise en charge CSS. Quand une mise en page exige une fidélité équivalente à celle d’un navigateur complet — par exemple flexbox, grid ou les polices web — installe le renderer Artisan et appelle writeHtmlChrome() à la place. Cette méthode garde le texte sélectionnable.

Depuis un contrôleur de framework

Ton application tourne peut-être déjà sur un framework ou en tant que serveur. Les deux mêmes appels se transposent dans ces environnements. Le moteur reste identique et seul le câblage change.

Laravel

La façade Pdf résout un nouveau document à chaque appel. PdfResponse transforme un document en réponse de téléchargement :

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

Consulte le guide de démarrage Laravel.

Symfony

Le bundle expose un service PdfFactory. Ajoute un type hint NextPDF\Symfony\Service\PdfFactory dans un contrôleur, construis un document de la même manière, puis renvoie-le en tant que réponse HTTP. Consulte le guide de démarrage Symfony.

Serveur (REST)

Avec NextPDF Server en cours d’exécution, tu envoies un POST contenant un tableau d’opérations ordonné ; le serveur renvoie les octets du PDF :

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

Avec une réponse 200, le corps contient le PDF. Consulte le guide de démarrage Connect.

Étapes suivantes

Tu viens de générer un PDF de trois façons. Voici où aller ensuite pour chacune d’elles.

Restituer du HTML dans une page PDF Le recipe HTML complet : les éléments pris en charge, le modèle de diffusion et la posture de sécurité.

Choisis ton parcours Choisis entre le core, un framework, le serveur, et le renderer HTML à utiliser.

Référence du moteur du core Chaque méthode, paramètre et valeur de retour de Document.

Cookbook Des recipes ciblées par tâche pour la mise en forme, les tableaux, la pagination, et plus encore.