Référence de l'API Laravel

En bref

Le paquet nextpdf/laravel branche le cœur NextPDF, indépendant du framework, sur une application Laravel. Il expose quatre éléments que tu appelles directement : la façade Pdf pour une génération rapide, la liaison de conteneur PdfDocumentInterface pour créer des documents par injection, l’aide PdfResponse, qui transforme un document terminé en réponse HTTP, et la tâche de file d’attente GeneratePdfJob pour la génération hors requête. Le NextPdfServiceProvider enregistre chaque liaison et est découvert automatiquement ; aucune configuration manuelle n’est donc nécessaire. La configuration dans config/nextpdf.php pilote les valeurs par défaut, les polices, la mise en file d’attente ainsi que les fonctionnalités optionnelles de signature et TSA.

Commence ici : pour renvoyer un PDF directement depuis un contrôleur, construis un document, puis retourne PdfResponse::download($document, 'file.pdf'), comme dans le premier exemple ci-dessous.

Tâches courantes

Les extraits ci-dessous couvrent les trois flux que tu utiliseras en premier. Chacun a été vérifié avec le code source du paquet ; les tableaux exhaustifs par symbole viennent ensuite.

Renvoyer un PDF téléchargeable depuis un contrôleur, la tâche la plus courante :

<?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(PdfDocumentInterface $document): Response
    {
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

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

Ce que fait cet exemple : il injecte un document neuf, écrit une ligne et retourne une réponse attachment avec Content-Type: application/pdf et les en-têtes de sécurité OWASP. Remplace download() par inline() pour l’afficher dans le navigateur à la place.

Compose et enregistre avec la façade Pdf, le chemin le plus court pour les scripts et les flux courts :

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

Ce que fait cet exemple : la façade récupère un document neuf depuis le conteneur, écrit une cellule et enregistre le PDF terminé sur le disque.

Génère un PDF en dehors du thread de requête avec GeneratePdfJob :

<?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),
);

Ce que fait cet exemple : il met la génération en file d’attente sur un worker. La closure de construction reçoit un document résolu depuis le conteneur, puis le retourne. La tâche valide le chemin de sortie .pdf avant l’enregistrement. Le nom de la file d’attente, le délai d’expiration et la connexion proviennent de config('nextpdf.queue.*').

Façade

La façade Pdf sert de proxy statique vers un nouveau Document du cœur ; utilise-la dans les flux courts de contrôleur où le style statique reste lisible. Chaque ligne correspond à une méthode de document relayée par proxy.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`NextPDF\Laravel\Facades\Pdf`	aucun ; l’accesseur de façade statique récupère `NextPDF\Contracts\PdfDocumentInterface`	Laravel récupère la liaison courante du conteneur pour l’interface de document.	L’API fluide du document du cœur sous-jacent.	Échec de la liaison de conteneur Laravel si le fournisseur n’est pas enregistré.	Utilise-la pour les flux courts de contrôleur. Préfère l’injection par constructeur pour les services et les tâches.
`Pdf::setTitle(string $title)`	`title` : titre du document.	Remplace tout titre précédent.	`static`	Erreurs de validation du cœur ou d’écriture.	Relayé par proxy vers le `Document` du cœur.
`Pdf::setAuthor(string $author)`	`author` : métadonnée d’auteur du document.	Remplace tout auteur précédent.	`static`	Erreurs de validation des métadonnées du cœur.	Préfère les valeurs par défaut configurées pour les métadonnées à l’échelle de l’application.
`Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)`	`size` : taille de page optionnelle ; `orientation` : `Portrait` par défaut.	Utilise la taille de page configurée ou par défaut lorsque `size` est omis.	`static`	Erreurs de validation de page du cœur.	Utilise un `PageSize` explicite lorsque la taille de sortie est importante.
`Pdf::setFont(string $family, string $style = '', float $size = 12.0)`	Famille de police, style et taille en points.	Style vide et taille de 12 pt.	`static`	Erreurs de registre de polices ou d’encodage.	Précharge les polices de production via `nextpdf.preload_fonts` lorsque la latence est importante.
`Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)`	Boîte de cellule, texte, indicateur de bordure, indicateur de saut de ligne, alignement.	Texte vide, pas de bordure, pas de saut de ligne, alignement à gauche.	`static`	Erreurs de mise en page ou d’encodage de texte.	À utiliser pour une sortie simple à mise en page fixe.
`Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)`	Largeur de cellule, hauteur de ligne, texte, indicateur de bordure, alignement.	Pas de bordure et alignement à gauche.	`static`	Erreurs de mise en page ou d’encodage de texte.	À utiliser lorsque le texte doit passer à la ligne dans une largeur fixe.
`Pdf::writeHtml(string $html)`	`html` : fragment HTML.	Effectue le rendu dans la page courante et en crée une si nécessaire.	`static`	Erreurs de rendu HTML du cœur.	Applique les politiques de taille d’entrée et de ressources avant d’accepter du HTML non fiable.
`Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)`	Chemin de fichier et rectangle de placement optionnel.	Laisse le document du cœur choisir la position courante et la taille intrinsèque lorsque les coordonnées sont omises.	`static`	Erreurs de décodage d’image, de chemin ou de mise en page.	Valide la politique de source d’image avant d’accepter des chemins fournis par l’utilisateur.
`Pdf::output(?string $filename = null, OutputDestination $dest = Inline)`	`filename` : nom optionnel ; `dest` : destination de sortie.	Sortie inline lorsque la destination est omise.	`string`	Erreurs de sérialisation du cœur.	Préfère `PdfResponse` pour les réponses HTTP Laravel.
`Pdf::save(string $path)`	`path` : cible du système de fichiers.	Écrit le PDF terminé sur le disque.	`void`	Erreurs du système de fichiers ou d’écriture du cœur.	Valide les répertoires de sortie dans le code de l’application.
`Pdf::getPdfData()`	aucun.	Matérialise le PDF en mémoire.	`string`	Erreurs de sérialisation du cœur.	À utiliser lorsqu’un autre objet du framework doit posséder le corps de la réponse.

Fournisseur de services et liaisons

Consulte ce tableau lorsque tu dois récupérer ou redéfinir directement une entrée du conteneur, par exemple pour injecter DocumentFactoryInterface dans un service ou vérifier quels services provides() déclare comme différés.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`NextPdfServiceProvider::register()`	aucun.	Fusionne la configuration `config/nextpdf.php`, puis enregistre les registres, la fabrique de document, la liaison de document, le client HTTP, le client TSA, le signataire et les contrats de facture électronique optionnels.	`void`	Erreurs de conteneur ou de résolution de classe optionnelle lorsqu’une fonctionnalité est utilisée.	`FontRegistryInterface` et `ImageRegistry` sont partagés ; les documents sont toujours neufs.
`NextPdfServiceProvider::boot()`	aucun.	Valide les extensions PHP requises et publie `nextpdf-config` en mode console.	`void`	`RuntimeException` si une extension requise n’est pas disponible.	Les extensions requises sont `mbstring` et `zlib`.
`NextPdfServiceProvider::provides()`	aucun.	Déclare les identifiants de services différés.	`array<string>`	aucune attendue.	Inclut `PdfDocumentInterface`, `DocumentFactoryInterface`, `FontRegistryInterface`, `SignerInterface`, `TsaClient`, `ClientInterface` et `nextpdf`.
`PdfDocumentInterface` / `nextpdf`	résolu depuis le conteneur Laravel.	Crée un `Document` jetable à partir de `DocumentFactoryInterface`, puis applique les valeurs par défaut configurées et les réglages PDF/A ou Artisan optionnels.	`NextPDF\Core\Document`	Erreurs d’extension optionnelle lorsqu’elle est configurée mais indisponible.	Récupère un nouveau document pour chaque requête ou tâche.
`DocumentFactoryInterface`	résolu depuis le conteneur Laravel.	Fabrique singleton qui partage les registres de polices et d’images pendant toute la durée de vie du processus.	`DocumentFactoryInterface`	Erreurs de configuration du registre.	À utiliser pour une injection de dépendances explicite.
`SignerInterface`	résolu depuis le conteneur Laravel.	Retourne `null` sauf si `nextpdf.signature.enabled` et les chemins de certificat sont configurés.	`SignerInterface	null`	Erreurs de chargement de certificat ou de validation au niveau de la signature.

Configuration

Utilise ce tableau pour repérer les clés nextpdf.* exposées à l’exécution et lues par les liaisons ; la référence complète par clé, avec les variables d’environnement et les valeurs par défaut, se trouve à /integrations/laravel/configuration/.

Clé	Type	Comportement par défaut	Notes
`nextpdf.fonts_path`	`string`	Utilise les polices des ressources Laravel lorsqu’il est omis.	Répertoire des polices personnalisées et du préchauffage.
`nextpdf.cache_path`	`string`	Chemin du cache de l’application.	À maintenir accessible en écriture par le worker PHP.
`nextpdf.preload_fonts`	`list<string>`	Liste vide.	Préchauffées lors de la création du registre, puis le registre est verrouillé.
`nextpdf.image_cache_mb`	`int`	Taille de cache d’images bornée.	Limite la mémoire du cache d’images à durée de vie du processus.
`nextpdf.defaults.*`	`array`	Créateur `NextPDF`, langue `en`, auteur et valeurs par défaut de mise en page optionnels.	Appliquées à chaque document neuf.
`nextpdf.artisan.*`	`array`	Renderer Chrome désactivé sauf s’il est installé et configuré.	Correspond à `ChromeRendererConfig::fromArray()`.
`nextpdf.signature.*`	`array`	Signature désactivée par défaut.	Certificat, clé privée, mot de passe, certificats supplémentaires et niveau de signature.
`nextpdf.tsa.*`	`array`	TSA désactivé lorsque l’URL est vide.	Prend en charge les identifiants, les fichiers mTLS, le délai d’expiration, les épinglages de clé publique et la politique HTTP.
`nextpdf.ocsp_cache.*`	`array`	Cache OCSP activé avec le TTL configuré.	Utilisé par les flux de validation de signature lorsqu’il est disponible.

Réponses HTTP

Utilise ce tableau lorsque tu renvoies un document terminé via HTTP et que tu dois choisir entre l’affichage inline, le téléchargement en pièce jointe ou la sortie en flux.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document` : document construit ; `filename` : nom de fichier Content-Disposition.	Les noms de fichiers vides sont normalisés en `document.pdf`.	`Illuminate\Http\Response`	Erreurs de sérialisation du cœur ou de construction de la réponse.	Définit le type de contenu PDF et les en-têtes défensifs.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Identique à `inline` ; la disposition est attachment.	Réponse de téléchargement du navigateur.	`Illuminate\Http\Response`	Identique à `inline`.	À utiliser pour les téléchargements de fichiers explicites.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Identique à `inline`.	Matérialise les octets du PDF, puis émet des fragments de 64 Ko.	`Symfony\Component\HttpFoundation\StreamedResponse`	Identique à `inline`.	Il s’agit d’une sortie HTTP en flux, pas d’un rendu sans copie.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Identique à `streamInline` ; la disposition est attachment.	Réponse de téléchargement en flux.	`StreamedResponse`	Identique à `streamInline`.	Applique les limites de taille d’entrée et de sortie avant le rendu.

Tâche de file d’attente

Utilise ce tableau lorsque tu déplaces la génération hors du thread de requête ; il couvre la construction, l’envoi et l’attachement de callbacks de succès ou d’échec à GeneratePdfJob.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)`	`outputPath` : cible `.pdf` ; `builder` : reçoit un `PdfDocumentInterface` ; les callbacks sont optionnels.	Le nom de la file d’attente, le délai d’expiration et la connexion sont lus depuis `config('nextpdf.queue.*')`.	Instance de la tâche.	Erreurs de sérialisation si le builder ou les callbacks ne sont pas sérialisables.	Le builder doit retourner le document configuré.
`GeneratePdfJob::handle()`	aucun.	Résout `PdfDocumentInterface`, applique le builder, valide le chemin de sortie, puis enregistre.	`void`	`InvalidArgumentException` pour les chemins de sortie non sûrs ; erreurs d’écriture du cœur.	Rejette les wrappers de flux, les octets nuls, les segments `..` et les chemins non-`.pdf`.
`GeneratePdfJob::failed(Throwable $exception)`	`exception` : cause de l’échec.	Appelle le callback d’échec configuré lorsqu’il est présent.	`void`	Échecs de callback.	Garde les callbacks idempotents.
`GeneratePdfJob::then(callable $callback)`	`callback` : reçoit le chemin de sortie.	Remplace le callback de succès.	`self`	Erreurs liées à la sérialisation de la closure.	Méthode fluide pour configurer l’envoi.
`GeneratePdfJob::catch(callable $callback)`	`callback` : reçoit le `Throwable` levé.	Remplace le callback d’échec.	`self`	Erreurs liées à la sérialisation de la closure.	À utiliser pour l’alerte ou le nettoyage compensatoire.

Notes de développement

PdfResponse appelle toujours getPdfData() avant la construction de la réponse. Ce n’est pas un constructeur de document paresseux.
Les charges utiles de file d’attente peuvent être falsifiées sur des transports partagés ; garde les chemins de sortie confinés à un répertoire appartenant à l’application.
Utilise un document neuf par requête ou par tâche. Ne réutilise pas un document entre plusieurs requêtes.