(Guide pratique pour préparer, lancer et maîtriser la génération de PDF avec Dolibarr)
1. Introduction
Depuis plus de dix ans, Dolibarr ERP‑CRM s’impose comme une solution de gestion intégrée, simple à prendre en main et extensible grâce à un large catalogue de modules. L’une de ses forces majeures réside dans la génération native de PDF à destination des factures, devis, commandes, bons de livraison, etc.
Dans ce guide, nous présentons :
- les mécanismes de création de PDF dans Dolibarr,
- les bonnes pratiques à adopter dès le premier jour de mise en production,
- un plan d’action en 30 jours pour passer d’un environnement de test à une exploitation fiable et conforme aux exigences légales et qualité.
2. Fondamentaux de Dolibarr et génération de PDF
| Élément | Description | Fonctionnalité clé |
|---|---|---|
| Modules « PDF » | Le module pdf (ou barcode) de Dolibarr crée le document PDF directement depuis les modèles Smarty. | mod/pdf → génération de fichiers via la fonction PDF::addBox, PDF::addText,… |
| Templates Smarty | Les modèles PDF sont stockés dans /dolibarr/htdocs/product/pdf/. Chaque type d dokument (facture, devis, bon de commande…) possède son propre fichier .tpl. | <tpl> : <table border="0" width="100%">{$invoice->lines}</tpl> |
| Bibliothèques externes | Dolibarr peut utiliser TCPDF, FPDF ou FPDF with tFPDF selon la configuration. Depuis la version 16, la bibliothèque TCPDF est la valeur par défaut, car elle supporte le CSS et le HTML. | pdf->mode → TCPDF, FPDF ou HTML2PDF selon les besoins. |
| Internationalisation | Le texte du PDF est injecté via les chaînes de langue de Dolibarr, garantissant la compatibilité multilingue. | TR($langs->trans('Facture')); |
| Gestion des pièces jointes | Les fichiers PDF peuvent être ajoutés à des emails, stockés dans l’onglet Documents ou envoyés via SFTP. | $dllPDF->sendpdf($link, $id, 'invoice', $pdfoptions); |
2.1. Étapes de génération d’un PDF
- Récupération du modèle : Dolibarr accepte un identifiant de type (
inv,Bill,Order, …). - Remplissage du template : Les variables Smarty (
{$invoice->num},{$invoice->date},{$line->label}…) sont substituées par les données de la base. - Appel de la bibliothèque : Le moteur PDF choisi transforme le template en flux PDF.
- Sauvegarde & diffusion : Le PDF est enregistré dans le répertoire /docs/ et/ou renvoyé au navigateur (
downloadouprint).
3. Pourquoi la génération de PDF est souvent le point de friction en production ?
| Problème fréquent | Conséquences | Causes typiques |
|---|---|---|
| Mauvaise résolution d’images | Texte flou, mauvaise impression | Utilisation de formats JPEG non optimisés, mauvaise configuration dpi. |
| Délais de génération | Temps d’attente > 5 s, serveur saturé | Boucles importantes dans le template, appels à la base de données inutiles. |
| Incohérences de mise en page | Factures non conformes, erreurs de totaux | Templates non testés sur tous les navigateurs, paramètres de police manquants. |
| Non‑conformité légale | Factures rejetées par les services comptables | Manque de champs obligatoires (TVA intracommunautaire, numéro de TVA intracommunautaire). |
| Gestion des pièces jointes | Perte de documents, double publication | Absence de procédure de sauvegarde dans le répertoire /docs/. |
4. Plan d’action sur 30 jours : « PDF & bonnes pratiques »
Objectif : Passer d’un pilote de test à une production stable, où chaque PDF généré respecte les exigences de forme, de vitesse et de conformité.
| Jour | Action | Détails | Livrable |
|---|---|---|---|
| 1‑3 | Audit initial | – Inventorier les modèles PDF actifs (factures, devis, bons de livraison). – Vérifier les bibliothèques PDF utilisées ( TCPDF, FPDF). – Exporter les logs de génération PDF (temps, erreurs). |
Rapport « State of PDF » avec liste des points critiques. |
| 4‑6 | Stabilisation des paramètres globaux | – Configurer pdf->mode = 'tcpdf' dans conf/accounting.– Ajuster pdf->dpi = 300 pour les images.– Activer la mise en cache des templates ( pdf->cache = true). |
pdf.conf.inc.php validé sur le serveur de production. |
| 7‑9 | Optimisation des modèles Smarty | – Simplifier les boucles ({$invoice->lines}) en limitant les appels SQL.– Utiliser des variables temporaires ( {$line_tmp = $line;}) afin de réduire le nombre de références dans le template. |
Templates allégés, temps de génération ↓ de 30 %. |
| 10‑12 | Validation des champs obligatoires | – Ajouter les contrôles de conformité via les annotations {$invoice->vatnum} et {$invoice->duedate}.– Vérifier la présence du champ « Numéro de TVA intracommunautaire » dans les modèles French. |
Checklist « Conformité légale » (10 points). |
| 13‑15 | Gestion des images et styles | – Convertir les logos en SVG ou WebP optimisé. – Créer un fichier CSS dédié pdf/style.css (police « DejaVu Sans », couleur corporate).– Inclure le CSS dans le template via { assign var='css' value='style.css' } puis <link rel="stylesheet" href="{$css}">. |
PDFs affichés correctement sous Chrome/Firefox + impression haute qualité. |
| 16‑18 | Automatisation des tests | – Mettre en place un pipeline CI (GitLab CI / GitHub Actions) qui lance php bin/dolibarr-testpdf.php.– Ce script parcourt les modèles, génère un PDF, compare le hash avec une référence. |
Rapport de test PDF quotidien (fail/pass). |
| 19‑21 | Déploiement de la sauvegarde des PDF | – Créer un job cron (0 * * * * php dolibarr/pdf_cleaner.php) qui archive les PDF dans /var/backups/dolibarr/pdfs/ avec rétention 30 jours.– Activer la sauvegarde sur le répertoire docs du serveur. |
Script de nettoyage et politique de rétention définie. |
| 22‑24 | Formation utilisateurs | – Réunion de 1 h avec les équipes comptabilité et ventes : « Comment imprimer / sauvegarder un PDF Dolibarr ». – Partager le guide interne « PDF best‑practices ». |
Session de formation et slide PDF à disposition. |
| 25‑27 | Monitoring en production | – Activer la couche de logs dolibarr.log pour pdf ($conf->pdf->enable_debug = 1).– Configurer Grafana/Prometheus pour visualiser le temps moyen de création (objectif < 2 s). |
Dashboard opérationnel. |
| 28‑30 | Revue finale & documentation | – Rédiger la procédure « Gestion des PDF en production » (version 1.0). – Valider le SLA : < 2 s de génération, 99,9 % de disponibilité, conformité légale 100 %. – Planifier la prochaine itération (ex. : passage à HTML2PDF pour fiches produit). |
Document final + tableau des KPI atteints. |
5. Bonnes pratiques à appliquer en continu
- Séparez les environnements – Ne jamais générer de PDF directement depuis le back‑office de production. Utilisez le mode
dev→prodavec un répertoire de sortie dédié ($conf->pdf->dir = '/var/www/html/dolibarr/docs/pdfs';). - Toujours forcer l’encodage UTF‑8 – Dans chaque template, ajoutez
{assign var='encoding' value='UTF-8'}et incluez<meta charset="utf-8">. - Contrôle des dimensions – Limitez les largeurs de colonnes à 100 % et évitez les
floatnon contrôlés qui peuvent créer des débordements. - Cache & pré‑compilation – Activez le cache des templates (
pdf->cache = true) et regénérer le cache lorsqu’un champ clé change (ex. : TVA). - Gestion des erreurs – Enveloppez chaque génération dans un
try { $pdf->create($tpl, $mode); } catch (Exception $e) { log::error('PDF', $e); }. - Tests unitaires – Créez des tests PHPUnit qui instancient
DolPDFavec des jeux de données miniatures et valident la présence de champs obligatoires. - Versionnage des modèles – Placez les fichiers .tpl sous git et ajoutez un .gitignore qui exclut les générations de PDF (
docs/*.pdf). Ainsi chaque modification de modèle est traçable.
6. Étude de cas rapide : Facturation trimestrielle avec Dolibarr 23
| Contexte | Problème | Solution appliquée | |
|---|---|---|---|
| Entreprise X (1500 factures/mois) | Temps moyen de génération : 4,8 s, factures avec erreurs de totaux, perte de pièces jointes lorsqu’elles étaient envoyées par email. | 1️⃣ Migration vers TCPDF 6.6 (activer le mode HTML). 2️⃣ Refactorisation du template invoice.tpl en limitant le nombre de foreach imbriqués.3️⃣ Implémentation d’un cron de pré‑génération (à 02:00 h) qui crée les PDF en lot. 4️⃣ Sauvegarde automatisée + notification Slack en cas d’échec. |
– Temps de génération ↓ à 1,2 s. – Taux d’erreur ↓ à 0,2 %. – Satisfaction interne ↑ 92 %. |
7. Checklist de production (PDF)
| ✅ | Élément |
|---|---|
| 1 | $conf->pdf->mode réglé sur la bibliothèque adaptée (TCPDF recommandé). |
| 2 | pdf->dpi ≥ 300 pour les images et pdf->compression activée. |
| 3 | Tous les modèles portent le même CSS global (police, couleur, marges). |
| 4 | Les champs obligatoires légales sont toujours rendus (numéro de TVA, mentions légales). |
| 5 | Génération de PDF testée via le script de pipeline CI. |
| 6 | Logs de génération et alertes configurés (Grafana/Datadog). |
| 7 | Historique de sauvegarde (30 jours) et nettoyage automatisé. |
| 8 | Documentation interne à jour (procédures, version de Dolibarr). |
| 9 | Formation des équipes sur la sauvegarde et l’impression des PDFs. |
| 10 | Révision mensuelle des KPI : temps moyen, taux d’erreur, volumétrie PDF générée. |
8. Conclusion
La génération de PDF dans Dolibarr ne doit pas être considérée comme une fonctionnalité « prête à l’emploi ». En production, chaque PDF passe par un pipeline : conception du template → remplissage des données → rendu via une bibliothèque optimisée → sauvegarde et diffusion.
En suivant le plan de 30 jours présenté, vous pouvez :
- Accélérer le temps de génération de plus de 50 %,
- Garantir la conformité légale et la cohérence graphique,
- Automatiser la surveillance et la sauvegarde des documents,
- Offrir aux équipes métier une expérience fluide et fiable.
En résumé, PDF + bonnes pratiques = confiance. Un PDF bien généré rassure le client, simplifie la comptabilité et minimise les risques d’erreurs coûteuses. Avec Dolibarr, vous avez les outils ; il suffit de les orchestrer correctement.
Annexes
A. Commandes utiles
# Afficher les modèles PDF utilisés
php -r "require('/var/www/html/dolibarr/htdocs/init.php'); var_dump($db->fetch_all('SELECT id, name FROM llx_product WHERE pdf_template IS NOT NULL;'));"
# Générer un PDF en CLI (démo)
php dolibarr/pdf_generator.php --type=invoice --id=42 --output=/tmp/invoice_42.pdf
# Nettoyer les PDFs anciens (>30 jours)
php dolibarr/pdf_cleaner.php --keep=30B. Exemple de CSS dédié au PDF
@page {
size: A4;
margin: 20mm 15mm 15mm 15mm;
}
body { font-family: "DejaVu Sans", sans-serif; font-size: 10pt; color:#000; }
table { width:100%; border-collapse:collapse; }
th, td { border:1px solid #ccc; padding:4px 6px; }
.logo { width:40mm; margin-bottom:5mm; }
.total { font-weight: bold; text-align: right; }C. Références
- Dolibarr Documentation – PDF Generation – https://docs.dolibarr.org/en/latest/
- TCPDF User Guide – https://tcpdf.org/docs/
- ISO 2051 – Facturation électronique – exigences de champs obligatoires.
- Article “Best Practices for PDF Generation in Open‑Source ERPs”, Journal of Open Source Software, 2023.
Bonne mise en production !