NextPDF : démarrage rapide avec Laravel

En bref

Dans ce tutoriel, tu génères un PDF téléchargeable depuis un contrôleur. Tu déplaces ensuite le même traitement vers un job en file d’attente. Chaque extrait correspond à un comportement vérifié par la suite de tests du package.

Installation

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Vue d’ensemble conceptuelle

Trois points d’entrée couvrent presque tous les cas d’usage Laravel. La façade est le moyen le plus rapide de démarrer. PdfResponse transforme un document en réponse HTTP. Un job en file d’attente déplace la génération lourde hors du thread de la requête, afin que l’utilisateur n’ait pas à l’attendre. Ce tutoriel les parcourt à tour de rôle. Les versions adaptées à la production, avec gestion des erreurs, se trouvent sur /integrations/laravel/production-usage/.

Exemple de code — Démarrage rapide

1. Façade

À chaque appel, la façade résout un nouveau document depuis le conteneur. Le conteneur est le registre de services de Laravel. Cet extrait correspond au comportement vérifié par tests/Unit/Laravel/Facades/PdfTest.php.

<?php

declare(strict_types=1);

use NextPDF\Laravel\Facades\Pdf;

Pdf::addPage();
Pdf::cell(0, 10, 'Hello from Laravel', newLine: true);
Pdf::save(storage_path('app/hello.pdf'));

2. Réponse de téléchargement depuis un contrôleur

PdfResponse::download() renvoie une Illuminate\Http\Response avec l’en-tête Content-Type: application/pdf, une disposition attachment et les en-têtes de sécurité OWASP. tests/Unit/Laravel/Http/PdfResponseTest.php vérifie le code de statut, le type de contenu, le préfixe de la disposition et les en-têtes.

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

Pour afficher un aperçu en ligne dans le navigateur, remplace download() par inline(). Pour les documents volumineux, utilise streamInline() ou streamDownload(). Ces méthodes envoient le PDF par blocs déterministes de 64 Ko.

3. Génération en file d’attente

GeneratePdfJob construit et enregistre un PDF sur un worker de file d’attente. La closure de construction reçoit le document résolu par le conteneur et retourne le document configuré. tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php confirme que le job crée bien le fichier au chemin de sortie exact.

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    storage_path('app/reports/january-2026.pdf'),
    static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
        ->addPage()
        ->cell(0, 10, 'January report', newLine: true),
);

Le chemin de sortie doit se terminer par .pdf. Le job valide le chemin sur le worker avant d’écrire.

Exemple de code — Production

Les versions de production ajoutent une gestion explicite des erreurs, des callbacks de succès et d’échec sur le job, ainsi qu’une stratégie d’exception typée. Elles sont documentées en détail sur /integrations/laravel/production-usage/.

Cas limites et pièges

La façade renvoie une instance de document différente à chaque résolution. Ne mets pas en cache Pdf::getFacadeRoot() entre deux documents logiques différents.
Quand un nom de fichier vide est passé à n’importe quelle fabrique PdfResponse, la valeur par défaut est document.pdf. La suite de tests des réponses vérifie cette valeur par défaut.
Les noms de fichiers non-ASCII reçoivent automatiquement un paramètre RFC 5987 filename*=. Les noms ASCII n’en reçoivent pas.
GeneratePdfJob rejette la traversée de chemin, les wrappers de flux, les octets nuls et toute extension autre que .pdf. Il lève InvalidArgumentException sur le worker.

Performance

La génération d’un document d’une seule page reste largement dans le budget de temps par page défini dans le front-matter. Déplacer la génération vers GeneratePdfJob retire entièrement le temps de construction du PDF de la requête HTTP. La requête se termine une fois le job dispatché.

Notes de sécurité

PdfResponse applique un ensemble fixe d’en-têtes OWASP via ses fabriques. Elles assainissent aussi le nom du fichier téléchargé. Le job en file d’attente valide son chemin de sortie. La couverture détaillée des menaces se trouve sur /integrations/laravel/security-and-operations/.

Conformité

Aucun standard normatif ne régit ce tutoriel. Chaque extrait est vérifié par rapport au code source du package. Il est également vérifié par rapport au test correspondant sous tests/.

Contexte commercial

La sortie signée et PDF/A est disponible avec nextpdf/premium. Il s’agit d’une capacité Enterprise optionnelle. Le package Core documenté ici ne nécessite aucune modification de code pour l’adopter. Voir https://nextpdf.dev/get-license/?intent=laravel-signing.

Voir aussi

/integrations/laravel/install/ — installer et publier la config
/integrations/laravel/production-usage/ — contrôleur et job câblés via injection de dépendances, avec gestion des erreurs
/integrations/laravel/configuration/ — clés de config utilisées ici
/integrations/laravel/overview/ — architecture et durées de vie des bindings

NextPDF : démarrage rapide avec Laravel