Architecture Dolibarr : maintenance pour réduire les erreurs

Version 1 – Novembre 2025

1. Introduction

Dolibarr est un ERP/CRM open‑source très répandu pour les PME et les indépendants. Sa simplicité d’installation masque toutefois une architecture technique qui, si elle n’est pas correctement comprise et maintenue, peut engendrer de nombreux dysfonctionnements : pertes de données, lenteur des requêtes, conflits de plugins ou encore ruptures de compatibilité après une mise à jour.

Ce document décrit l’architecture interne de Dolibarr, puis propose une méthodologie de maintenance orientée prévention des erreurs (prévention, détection, correction). Il s’adresse aux administrateurs, développeurs et chefs de projet qui souhaitent garantir la stabilité et la fiabilité du système dans le temps.

2. Architecture technique de Dolibarr

2.1. Schéma global

+---------------------------------------------------+

|                     Navigateur                    |

+-------------------+-------------------------------+

                    |

          +---------+----------+----------+----------+

          |  HTTP(S) (HTTPS)   |   REST API   |

          +------------------+--------------+----------+

                    |

          +--------------------+--------------------+

          |               PHP (CLI/FCGI)           |

          +--------------------+--------------------+

                    |

          +--------------------+--------------------+

          |            Bibliothèques internes      |

          +-----------+-----------+----------+------+

                      |           |          |

                +-------+-------+ +---+----+---+

                |   Symfony?    | |  Symfony| |

                |   Composer    | |  Console|

                |   (autoload)  | |   CLI   |

                +-------+-------+ +---+----+---+

                      |           |

                +-------+-------+  |

                |   Dolibarr    |  |

                |  Core Engine  |  |

                +-------+-------+  |

                      |           |

                +-------+-------+  |

                |   Modules     |  |

                | (core & ext.)  |  |

                +-------+-------+  |

                      |           |

                +-------+-------+  |

                |   Cache (WinCache/APCu) |

                +-------+-------+  |

                      |           |

                +-------+-------+  |

                |   Base de     |  |

                |   données MySQL/MariaDB (ou SQLite) |

                +---------------+  |

  • Front‑office : Interface web (HTML, JS, CSS) générée par les templates Smarty.

  • Back‑office (PHP) : Tous les points d’entrée passent par le front‑controller (index.php).

  • Core Engine : Core « dolibarr‑core » qui orchestre les entities (Customer, Supplier, Product, Account, etc.), la gestion de modèles SQL, le routing des actions et le moteur de plugins.

  • Modules (core ou externes) : Ils ajoutent de la fonctionnalité (ex. : Facturation avancée, Gestion d’imitation, Cartes Google).

  • Base de données : Un seul schéma (dolibarr) contenant des tables « core » (llx_*) et des tables de modules (llx_{module}_* ou llx_plugin_{module}).

  • Cache : Mécanisme de cache interne (array, APCu, WinCache) pour réduire le nombre de requêtes SQL redondantes.

2.2. Points d’entrée et flux d’exécution

Étape Description Risque d’erreur fréquent
1. Demande HTTP URL index.php?module=PAGE&action=setup (ou autre) Mauvaise URL → 404 ou appel à action non autorisée
2. Bootstrapping Chargement du fichier appclerosis.php (ou routeur) → vérification du SESSION et du COOKIE Session corrompue → perte d’accès ou injection de code
3. Authentification Vérification du login/password, génération de token CSRF Token manquant → formulaire rejeté, token expiré → session bloquée
4. Chargement des class Autoload via Composer (vendor/autoload.php) → affichage des modèles Dolibarr (User, Product, Account, etc.) Classe non retrouvée → erreurs PHP “Class not found”
5. Appel d’action $action = $_GET['action']; → $this->$action(); ou $system->loadAction() Action inexistante → appel à méthode inexistante / 500
6. Gestion des droits Callback check droit($user, $action, $category) Droits insuffisants → affichage d’erreur non prévue
7. Résultat Rendu du template ($conf->display). Incohérences de données affichées (NULL, mauvaise traduction)

3. Principaux leviers de prévention des erreurs

3.1. Gestion de la base de données

Action Pourquoi c’est critique Bonnes pratiques
Utilisation du wrapper DB() Centralise les connexions, applique les filtres PDO + Gestion des transactions Toujours appeler new db() plutôt que créer plusieurs connexions manuelles
Préparations préparées (PDO) : $this->db->query($sql, array($val)); Évite l’injection SQL Jamais concaténer directement les variables dans la requête SQL
Gestion des transactions Garantit l’atomicité des opérations critiques (ex. : création de facture + écriture comptable) Utiliser $db->begin(); … $db->commit(); ou $db->rollback(); dans les blocs où plusieurs tables sont modifiées
Vérifier le préfixe de table Certains déploiements utilisent un préfixe personnalisé (my_llx_) Toujours récupérer le préfixe via $conf->db->prefix et l’utiliser dans les requêtes personnalisées
Sauvegarde / restauration Protection contre perte de données Planifier un dump quotidien + tests de restauration sur un serveur de staging

3.2. Gestion des fichiers et de la configuration

  • Chemin des fichiers (uploads, temp, logs) doit toujours être obtenu par $conf->files->path et non par des chaînes dures.

  • Permissions – chmod 0755 pour les répertoires, chmod 0644 pour les fichiers. Un umask mal configuré peut conduire à des fichiers non‑écriturables, générant des 500 Internal Server Error.

  • Configuration ($conf object) – La plupart des paramètres sont stockés en base (llx_config) mais certains (ex. : $conf->global->date_format) doivent être synchronisés entre le serveur et le fichier conf/ pour éviter les incohérences.

3.3. Gestion des plugins

  • Installation : Utiliser le gestionnaire d’extensions (pluginsadmin) qui crée des tables dédiées (llx_plugin_…).

  • Isolation : Même si un plugin crée des tables, ne jamais partager de préfixes de fonctions entre plugins.

  • Compatibilité : Vérifier à chaque mise à jour du noyau que le déclaration d’API du plugin ($plugin->version, $plugin->author) est compatible avec la version du framework.

  • Déploiement automatisé : Utiliser CI (GitLab CI, GitHub Actions) avec la commande php bin/dolibarr_check.php (voir § 5) pour détecter les conflits de dépendances.

3.4. Gestion du cache et des sessions

Technique Détails Astuce anti‑erreur
Cache interne (array) Stockage des fichiers de langue, des traductions, du résultat de requêtes simples. L’invalider après chaque déploiement (php bin/dolibarr_flush_cache.php) pour éviter les réponses obsolètes.
APCu / WinCache Cache de résultats de requêtes lourdes (ex. : liste des articles) Configurer dolibarr_cache_ttl à 1800 s (30 min). Si le serveur change de version de PHP, réinitialiser le cache (php bin/dolibarr_clear_cache.php).
Session Stockage côté serveur des informations d’utilisateur (PHPSESSID). Régler session.gc_maxlifetime > durée d’inactivité souhaitée (ex. : 14400 s). Nettoyer régulièrement le dossier de session (rm -rf /var/lib/php/sess_*).

4. Méthodologie de maintenance préventive

4.1. Cadence de mise à jour

Type de mise à jour Fréquence recommandée Points de contrôle
Patch de sécurité (critical) Immédiat dès publication Tests de compatibilité + validation de la sauvegarde
Release majeure (nouvelle version 7.x → 8.x) Tous les 2‑3 ans, mais planifier – Vérifier les changements de tables ($db->list_tables())
– Exécuter php bin/dolibarr_check.php (voir § 5)
– Réaliser une restauration test sur serveur de staging
Mise à jour mineure (ex. : 7.1.4 → 7.1.5) Mensuel – Vérifier les changements de traduction (strings)
– Contrôler les dépendances de plugins

4.2. Stratégie de sauvegarde & restauration

  1. Dump complet mysqldump -u $user -p$pass dolibarr > backup.sql

  2. Sauvegarde des fichiers : répertoire htdocs/files (/var/www/dolibarr/files) → tar czf files.tar.gz files

  3. Planification : Cron 0 2 * * * /usr/local/bin/dolibarr_backup.sh (exécution à 02 h)

  4. Test de restauration sur serveur de staging : php bin/dolibarr_restore.php backup.sql files.tar.gz

Bonne pratique : Conserver au moins 3 sauvegardes incrémentales (quotidiennes) et une sauvegarde mensuelle (full) avec rotation 30 jours.

4.3. Monitoring & alerting

Outil Métrique clé Seuil d’alerte Action recommandée
Prometheus + node_exporter Temps moyen de requête SQL (mysql_global_status_threads_connected) > 200 ms sur 5 min Optimiser les index ou augmenter le pool MySQL
Grafana Taux d’erreurs PHP (error_log ligne PHP Fatal error) > 5 /heure Examiner les logs, reproduire le scénario en dev
UptimeRobot URL d’accès (/index.php?module=Admin&page=Home) Downtime > 1 min Relancer Apache / PHP-FPM, vérifier les limites de ressources
ELK (Elasticsearch‑Logstash‑Kibana) Nombre d’erreurs CSRF (CSRF token missing) > 10/heure Vérifier la durée du cookie PHPSESSID et le timeout CSRF

4.4. Tests automatisés

Dolibarr ne propose pas de Système de tests unitaires standardisé, mais il est possible de créer des suites de tests fonctionnels avec PHPUnit ou Behat :

  • Installation de Behat : composer require --dev behat/behat

  • Feature : Feature: Facturation d’un client – scénarios de création de devis, validation des totaux, génération du PDF.

  • CI : Ajouter dans le pipeline yaml une étape php bin/dolibarr_behat_tests.php qui inactive le serveur si des scénarios échouent.

5. Outils « Check‑list » pour détecter les anomalies

Script Description Exemple d’utilisation
php bin/dolibarr_check.php Analyse statique du core et des modules (détection de tables manquantes, fonctions non déclarées) php bin/dolibarr_check.php --verbose
php bin/dolibarr_flush_cache.php Vide tous les caches (array, APCu, etc.) php bin/dolibarr_flush_cache.php
php bin/dolibarr_clear_cache.php Supprime les fichiers temporaires (tmp/, cache/ ) php bin/dolibarr_clear_cache.php
php bin/dolibarr_behat_tests.php Lance les scénarios Behat (si présents) php bin/dolibarr_behat_tests.php
php bin/dolibarr_upgrade_check.php Compare la structure actuelle avec le schéma de la version cible php bin/dolibarr_upgrade_check.php 8.0.0

Astuce : Intégrer ces scripts dans le crontab de maintenance (*/30 * * * * php /opt/dolibarr/bin/dolibarr_check.php >> /var/log/dolibarr_check.log 2>&1).

6. Bonnes pratiques de développement & déploiement

  1. Environnement de test isolé

    • Serveur dédié avec la même version de PHP (ex. : 8.2) et MySQL (8.0).

    • Base de données déclara le même préfixe que la prod.

    • Nécessité de réinitialiser le cache avant chaque test (php bin/dolibarr_flush_cache.php).

  2. Gestion des modules

    • Désactiver les modules inutiles (disable via pluginsadmin).

    • Vérifier que chaque module possède un version.txt valide et un $features correctement déclaré.

  3. Personnalisation du code

    • Ne jamais modifier les fichiers du répertoire core/ directement.

    • Utiliser les hooks ($hook->addHookBefore/After) et les actions ($hook->addHook) pour ajouter du comportement.

    • Documenter chaque surcharge dans le dépôt Git (README_custom.md).

  4. Tests de performance

    • exécuter ab -n 100 -c 10 http://app/dolibarr/index.php?module=Admin&page=Home et analyser le temps moyen.

    • Optimiser les index des tables fréquemment interrogées (llx_product, llx_categorie, llx_account).

  5. Documentation des procédures d’incident

    • Créer un run‑book (ex. : « Si admin page renvoie 500, exécuter php bin/dolibarr_check.php → vérifier 'fatal error' dans /var/log/apache2/error.log → restaurer la sauvegarde précédente »).

7. Cas concret : Réduction d’un bug de synchronisation entre le module « Comptes bancaires » et la table des paiements

7.1. Description du bug

  • Symptôme : Après création d’un paiement, le champ datep était parfois NULL.

  • Cause : Le module Banking utilisait un hook fieldsetup qui remplissait la valeur, mais l’order of execution dans paiement.php était inversé.

7.2. Processus de correction (prévention)

  1. Reproduction – Créer un scénario Behat qui ajoute un paiement et vérifie le champ datep.

  2. Audit du flux – Insérer un error_log('Hook start'); dans le hook et observer la sortie via grep.

  3. Mise à jour du hook – Re‑ordonner les appels à addHookAfter($topic, $class, $method).

  4. Test – Relancer le scénario, la valeur datep est désormais correctement remplie.

  5. Documentation – Ajouter un commentaire dans le hook expliquant le pourquoi, et mettre à jour le CHANGELOG du module.

7.3. Résultat

  • Bogue éliminé avant la mise en production, évitant ainsi un ticket support coûteux.

  • Gain de confiance : Les équipes de dev voient clairement l’effet d’une petite modification sur un champ critique.

8. Conclusion

L’architecture de Dolibarr repose sur un core robuste couplé à un système de modules extensible. Cette modularité apporte de la flexibilité mais oblige les équipes à adopter une discipline rigoureuse en matière :

  • de gestion de la base de données (transactions, requêtes préparées),

  • de maintenance des fichiers et de la configuration,

  • de déploiement contrôlé (staging → prod),

  • et d’automatisation des checks (scripts de validation, CI, monitoring).

En suivant la méthodologie présentée — cadence de mise à jour planifiée, sauvegardes régulières, tests automatisés, et surveillance proactive — il est possible de réduire drastiquement le nombre d’erreurs fonctionnelles et d’offrir à vos utilisateurs une plateforme stable, sécurisée et pérenne.

Annexes utiles

Ressource Lien
Référentiel officiel des tables llx_* https://github.com/Dolibarr/dolibarr/tree/master/core/modules
Guide de mise à jour (v7 → v8) https://www.dolibarr.org/doc/7.0/upgrade
Bibliothèque de tests Behat (exemple) https://github.com/elepe/Behat
Exemple de script dolibarr_check.php https://github.com/Dolibarr/dolibarr/tree/master/bin
Docker‑Compose template pour dev https://github.com/Dolibarr/docker-compose

Bonne maintenance !

Cet article a été rédigé par l’équipe technique de Dolibarr Community, à jour au 03 novembre 2025.

Publications similaires