Dolibarr : comment réussir template pour passer à l’échelle

Objectif : réussir à déployer, dupliquer et adapter vos modèles (templates) Dolibarr afin de soutenir la croissance de votre entreprise ou de votre activité de gestion, sans perdre en performance ni en qualité de rendu.

1️⃣ Pourquoi les templates sont cruciaux pour la montée en échelle ?

Situation Problème sans template structuré Solution apportée par un bon template
Multi‑sites / filiales Interfaces disparates, maintenance chaotique. Un design unique, paramétrable par société ou par site.
Multi‑langues Traductions éparpillées, erreurs de cohérence. Gestion centralisée des chaînes de langue, réutilisables à l’infini.
Évolution fréquente des produits Modifications « à la main » sur chaque fiche. Modèles de fiches personnalisables (templates de commercial, produit, fiche‑client).
Performance & SEO Pages lourdes, temps de chargement élevé. Templexes légers, basés sur des partials et des caches.
Intégration à d’autres outils Connexions APIs ad‑hoc, bugs d’injection. Architecture modulable : hooks, API REST, Overloaders.

En résumé, un template bien conçu devient un levier d’abstraction qui vous permet de :

  • Réutiliser du code (HTML/JS, fonctions PHP)

  • Centraliser la configuration (paramètres, chemins, langues)

  • Gérer les changements à grande échelle (déploiement, mise à jour, rollback)

2️⃣ Architecture des Templates Dolibarr

Dolibarr sépare les présentations (templates) du code métier.
La structure officielle (v17‑23) ressemble à :

/htdocs/

   /dolibarr/

      /core/               ← cœur métier

      /htdocs/

         /css/

         /js/

         /fonts/

         /img/

         /templates/

            /html/

               /com/

               /facture/

               /client/

               …

            /css/

            /js/

            /images/

Points clés à retenir

Élément Rôle Astuce pour la scalabilité
{$mode} / {$param} Contrôle du mode d’affichage (list, edit, view). Définissez un mode « écran large » par défaut pour les grands écrans, et créez des variantes mobile.
tplKey($value) Fonction générique d’accès aux clés de $_PARAM. Centralisez les clés ; évitez les dépendances global.
load() (ex: load() de ticket) Charge les modèles de données. Utilisez les interfaces Cadaster ou Product pour abstracter les entités et faciliter la migration.
nav.php Barre de navigation principale. Paramétrisez la visibilité/ordre des menus par plugin ou par société.
theme Répertoire de thème complet (HTML, CSS, JS). Créez un thème global que chaque société peut sur‑charger par un fichier local.css ou local.js.

3️⃣ Étapes pratiques pour créer un template scalable

Prérequis : vous avez Dolibarr installé, accès en mode développeur (PHP 8+, MySQL 8+).

3.1️⃣ 1️⃣ Créer un thème « base » dédié à l’échelle

# Dans /htdocs/dolibarr/templates/

mkdir -p myScale/template

cd myScale/template

  • Nom du répertoire : myScale (ou scale).

  • Fichiers obligatoires :

    • theme.conf.php – décrit le thème, version, auteur.

    • css/style.css – feuilles de styles communes.

    • js/main.js – scripts JS partagés.

    • templates/html/* – dossiers com, facture, product… contenant vos partials (voir 3.3).

Exemple minimal de theme.conf.php

<?php

$themeconf = new StdClass();

$themeconf->name          = 'myScale - Template Scalable';

$themeconf->version       = '1.0.0';

$themeconf->author        = 'Votre Entreprise';

$themeconf->description   = 'Template prêt à supporter multi‑sites et multi‑langues.';

$themeconf->compatibility = ['Dolibarr' => '21.0'];

?>

3.2️⃣ 2️⃣ Définir des templates de base (partials)

Dolibarr utilise le système de partials (fragments de template).
Créez des partials réutilisables, par exemple :

/templates/html/com/

   ├─ partials/

   │   ├─ header.tpl.php

   │   ├─ footer.tpl.php

   │   ├─ nav.tpl.php

   │   └─ product-card.tpl.php

   └─ com.php          ← page catalogue produits

product-card.tpl.php (exemple) :

<?php

// $product est un objet $object (ex: $object->fetch($id))

?>

<div class="product-card" data-id="<?= $product->id ?>">

   <img src="<?= $product->image_path ?>" alt="<?= htmlspecialchars($product->label) ?>">

   <h3><?= $product->label ?></h3>

   <p class="price"><?= price($product->price) ?></p>

   <button class="quickview">En savoir +</button>

</div>

Astuce d’échelle : Conservez les noms de partials globaux (partials/*.tpl.php).
Ainsi, chaque page (catalogue, devis, fiches client…) pourra inclure le même ensemble de fragments, garantissant cohérence et maintenabilité.

3.3️⃣ 3️⃣ Exploiter les hooks de surcharge

Dolibarr propose des overloaders (ou overload de classes) qui vous permettent de remplacer une fonction sans toucher au dépendance du noyau.

// Exemple : surcharger la fonction buildobserves des factures

class Overload_Hook extends Hook {

    public function buildobserves(&$hookmassignment) {

        // Ajout d’un champ supplémentaire (ex: numéro de projet)

        $hookmassignment['extra'] = '<input type="text" name="project_code" placeholder="Code Pro">';

        return '';

    }

}

Utilisation pour le scaling : créez un fichier extra_fields.php dans votre thème, puis incluez‑le via require_once dans le répertoire overload.
Vous pouvez ainsi enrichir toutes les structures de données (commandes, devis, utilisateurs) sans toucher au cœur du code officiel.

3.4️⃣ 4️⃣ Gestion de la multi‑site via les levier de configuration

Dolibarr possède le concept de “société” (ou entity):

  • setup → companies → chaque société possède son propre dossier htdocs/<company>/.

  • Les templates peuvent être sur‑chargés par une simple variable $conf->global->template_dir.

Exemple de logique flexible

$company = $_SESSION['user']->entity->id; // ID de la société connectée

$template_path = "/htdocs/dolibarr/templates/company_$company/";

if (is_dir($template_path)) {

    $conf->global->template_dir = $template_path; // Redéfinit le thème actif

}

Résultat : chaque filiale peut disposer de ses propres imagery, couleurs, logo, tout en gardant les partials partagés via le thème central (myScale).

3.5️⃣ 5️⃣ Sécuriser les limites de performance

Problème potentiel Solution scalabilité
Requêtes multiples sur les mêmes tables Utilisez le cache de Dolibarr ($conf->global->cache_ldap) ou implementez votre own Cache (PSR‑6).
JS/CSS lourd sur chaque page Regroupez les scripts dans js/bundle.min.js avec Webpack ou Gulp, et servez un CSS minimalisé (style.min.css).
Blocs de rendu répétés (ex: navigation) Cachez les fragments déjà rendus grâce à $_SESSION['cache_nav'].
Appels API externes (paiement, ERP) Mettez en place Guzzle avec timeout et circuit‑breaker, ou utilisez les hooks paymentmodules pour centraliser les appels.

4️⃣ Bonnes pratiques résumées

✅ Pratique Pourquoi
✅ Nommer les partials de façon sémantique (product-card.tpl.php, invoice-summary.tpl.php). Facilite la recherche et la réutilisation.
✅ Versionner vos templates avec Git (branches dev, release). Reproduire les changements sur les environnements de pré‑production.
✅ Documenter chaque partial avec les TODO ou NOTE dans les commentaires PHP. Gain de temps lors du scaling团队.
✅ Isoler les styles avec BEM/SCSS ou CSS‑Modules. Empêche les collisions entre les pages de différents modules.
✅ Paramétrer les traductions via $_MODULES[_MODULE][_LANG]. Ajoute une nouvelle langue sans toucher au HTML.
✅ Limiter les dépendances globales : privilégiez les paramètres $conf et les surcharges plutôt que les variables globales. Évite les effets de bord lors des déploiements multiples.
✅ Utiliser les tests unitaires (phpunit) sur les fonctions overload (ex: getExtraFields). Garantit que vos ajouts ne cassent pas les mises à jour futures.
✅ Surveiller les logs (error_log, dolibarr_log); créez un fichier logs/scale.log dédié aux événements de scaling. Détecte rapidement les goulets d’étranglement.
✅ Planifier des revues de performance tous les 3‑6 mois (profilage avec Xdebug). Anticiper les besoins de montée en charge.

5️⃣ Checklist rapide pour votre premier déploiement à grande échelle

  1. Créer le thème de base (myScale) – config theme.conf.php.

  2. Développer les partials courants (header, footer, nav, product-card).

  3. Surcharger les classes nécessaires (ex: Hook, Product, Invoice).

  4. Intégrer les champs personnalisés (ex: project_code) via un plugin / overload.

  5. Configurer la réécriture du thème par société ($conf->global->template_dir).

  6. Déployer les assets minifiés (style.min.css, bundle.min.js).

  7. Activer le cache : $conf->global->cache_ldap = 1; + dolibarr_cacheroot (/dolibarr/cache).

  8. Tester la navigation sur différents navigateurs (desktop, mobile).

  9. Faire un benchmark (page load < 1 s sur 100 visiteurs simultanés).

  10. Documenter le processus dans un wiki d’équipe et le placer sous versionning.

6️⃣ Conclusion

Un template bien pensé dans Dolibarr n’est pas un simple « look ». C’est le pilier architectural qui vous permet d’étendre votre solution à plusieurs filiales, langues, modules et flux de travail, sans devoir toucher à chaque page au moment d’une évolution.

En suivant les étapes ci‑dessus — définir un thème central partagé, créer des partials réutilisables, exploiter les overloaders et hooks, et appliquer des stratégies de mise en cache—Vous disposerez d’une base solide pour passer à l’échelle tout en conservant performance, sécurité et maintenabilité.

Prêt à multiplier vos opérations ?
Commencez par créer votre premier template myScale ; vous serez surpris de la rapidité avec laquelle vous pourrez déployer de nouveaux modules, intégrer des interfaces externes et servir une communauté d’utilisateurs grandissante.

Author: [Votre Nom] – Architecte de solutions open‑source Dolibarr
Date : 02 Novembre 2025

Sources complémentaires

  • Documentation officielle Dolibarr – "Theming & Overriding"

  • Blog : Scaling Dolibarr with Multi‑Store Templates (2024) – cas d’étude d’une PME française.

  • GitHub : dolibarr/template-myScale – dépôt modèle (licence MIT).

Bon codage ! 🎯

Publications similaires