Comment ne plus galérer avec la génération de PDF dans Laravel

Générer des documents PDF sur le web a toujours été un vrai défi. Pensez au nombre de fois où vous avez essayé de mettre en page la facture ou le rapport parfait, pour découvrir que les polices avaient changé, que les tableaux étaient désalignés, ou que les images avaient disparu. D'habitude, le choix se résume à des utilitaires système complexes comme wkhtmltopdf, qui nécessitent une configuration serveur, et des services cloud payants.

Si vous travaillez avec la stack Laravel, il existe une solution éprouvée — le package laravel-dompdf de Barry van den Heuvel. C'est un wrapper autour de la bibliothèque Dompdf qui prend votre template Blade familier et le convertit en fichier PDF. Aucune dépendance serveur supplémentaire, juste PHP.

Ce qu'il y a sous le capot

Le projet fait essentiellement une chose : il connecte la puissance de Laravel avec le moteur Dompdf. La principale fonctionnalité est que vous n'avez pas besoin d'apprendre une nouvelle syntaxe pour la mise en page des documents. Vous créez une View classique, vous lui passez des données, et le package gère le rendu.

Curieusement, le package supporte non seulement Laravel standard mais aussi Lumen. C'est utile si vous extrayez la génération de documents dans un microservice séparé.

Comment ça marche en pratique

L'installation se fait de manière standard via Composer :

composer require barryvdh/laravel-dompdf

Après cela, vous avez accès à la façade Pdf. L'exemple le plus simple pour créer un fichier ressemble à ceci :

use Barryvdh\DomPDF\Facade\Pdf;

$pdf = Pdf::loadView('emails.invoice', ['order' => $order]);
return $pdf->download('invoice.pdf');

La méthode loadView récupère votre fichier Blade, lui passe les variables, et génère un objet que vous pouvez immédiatement envoyer à l'utilisateur pour téléchargement ou simplement afficher dans le navigateur via stream().

Configuration flexible des pages

Souvent, vous devez modifier l'orientation de la page ou le format du papier directement dans le code. Par exemple, l'orientation paysage fonctionne mieux pour les tableaux larges :

Pdf::loadHTML($html)
    ->setPaper('a4', 'landscape')
    ->setWarnings(false)
    ->save('report.pdf');

Au fait, si vous avez besoin de sauvegarder le fichier sur le disque au lieu de le servir à l'utilisateur, la méthode save() le fera en une seule action.

Support PDF/A-3b et factures électroniques

Les versions récentes (3.x) ont ajouté le support de la norme PDF/A-3b. C'est critique pour l'archivage à long terme des documents. Mais il y a un hic : cette norme exige que toutes les polices soient intégrées dans le fichier. L'Helvetica ou Times standard ne fonctionneront pas — vous devrez utiliser quelque chose comme DejaVu Sans.

Pour ceux qui travaillent sur l'automatisation comptable, le package supporte maintenant les formats Zugferd et Factur-X. C'est quand un fichier XML avec les données de la facture est intégré directement dans le PDF. Ça ressemble à quelque chose comme ceci :

$pdf = Pdf::loadView('invoice', $data)->setPdfA();

// Добавляем метаданные для Factur-X
$pdf->setAdditionalXmpRdf($xmlMetadata);

// Прикрепляем сам XML
$pdf->addEmbeddedFile(
    storage_path('invoices/factur-x.xml'),
    'factur-x.xml',
    'Factur-X Invoice',
    'text/xml'
);

Quelques conseils de mise en page

Dompdf n'est pas un moteur de navigateur complet. Il gère bien le CSS 2.1 et certaines propriétés CSS 3, mais n'essayez pas d'utiliser Flexbox ou Grid là-bas. Les bonnes vieilles tables et les floats sont votre meilleur pari.

Deux choses qui vous feront gagner beaucoup de temps :

1. Toujours spécifier l'encodage dans votre template : <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>. Sans cela, le cyrillique se transformera en points d'interrogation.
2. Pour les sauts de page, utilisez la propriété CSS page-break-after: always. C'est la manière la plus fiable pour que l'imprimante commence une nouvelle feuille là où vous en avez besoin.

Est-ce que ça vaut le coup

laravel-dompdf est un vrai bourreau de travail. C'est parfait pour générer des documents de complexité simple à moyenne : factures, rapports de service, relevés simples.

Le principal avantage est la simplicité. Vous n'avez pas besoin d'installer Node.js, Puppeteer, ou de configurer des binaires serveur. Tout fonctionne out of the box sur un hébergement PHP standard.

Cependant, si vous avez besoin de rendre des graphiques JavaScript complexes ou que votre mise en page est très chargée en tricks CSS modernes, Dompdf pourrait peiner. Dans de tels cas, il vaut mieux regarder du côté des outils basés sur Chromium. Mais pour 90% des tâches d'un développeur backend, ce package est plus que suffisant.

Le projet est vivant et activement maintenu (plus de 7 000 étoiles sur GitHub) et est soutenu par l'un des contributeurs les plus connus de la communauté Laravel. Si vous ne l'avez pas encore essayé — c'est le moment de l'ajouter à vos favoris.