Par [Nom du rédacteur], 3 novembre 2025 —
1. Introduction
Dolibarr est un ERP/CRM léger, open‑source et très apprécié des PME pour sa simplicité d’utilisation et sa modularité. En production, la performance et la fiabilité du système deviennent des enjeux majeurs : temps de réponse, disponibilité, et surtout la minimisation des erreurs qui peuvent impacter les processus métiers.
L’un des leviers les plus puissants, mais souvent sous‑exploité, est le cache : il permet de réduire le nombre de requêtes SQL, d’éviter les recompilations de templates et de diminuer la charge du serveur web. Cet article passe en revue les différentes couches de cache de Dolibarr, propose des configurations concrètes et détaille les bonnes pratiques pour éviter les bugs courants en environnement de production.
2. Architecture de Dolibarr et points d’attention
| Niveau | Description | Conséquence d’un mauvais réglage |
|---|---|---|
| PHP | Exécution des scripts, compilation des templates Smarty, inclusion des classes. | Scripts lents, “Class not found”, erreurs de parsing. |
| MySQL / PostgreSQL / SQLite | Stockage des données, exécution des requêtes. | Conflits de verrouillage, lenteurs, erreurs de requête. |
| Cache interne | Stockage temporaire d’objets PHP (tables de hachage, fichiers). | Redondance de requêtes, surcharge mémoire. |
| Cache d’affichage | Images, CSS, JS mis en cache côté navigateur ou via reverse‑proxy. | Affichage obsolète, erreurs de design, problèmes de validation. |
| Cache de sessions / Cookies | Gestion des identifiants d’utilisateur. | Perte de connexion, sessions corrompues. |
3. Le cache interne de Dolibarr
3.1. Mécanisme de cache natif
Dolibarr utilise deux types de caches :
- Cache de dictionnaire (
$dict) : stocke la traduction des libellés. - Cache des états/menus (
$objects,$hookenv) : garde en mémoire les objets déjà chargés et les résultats d’appels à$hook->hook()ou$_SESSIONd’évènements.
Ces caches sont généralement sauvegardés dans le répertoire dolibarr/cache/ sous forme de fichiers .cache.php.
3.2. Activation du cache en production
Pour activer le cache : « `php
$hook->loaded = 1; // force le cache dès le démarrage
define(‘USE_CACHE’,1); // active le mécanisme global
> **Astuce** : ajoutez ces deux lignes dans `config.php` (ou créez un fichier `local.inc.php`) avant toute inclusion des classes Dolibarr.
### 3.3. Période d’expiration
Le cache doit être rafraîchi lorsqu’une donnée métier change :
```php
// Exemple : rafraîchir le cache après une sauvegarde
if ($status == 1) {
dolCacheClean('ALL'); // vide le cache complet
}4. Cache externe : les options les plus efficaces
| Solution | Où l’appliquer | Avantages | Mise en œuvre rapide |
|---|---|---|---|
| Reverse proxy (Varnish / Nginx FastCGI Cache) | Front‑end web | Cache HTTP complet, réduction du nombre de requêtes PHP | Configurer fastcgi_cache_path et inclure proxy_cache |
| OPcache (PHP) | Serveur PHP | Cache byte‑code, améliore la vitesse de script | Activer via php.ini : opcache.enable=1 |
| APCu (User‑Data Cache) | PHP (scripts CLI ou API) | Cache clé‑valeur en mémoire | extension=apcu.so + apc.enable_cli=1 |
| Cache CDN | Assets statiques (CSS/JS) | Distribution mondiale, réduction de la latence | Utiliser Cloudfront, Cloudflare, etc. |
| Database query cache | MySQL/PostgreSQL | Cache des requêtes fréquentes | Activer query_cache_type (MySQL) ou shared_buffers (PostgreSQL) |
Contrôle : après chaque modification, purgez le cache avant de vérifier le bon fonctionnement (
dolCacheClean('ALL')ousystemctl restart nginx).
5. Bonnes pratiques pour réduire les erreurs en production
5.1. Sécuriser les réglages de cache
| Point | Action | Pourquoi |
|---|---|---|
| Permissions de fichiers | chmod 750 dolibarr/cache ; chown www-data:www-data |
Empêche les écritures arbitraires par des utilisateurs non privilégiés. |
| Exclure le cache des backups | Ajouter cache/ dans le .gitignore ou le script de sauvegarde |
Evite de restaurer des caches corrompus. |
| Désactiver le cache en dev | define('USE_CACHE',0); dans dev.inc.php |
Facilite le débogage (les changements sont immédiatement visibles). |
| Limiter la taille du cache | define('MAX_CACHE_SIZE', 1024); // en Mo |
Empêche une consommation excessive de disque. |
5.2. Gestion des modifications données
- Utiliser les hooks :
$hook->addFunctionHeader('refreshCacheAfterUpdate', 'function refreshCacheAfterUpdate(&$params){
dolCacheClean('ALL');
}'); - Déclencher un rafraîchissement manuel après les imports de données (CSV, API, scripts batch).
- Planifier une tâche cron pour nettoyer le cache à intervalles (ex. 00h00) si le volume de changements est faible.
5.3. Monitoring et alertes
| Outil | Analyse | Exemple de règle |
|---|---|---|
| Grafana + Prometheus | Tracking de cache_hits et cache_misses. |
alert: HighCacheMisses → > 30 % de cache_miss pendant 5 min. |
| ELK / Graylog | Centralisation des logs PHP (erreurs 500, warnings). | Filtrer sur DolibarrException + seuil de fréquence. |
| UptimeRobot / Zabbix | Vérification de la disponibilité du service. | Timeout > 5 s déclenche alerte. |
5.4. Tests automatisés avant mise en prod
| Type de test | Description | Outils recommandés |
|---|---|---|
| Unitaires | Tests de fonctions utilitaires (cache, hooks). | PHPUnit, avec bootstrap.php qui charge Dolibarr en mode « test ». |
| Intégration | Simuler des scénarios de mise à jour de données. | Behat ou Prophecy. |
| Charge | Mesurer le nombre de requêtes servies avant/network saturation. | ab (Apache Bench) ou wrk. |
| Sécurité | Scanner les vulnérabilités liées à la configuration du cache (ex. injection de cache). | OWASP ZAP, Nuclei. |
6. Checklist de déploiement en production
| ✅ | Action | Commentaire |
|---|---|---|
| 1 | Activer USE_CACHE=1 dans config.php. |
Assure le cache interne. |
| 2 | Configurer OPcache (opcache.enable=1, opcache.memory_consumption=256). |
Accélère le script. |
| 3 | Mettre en place Varnish/Nginx FastCGI Cache avec max_size 200M. |
Cache HTTP. |
| 4 | Vérifier les permissions (750 pour cache/). |
Sécurité des fichiers. |
| 5 | Purger le cache après chaque mise à jour du code. | dolCacheClean('ALL'). |
| 6 | Surveiller les métriques (hits/misses, latence). | Grafana/Prometheus. |
| 7 | Planifier un cron de nettoyage (ex. 0 2 * * * /path/to/php dolibarr/scripts/clean_cache.php). |
Prévenir la fuite de disque. |
| 8 | Documenter les procédures de rollback. | Permet de revenir rapidement à un état stable. |
7. Exemple de configuration concrète
7.1. config.php minimal en prod
« `php<?php
// ——————————————————————-
// Configuration de production
// ——————————————————————-
$conf[‘env’] = ‘prod’;
$conf[‘use_cache’] = 1; // Active le cache interne
$conf[‘cache_dir’] = ‘/var/www/dolibarr/dolibarr/cache’;
$conf[‘cache_ttl’] = 3600; // 1h avant expiration$conf[‘opcache_enabled’] = 1; // pour les versions >= 7.4
$conf[‘fastcgi_cache’] = ‘/var/cache/nginx/dolibarr_fastcgi’;
$conf[‘max_cache_size’] = 512; // Mo
?>
### 7.2. Config Nginx avec FastCGI Cache
```nginx
location ~ \.php$ {
include fastcgi_params;
fastcgi_pass unix:/run/php/php-fpm.sock;
fastcgi_cache /var/cache/nginx/dolibarr_fastcgi;
fastcgi_cache_key $scheme$request_method$uri;
fastcgi_cache_valid 200 302 10m;
fastcgi_cache_use_stale error timeout updating;
fastcgi_cache_lock on;
fastcgi_no_cache $is_args$args $request_method;
}7.3. Script de nettoyage (cron)
<?php// clean_cache.php
require_once '/var/www/dolibarr/htdocs/config.php';
dolCacheClean('ALL');
echo "Cache vidé le ".date('H:i:s').PHP_EOL;
?>Crontab :
0 3 * * * /usr/bin/php /var/www/dolibarr/scripts/clean_cache.php >> /var/log/dolibarr_clean_cache.log 2>&18. Réduire les erreurs fréquentes liées au cache | Erreur typique | Cause probable | Solution immédiate |
|—————-|—————-|——————–|
| Page affichée avec des données périmées | Le cache n’a pas été vidé après une sauvegarde ou un changement de configuration. | Exécuter dolCacheClean('ALL') ou purger via le panneau d’administration → Administration → Maintenance → Clear Cache. |
| Erreur 500 après mise à jour du code | Fichiers cache/*.php non régénérés ou permissions erronées. | Supprimer le répertoire cache/ puis recréer les permissions. |
| Session expirée aléatoirement | Cache de sessions partagé avec apc.serialize et nettoyage trop fréquent. | Augmenter apc.ttl ou configurer un cache dédié (Redis). |
| Timeout de requête MySQL | Nombre excessif de requêtes non indexées, stockées dans le cache lent. | Activer query_cache_type=ON (MySQL) ou ajouter des index sur les tables concernées. |
| Cache CDN incompatibilité avec les sessions | Les assets CDN ne sont pas versionnés, les objets statiques restent inchangés. | Ajouter un hash ou un timestamp au nom du fichier (style.css?v=20251103). |
9. Conclusion
Le cache est le véritable catalyseur de performance dans un environnement de production : il diminue les temps de réponse, allège la charge du serveur et améliore l’expérience utilisateur. Tuttavia, son utilisation doit être accompagnée d’une gestion rigoureuse : configuration adéquate, nettoyage automatisé, monitoring en temps réel et bonnes pratiques de déploiement.
En suivant les étapes et la checklist présentées ci‑dessus, vous pourrez :
- Réduire drastiquement les latences grâce aux couches de cache (OPcache, FastCGI, CDN).
- Éviter les erreurs classiques liées aux données périmées ou aux permissions.
- Faciliter la maintenance avec des scripts de nettoyage, des alertes et des tests automatisés.
En adoptant une approche « cache‑first, monitor‑driven, clean‑up‑regularly », Dolibarr passera d’un simple outil de gestion à une plateforme fiable, résiliente et prête à soutenir la croissance de votre entreprise.
Bonne optimisation ! N’hésitez pas à partager vos retours d’expérience ou vos configurations spécifiques dans les commentaires.