Table des Matières

  1. Introduction

  2. Comment fonctionne la facturation PDF dans Dolibarr

  3. Principaux moteurs de génération de PDF : TCPDF vs DOMPDF

  4. Symptômes courants des erreurs d'affichage PDF

  5. Causes profondes des problèmes de facturation PDF

  6. Flux de travail de diagnostic étape par étape

  7. Correction n° 1 : Réparation des erreurs de modèle PDF

  8. Correction n° 2 : gestion de la compatibilité des polices

  9. Correction n° 3 : Ajuster la configuration PHP pour la génération de PDF

  10. Correction n° 4 : Résolution des problèmes d'autorisation et d'accès aux fichiers

  11. Correction n° 5 : Utiliser la bonne méthode de sortie (navigateur, téléchargement, stockage)

  12. Modèles personnalisés : bonnes pratiques pour éviter la casse

  13. Conseils pour la sortie PDF multilingue et RTL (arabe, hébreu)

  14. Réflexions finales

1. Introduction

Dolibarr ERP & CRM est une plateforme commerciale open source largement adoptée qui simplifie les opérations, de la facturation et des paiements à la gestion des stocks, en passant par la gestion de la relation client (CRM), la comptabilité et le suivi de projets. L'une de ses fonctionnalités les plus cruciales, notamment pour les opérations commerciales, est la possibilité de générer des rapports. Factures PDF et autres documents automatiquement.

Cependant, de nombreux utilisateurs rencontrent un problème frustrant : leurs factures ne s'affichent pas correctement, ne sont pas générées du tout ou génèrent des PDF cassés ou illisiblesQue vous soyez auto-hébergé ou que vous utilisiez une instance Dolibarr basée sur le cloud, ces problèmes peuvent perturber les flux de facturation et nuire à l'image professionnelle de votre entreprise.

Ce guide décompose pourquoi les factures PDF ne s'affichent pas correctement dans Dolibarr, comment fonctionne la génération PDF sous-jacente et comment vous pouvez diagnostiquer et résoudre ces problèmes, rapidement et définitivement.

2. Fonctionnement de la facturation PDF dans Dolibarr

Lorsque vous cliquez sur « Générer un PDF » dans Dolibarr (pour une facture, une proposition, une commande, etc.), le système :

  1. Utilise un Modèle basé sur PHP (connu sous le nom de « modèle PDF »)

  2. Remplit les variables dynamiques (nom du client, détails de l'article, montant total, etc.)

  3. Envoie ce contenu à un Moteur PDF (TCPDF ou DOMPDF)

  4. Affiche le résultat pour :

    • Téléchargement immédiat

    • Affichage du navigateur

    • Stockage de fichiers dans /documents/

La génération de PDF est entièrement gérée côté serveur, ce qui signifie que l'environnement (version PHP, paramètres de mémoire, prise en charge des polices) joue un rôle essentiel dans la réussite ou l'échec.

3. Principaux moteurs de génération de PDF : TCPDF vs DOMPDF

Dolibarr prend en charge deux moteurs de rendu PDF principaux :

TCPDF (moteur par défaut dans les anciennes versions)

  • Largement utilisé dans les anciennes versions de Dolibarr

  • Rapide et léger

  • Prend en charge UTF-8 et le rendu d'image de base

  • Mauvais support pour les CSS ou les mises en page avancées

DOMPDF (introduit dans les versions ultérieures)

  • Plus moderne et flexible

  • Prend en charge la mise en page HTML5/CSS3

  • Nécessite plus de mémoire et des ressources système plus lourdes

  • Idéal pour les conceptions personnalisées et les documents complexes

Si vos factures sont vierges, corrompues ou mal alignées, le problème peut être lié à limitations du moteur, mauvaise configuration ou contraintes de ressources.

4. Symptômes courants des erreurs d'affichage PDF

Les utilisateurs signalent généralement les problèmes suivants lors de la génération de factures :

  • PDF vierge sans contenu

  • Rendu incomplet (tableaux, prix, informations clients manquants)

  • Texte mal aligné ou décalage de mise en page

  • Téléchargements PDF mais ne s'ouvre pas

  • Messages d'erreur tels que :

    • TCPDF ERROR: Some data has already been output

    • DOMPDF Fatal error: Uncaught exception

  • Le PDF semble correct mais affiche une langue incorrecte ou des caractères cassés

Ces symptômes indiquent différentes causes profondes, allant des problèmes de configuration du serveur au code de modèle défectueux ou aux polices manquantes.

5. Causes profondes des problèmes de facturation PDF

Voici les causes les plus courantes d'échec de facturation PDF dans Dolibarr :

Causes Description
Modèle PDF corrompu ou obsolète Problèmes de syntaxe ou erreurs de logique dans les modèles PDF personnalisés
Version PHP incompatible DOMPDF et TCPDF ont des exigences PHP strictes
Polices manquantes ou prise en charge Unicode Les caractères non latins interrompent la sortie
Faibles limites de mémoire ou d'exécution PHP Les factures importantes ne sont pas traitées en raison de l'épuisement des ressources
Autorisations incorrectes Dolibarr ne peut pas écrire sur /documents/ ou accéder aux modèles
En-têtes de sortie déjà envoyés Empêche la génération correcte du fichier en raison d'un écho ou d'un espace prématuré
Mauvaise configuration du chemin de fichier Pointe vers des dossiers inexistants ou obsolètes
Encodage du serveur ou paramètres régionaux incorrects Interrompt le rendu PDF multilingue

Chacun de ces problèmes nécessite une approche différente pour être résolu.

6. Flux de travail de diagnostic étape par étape

Avant d’appliquer les correctifs, suivez cette routine de diagnostic structurée :

Étape 1 : Activer le mode développeur

In conf.php, activer le mode développeur :

php

define('DOL_DEVELOPER_MODE', 1);

Ceci affiche la sortie de débogage de la génération PDF.

Étape 2 : Reproduire le problème

  • Essayez différents modèles de factures (par exemple, crabe, azur, rouget)

  • Générer des PDF pour les petites et grandes factures

  • Tentez les actions de téléchargement et d'aperçu

Étape 3 : Vérifier les journaux

  • Journaux PHP (/var/log/php/error.log)

  • Journaux Apache/Nginx (/var/log/apache2/error.log)

  • Fichier journal interne de Dolibarr (si configuré)

Étape 4 : Vérifier le code source du modèle

  • Allez dans /dolibarr/core/modules/facture/doc/

  • Vérifiez le code PHP pour détecter les problèmes de syntaxe, les balises non fermées ou les fonctions obsolètes.

7. Correction n°1 : Réparer les erreurs de modèle PDF

Modèles PDF (par exemple, pdf_crabe.modules.php) sont écrits en PHP. Un seul caractère mal placé peut endommager le résultat.

Liste de contrôle:

  • Qu'on Assure <?php les balises ne sont pas suivies d'espaces

  • Aucune sortie HTML ou texte avant les en-têtes sont définis

  • Pas d'accident echo or print appels dans les sections logiques

  • Variables comme $this->emetteur doit être correctement initialisé

Conseil : testez d’abord avec les modèles par défaut

Passer à la valeur par défaut de Dolibarr crabe modèle. Si cela fonctionne, votre modèle personnalisé est le problème.

8. Correction n° 2 : Gestion de la compatibilité des polices

Les moteurs PDF nécessitent la police appropriée pour afficher correctement les caractères.

Symptômes des problèmes de police :

  • Le texte arabe, chinois ou cyrillique ne s'affiche pas

  • Espaces vides où les noms ou adresses devraient être

  • Le PDF affiche « ???? » au lieu de lettres

Solutions:

  • Basculer vers Polices compatibles UTF-8 comme DejaVu Sans ou FreeSerif

  • Pour DOMPDF, chargez manuellement les polices à l'aide de load_font.php utilitaire

  • Évitez les polices système non intégrées dans la sortie PDF

Dans Dolibarr, vous pouvez personnaliser les paramètres de police par modèle.

9. Correction n° 3 : Ajuster la configuration PHP pour la génération de PDF

DOMPDF nécessite notamment des ressources serveur adéquates.

Mises à jour php.ini:

ini

memory_limit = 512M max_execution_time = 120 upload_max_filesize = 20M post_max_size = 25M

Redémarrez Apache/Nginx ou PHP-FPM après les modifications.

Vérifier les extensions

Assurez-vous que les extensions PHP suivantes sont actives :

  • mbstring

  • gd

  • dom

  • fileinfo

  • intl (pour la prise en charge des langues/paramètres régionaux)

Utilisation:

bash

php -m | grep gd

10. Correction n° 4 : Résolution des problèmes d'autorisation et d'accès aux fichiers

Si Dolibarr ne peut pas écrire au /documents/ dossierLa génération de PDF échoue silencieusement.

Commandes pour corriger les autorisations :

bash

chown -R www-data:www-data /var/www/dolibarr/documents chmod -R 755 /var/www/dolibarr/documents

remplacer www-data avec l'utilisateur de votre serveur Web.

Assurer les sous-répertoires pour les factures (/documents/facture/) sont présents.

11. Correction n° 5 : Utiliser la bonne méthode de sortie (navigateur, téléchargement, stockage)

Dolibarr permet différents comportements de sortie lors de la génération de factures PDF :

  • Afficher dans le navigateur (en ligne)

  • Demande de téléchargement

  • Enregistrer directement dans /documents/ annuaire

Si les factures ne s'affichent pas correctement dans une méthode mais fonctionnent dans une autre, le problème peut provenir de En-têtes HTTP ou compatibilité du navigateur.

Nos recommandations:

  • Tester toutes les méthodes de sortie à partir de la page de facture

  • Évitez d'envoyer une sortie HTML (comme des informations de débogage) avant les en-têtes

  • Vérifier les conflits Content-Type or Content-Disposition têtes

  • Désactiver les extensions de navigateur susceptibles de bloquer le rendu PDF

Dans certains cas, le passage de l’affichage en ligne au téléchargement résout les problèmes d’« écran vide ».

12. Modèles personnalisés : bonnes pratiques pour éviter les casses

La création d'un modèle PDF personnalisé pour les factures est courante dans Dolibarr, mais elle introduit des risques potentiels de compatibilité avec :

  • Mises à niveau de la version PHP

  • Modifications du moteur PDF

  • Mises à jour du noyau de Dolibarr

Pour éviter de futurs problèmes :

12.1 Utiliser le squelette du modèle officiel

Utiliser un modèle existant (comme crabe) comme point de départ. Respectez la structure interne de Dolibarr :

  • Définir $object correctement (généralement un Facture instance de classe)

  • Utiliser des méthodes d'assistance internes pour la génération de tables

  • Évitez les positions de mise en page codées en dur : utilisez un positionnement relatif

12.2 Désinfecter toutes les sorties

Échappez les chaînes qui peuvent contenir des caractères spéciaux ou interrompre l'encodage :

php

$this->pdf->MultiCell(..., dol_htmlentities($line->description), ...)

12.3 Valider avec les outils de développement

Si vous utilisez une logique personnalisée (par exemple, totaux, remises), validez les résultats par rapport au PDF intégré de Dolibarr et à l'affichage à l'écran.

12.4 Conserver les modèles sous contrôle de version

Stockez des modèles personnalisés dans Git. Cela vous permet de :

  • Restaurer les versions cassées

  • Suivez les changements de compatibilité au fil du temps

  • Fusionnez facilement les modifications entre les mises à niveau de Dolibarr

13. Conseils pour la sortie PDF multilingue et RTL (arabe, hébreu)

La génération de PDF multilingues ou de droite à gauche nécessite une attention particulière.

13.1 Définir les paramètres régionaux corrects

Assurez-vous que Dolibarr est défini sur la langue de l'utilisateur/client avant la génération du PDF :

php

$langs->setDefaultLang('ar_EG');

Dans certains cas, vous devrez peut-être forcer le jeu de caractères :

php

header('Content-Type: application/pdf; charset=UTF-8');

13.2 Utiliser des polices compatibles RTL

Des polices comme Amiri, Noto Naskh Arabe, Déjà-Vu Sans prend en charge les scripts RTL.

13.3 Activer RTL dans DOMPDF

DOMPDF prend en charge RTL uniquement lorsqu'il est explicitement configuré :

php

$this->pdf->setRTL(true);

Cependant, la prise en charge peut varier. TCPDF est généralement plus fiable pour les scripts RTL, mais sa conception est moins flexible.

13.4 Évitez de mélanger LTR/RTL sans paramètres d'alignement

Dans les tableaux, définissez toujours explicitement les propriétés d'alignement. Exemple :

php

$this->pdf->MultiCell(..., 'Client Name:', 0, 'R'); $this->pdf->MultiCell(..., $client_name, 0, 'L');

14. Réflexions finales

La génération de factures PDF professionnelles dans Dolibarr devrait être une expérience transparente, mais elle peut facilement devenir un point de frustration lorsque les modèles se cassent, que les paramètres du serveur entrent en conflit ou que le contenu ne s'affiche pas.

Voici une liste de contrôle finale pour garantir une sortie PDF robuste :

✅ Utiliser modèles officiels comme base pour un travail personnalisé
✅ Gardez vos versions PHP et Dolibarr alignées avec compatibilité des modules
✅ Assurer couverture des polices pour chaque langue que vous utilisez
✅ Définir correctement autorisations sur le /documents/ annuaire
✅ Valider syntaxe de modèle, éviter une sortie prématurée
✅ Régulièrement tester des modèles personnalisés après les mises à niveau de Dolibarr
✅ Si multilingue ou RTL : vérifier le comportement de la police et de la mise en page sur des données réelles
✅ Utiliser journaux et mode développeur pour tracer les erreurs silencieuses

Un petit oubli de configuration ou un modèle obsolète peut perturber l'ensemble de votre processus de facturation. Grâce au cadre de diagnostic et aux correctifs détaillés dans ce guide, vous disposerez de tout le nécessaire pour résoudre et prévenir les problèmes liés aux PDF dans Dolibarr.

En mettant en œuvre ces bonnes pratiques, vous vous assurez que vos factures PDF sont clair, fiable, professionnel et entièrement fonctionnel—quelle que soit la version de Dolibarr ou de PHP que vous utilisez.