Diagnostiquer Dolibarr : support Méthode pour réduire les erreurs

Version : 1.0 – novembre 2025
Auteur : Équipe de support Dolibarr (Open‑Source ER​P/CRM) —

1. Introduction Dolibarr est un ERP / CRM léger, entièrement écrit en PHP et MySQL, qui convient aussi bien aux petites structures qu’aux PME. Malgré sa simplicité d’utilisation, les environnements de production peuvent rapidement se complexifier, notamment en raison de :

  • Mauvaises configurations (permissions, paramètres PHP, pilotes BD)

  • Mises à jour non testées

  • Interférences avec d’autres extensions (modules tiers, thèmes)

  • Données corrompues (tables de base de données, sessions)

Ce document propose une méthode de diagnostic structurée et des actions de support pour réduire durablement les erreurs rencontrées dans un serveur Dolibarr en production.

2. Cadre de diagnostic recommandé | Étape | Objectif | Outils / Moyens | Résultat attendu |

|——-|———-|—————-|——————|
| 2.1 | Recenser l’environnement (OS, version PHP, extensions, serveur web) | php -v, phpinfo(), composer show-assets | Baseline fonctionnelle et Identification des incompatibilités |
| 2.2 | Vérifier la santé de la base de données | SHOW ENGINE INNODB STATUS; (MySQL), SELECT * FROM dol_user; | Détection des problèmes de requêtes, de verrous ou de tables corrompues |
| 2.3 | Analyser les logs appliqués (PHP, Apache/Nginx, Dolibarr) | /var/log/php-fpm.log, error_log de Dolibarr | Identification du type d’erreur (warning, notice, fatal) |
| 2.4 | Reproduire l’incident hors contexte de production (dev/clône) | Installation locale (Docker, VM) | Confirmation de la répétabilité et des conditions déclencheuses |
| 2.5 | Appliquer les bonnes pratiques de mise à jour et de configuration | Guide de mise à jour de Dolibarr, checklist de sécurité | Correction ciblée et prévention des reappears |

— ## 3. Méthode pas à pas

3.1 Collecte d’informations initiales

  1. Version exacte 

    php -r "echo PHP_MAJOR_VERSION.'.'.PHP_MINOR_VERSION;\""
    
cat /var/www/dolibarr/version.txt

    Notez le code de révision (ex. 15.0.3+20251001).

  2. Profils serveur

    • OS (cat /etc/os-release)

    • PHP  (php -m) : pdo_mysql, zip, gd, exif obligatoires – Base de données  (SELECT VERSION();) : MySQL 5.7+, PostgreSQL 12+, SQLite 3.26+

    • Serveur web  (apache2 -v ou nginx -v)

  3. État de la base

    • Vérifier les tables : SHOW TABLES LIKE 'categorie%';

    • Exécuter SELECT COUNT(*) FROM dol_log; pour s’assurer que le nettoyage s’est bien produit.

    • Si le moteur est InnoDB, lancer `: 

      
ANALYZE TABLE dol_user;
      
```  4. **Permissions**  
      
```bash
      
ls -lR /var/www/dolibarr/ | grep -E 'drwx|-rw-'
      
```     - Directories **775** (ou 755 sur serveur partagé)

    • Files 644

    • config.php doit être 640 ou 600 et non‑exécutable.

3.2 Revue des logs

Source Location Filtre recommandé Exemple d’analyse
PHP error log /var/log/php-fpm.log ou /var/log/php7.4-fpm.log grep -i "Dolibarr" -n Recherche de PHP Fatal error, Uncaught Exception
Apache/Nginx error /var/log/apache2/error.log grep -i "Dolibarr" Parssage des Segfault, Permission denied
Dolibarr log ~/dolibarr/htdocs/logs/*.log grep -i "ERROR" Corrélation avec les appels API et modules

Synthèse : Tableau à alimenter quotidiennement avec les lignes critiques et leurs dates.

3.3 Reproduction contrôlée

  1. Clonez l’environnement : 
    docker run -d -p 8080:80 -e DB_SERVER=127.0.0.1 -e DB_USER=dolibarr -e DB_PASSWORD=secret -e DB_NAME=dolibarr_nightly -v $(pwd)/dolibarr:/var/www/dolibarrImage:dolibarr:15.0.3

  2. Chargez le module d’erreur (ex. capture_trace.php) pour obtenir le stack trace complet.

  3. Reportez les requêtes SQL exécutées : activez le general log (MySQL) ou log_statement = 'all' (PostgreSQL).

Conseil : Si l’erreur apparaît uniquement sous charge, simulez plusieurs requêtes simultanées avec ab (Apache Bench) ou hey.

3.4 Vérification des mises à jour

  • Comparer le git log (ou les archives) entre la version installée et la dernière stable release. – Appliquer les patches (ex. CVE‑2025‑XXXXX) via composer update ou le script scripts/update du repository. – Tester la chaîne CI : 
    docker exec -it dolibarr php bin/phpunit --filter=testUpgrade

3.5 Application de correctifs ciblés

Type d’erreur Correctif recommandé Exemple de mise en œuvre
Notice / Warning Ignorer seulement si l’impact fonctionnel est nul ou ajouter @ de façon ciblée. error_reporting(E_ALL & ~E_DEPRECATED & ~E_NOTICE); dans config.php.
Fatal error – Call to undefined function Installer le module PHP manquant (apt install php8.2-zip). docker exec -it dolibarr apt-get install -y php8.2-zip.
SQL syntax error Mettre à jour le schéma ou corriger le nom de champ. ALTER TABLE dol_user ADD COLUMN last_login DATETIME;
Timeout Augmenter max_execution_time ou optimiser les index. SET GLOBAL max_allowed_packet = 64M;
Permission denied Changer les groupes (chown -R www-data:www-data /var/www/dolibarr) ou ajouter le groupe au répertoire. chmod g+ws /var/www/dolibarr/files.
Deprecated API Adopter la nouvelle fonction ou mettre à jour le code. Remplacer md5($crypto_key) par openssl_encrypt.

4. Guide de réduction durable des erreurs

4.1 Processus de mise à jour automatisé

  1. Branch protection sur main (GitHub/GitLab)

    • Exiger pull‑request avec revue de code.

    • Pipeline CI : composer ci → phpunit → phpstan.

  2. Mise à jour en deux étapes

    • Version mineure (X.Y → X.Y+1) : test unitaire complet.

    • Version majeure (X → X+1) : mise en place d’un environnement de pré‑production isolé.

  3. Rollback automatique via Docker tag :previous.

4.2 Outils de monitoring continu

Outil Fonction Implémentation Dolibarr
Grafana + Prometheus Métriques temps de réponse, taux d’erreur HTTP Exporter dolibarr_status.php avec /metrics (ex. php -S 0.0.0.0:8000 -t htdocs)
Sentry Capture des exceptions PHP Configurer sentry.io via sentry/sdk-php dans config.php.
Watchtower (Docker) Mise à jour automatique des containers docker run -d --restart unless-stopped -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower

4.3 Checklist de validations pré‑déploiement

✔️ Action
1 Vérifier les permissions sur les dossiers files, globalpayments, certains.
2 Exécuter le script de nettoyage php scripts/clean.php.
3 Tester le chemins d’accès avec realpath (ex. require_once realpath('inc/lib.php');).
4 S’assurer que le cron de sauvegarde ne supprime pas dol_log sans archive.
5 Effective backup avant migration (mysqldump --single-transaction).

4.4 Documentation et partage des connaissances

  • Wiki interne : répertorier chaque type d’erreur avec sa cause, solution, date de résolution.

  • Playbook de support (Markdown) : 
    ## Erreur : "Fatal error: Uncaught Error: Call to a member function get() on null"
    
- Cause fréquente : Table `dol_user` corrompue ou champ manquant.
    
- Diagnostic : `SELECT COUNT(*) FROM dol_user;` → 0 ou erreur.
    
- Solution : `REPAIR TABLE dol_user;` + mise à jour du champ `login`.

  • Formation annuelle de l’équipe support (débugging, versionning).

5. Exemples concrets de résolution

5.1 Cas pratique 1 – “SQLSTATE[HY000] [2002] Connection refused”

Symptome Analyse Action Résultat
Page : index.php → 500 Internal Server Error Le log indique : Connection refused. Vérifier DATABASE_SERVER dans config.php et le port du conteneur MySQL. Le serveur MySQL était démaré dans un autre namespace Docker. Ajout de --link ou du network bridge a résolu la situation.
Ajouter le service depends_on: - db au fichier docker-compose.yml. Le conteneur démarre dans l’ordre correct.

5.2 Cas pratique 2 – “Notice: Undefined variable $currency_code”

Symptome Analyse Action Résultat
Affichage du prix du client : “undefined variable”. Appel à $currency_code dans htdocs/product/_picker.php sans vérification. Introduire un fallback : global $currency_code; $currency_code = $currency_code ?? ''; ou injecter via $_SESSION. L’avertissement disparait, aucune régression fonctionnelle.
Ajouter @E_NOTICE à error_reporting uniquement pour ce module. Meilleure maîtriser du niveau de bruit.

5.3 Cas pratique 3 – “Maximum execution time of 30 seconds exceeded”

Symptôme Analyse Action Réultat
Déploiement d’un gros lot d’articles → génération d’un PDF prend 35 s. Augmentation du nombre de lignes du tableau price. Modifier max_execution_time à 60 s dans php.ini ou externaliser le génération de PDF dans un cron (CLI). Le temps de réponse du front‑end reste < 2 s.

6. Conclusion

Diagnostiquer Dolibarr efficacement repose sur une méthode itérative :

  1. Recenser l’environnement (serveur, PHP, DB).

  2. Analyser les logs pour identifier le type exact d’erreur.

  3. Reproduire l’incident dans un environnement contrôlé.

  4. Appliquer ciblé les correctifs (patch PHP, mise à jour du schéma, réglage de permissions).

  5. Institutionnaliser le processus (CI/CD, monitoring, checklists) pour éviter que les mêmes erreurs ne réapparaissent. En suivant scrupuleusement cette démarche, les équipes de support peuvent :

  • Réduire de plus de 70 % le nombre de tickets récurrents. – Accélérer le temps de mise en production de nouvelles versions (déploiement « green‑blue »). – Améliorer la stabilité de l’application, garantissant ainsi la continuité du métier.

Vous avez désormais toutes les cartes en main pour mettre en place une méthode de support robuste qui minimise les erreurs Dolibarr dans vos installations, tout en assurant une culture d’excellence à travers vos équipes techniques. —

Pour toute question supplémentaire ou accompagnement personnalisé, n’hésitez pas à contacter l’équipe de support Dolibarr sur le canal officiel : #dolibarr (FreedNode) ou via le formulaire « Support » du portail GitHub.

Annexes

  • Annexe A – Script de nettoyage scripts/clean.php (exemple complet).

  • Annexe B – Exemple de docker-compose.yml pour un environnement complet.

  • Annexe C – Checklist CI/CD (Makfile).

(Les annexes peuvent être fournies sur demande ou intégrées dans le repository officiel de Dolibarr.)

Publications similaires