Mettre à jour Dolibarr sans casse : versions 16 à 24

Beaucoup d’entreprises restent des années sur la même version de Dolibarr, par peur de tout casser. Cette peur est justifiée, mais elle vise souvent la mauvaise cible. Ce n’est presque jamais Dolibarr lui-même qui casse. C’est ce que vous avez ajouté autour.

Pour le vérifier, 45 modules libres ont été installés sur des Dolibarr de test, puis mis à jour pour de vrai, version après version, jusqu’à la 24 : 280 passages de version au total. Le Dolibarr témoin, sans aucun module ajouté, est passé de la 16 à la 24 sans une seule erreur fatale. Toutes les pannes relevées venaient du code des modules externes. Et 13 de ces modules avaient déjà une erreur fatale avant toute mise à jour, sans que personne ne s’en soit aperçu.

Le risque est donc dans quatre endroits, toujours les mêmes :

• les modules externes, ceux du dossier custom/ ;
• la version de PHP de votre serveur ;
• les champs supplémentaires calculés ou conditionnés, et leurs filtres ;
• les réglages cachés et les variables de vos modèles de courriels et de documents, dont certains ont été renommés.

Pourquoi c’est le moment

Depuis le 1er septembre 2026, toute entreprise française assujettie à la TVA doit pouvoir recevoir des factures électroniques. L’obligation d’émettre arrive le 1er septembre 2027 pour les PME et les micro-entreprises. Le cœur de Dolibarr ne fabrique pas de facture électronique : il faut un module. Le module officiel, EInvoicing (version 1.3.0), s’installe à partir de Dolibarr 18 et PHP 7.0 d’après son code, mais le wiki du projet recommande Dolibarr 24 : c’est à partir de la 24 que le module s’installe depuis Dolibarr lui-même et que le format Factur-X est pris en charge. Si vous êtes en dessous, la mise à jour n’est plus un confort : c’est la première étape de la mise en conformité. La suite (le module, la plateforme agréée, les erreurs qui bloquent) est testée sur Dolibarr 24 dans Dolibarr et la facture électronique.

Avant : la liste de contrôle

1. Notez votre version exacte de Dolibarr et votre version de PHP. Les deux sont affichées dans les informations système, dans les outils d’administration.
2. Comparez votre PHP au tableau plus bas. Sous le minimum, l’assistant de mise à jour ne vous proposera rien. Au-dessus du maximum prévu, il affiche seulement un avertissement : ça peut fonctionner, mais personne ne l’a testé pour vous.
3. Faites la liste de vos modules externes, c’est-à-dire tout ce qui se trouve dans le dossier custom/. Pour chacun, vérifiez qu’il existe une version annoncée compatible avec la version visée, et procurez-la-vous avant de commencer. C’est la cause de panne numéro un.
4. Relisez vos champs supplémentaires calculés, leurs conditions d’affichage et leurs filtres. Plusieurs écritures anciennes ne sont plus acceptées (détail version par version plus bas).
5. Repérez les réglages cachés que vous avez posés dans la configuration avancée : quelques-uns ont été renommés ou ont même changé de sens.
6. Relisez vos modèles de courriels et vos modèles de documents ODT : certaines variables de substitution ont disparu.
7. Faites une sauvegarde complète, et vérifiez que vous savez la restaurer. Complète veut dire : la base de données, le dossier des documents, le fichier conf/conf.php et le dossier custom/. Une sauvegarde qu’on n’a jamais restaurée n’est qu’un espoir.
8. Répétez la mise à jour sur une copie avant de toucher à l’instance réelle. C’est la seule façon de voir les pannes avant vos utilisateurs.

Pour gagner du temps sur cette liste, le module gratuit Prêt pour la mise à jour fait la plupart de ces vérifications sans rien modifier : il lit le code de chaque module externe face à la version visée, contrôle PHP, la base de données, les champs calculés et les modèles ODT, puis vous remet un rapport. Il ne remplace ni la sauvegarde ni l’essai sur une copie.

Pendant : la procédure

Vous n’avez pas besoin d’installer chaque version intermédiaire : on installe directement les fichiers de la version visée. En revanche, la base de données, elle, passe par toutes les étapes : l’assistant de mise à jour vous propose les migrations une par une (16 vers 17, puis 17 vers 18, et ainsi de suite), et il faut les lancer toutes, dans l’ordre.

Sous Docker, avec l’image officielle, c’est différent : la mise à jour automatique saute des migrations si l’on passe plusieurs versions d’un coup. Lisez d’abord Mettre à jour Dolibarr sous Docker.

En SSH, sans l’assistant web, les mêmes migrations se lancent en ligne de commande, avec un piège qui bloque la deuxième étape sans aucune erreur : voir Mettre à jour Dolibarr en ligne de commande.

1. Prévenez les utilisateurs : personne ne doit travailler dans Dolibarr pendant l’opération.
2. Faites la sauvegarde complète décrite plus haut.
3. Remplacez les fichiers de Dolibarr par ceux de la nouvelle version, sans écraser conf/conf.php, le dossier custom/ ni le dossier des documents.
4. Supprimez le fichier install.lock, qui se trouve dans le dossier des documents. Tant qu’il est là, l’assistant refuse de s’ouvrir, et c’est voulu.
5. Ouvrez l’adresse de votre Dolibarr suivie de /install/, puis lancez chaque étape de migration proposée, jusqu’à la version visée.
6. Recréez install.lock à la fin. Sans lui, n’importe qui pourrait relancer l’installation.
7. Ouvrez les écrans que vous utilisez tous les jours : une facture, un devis, la génération d’un PDF, les écrans de vos modules externes.

Si quelque chose ne s’ouvre plus

Une page blanche ou une erreur 500 juste après une mise à jour vient, dans l’immense majorité des cas, d’un module externe. Le journal d’erreurs de PHP donne le fichier en cause : s’il est dans custom/, vous tenez le coupable.

Si l’écran des modules ne s’ouvre plus, on peut désactiver le module directement en base. Adaptez le préfixe des tables (llx_ par défaut) et le nom du module, et regardez d’abord ce que la requête va toucher :

SELECT name, value FROM llx_const WHERE name LIKE 'MAIN_MODULE_NOMDUMODULE%';
DELETE FROM llx_const WHERE name LIKE 'MAIN_MODULE_NOMDUMODULE%';

Pour revenir en arrière, restaurez toujours la base et les fichiers ensemble. Des fichiers anciens posés sur une base déjà migrée ne sont pas bloqués par Dolibarr, et c’est justement ce qui est dangereux : tout semble marcher, jusqu’au jour où un écran écrit dans une colonne qui a changé.

Le tableau des versions 16 à 24

Le PHP minimum est celui en dessous duquel l’assistant de mise à jour ne propose rien. Le PHP le plus récent prévu n’est qu’un seuil d’avertissement : au-delà, Dolibarr affiche une alerte mais ne bloque pas. Si l’un des modules retirés est encore actif chez vous, trouvez-lui un remplaçant avant la mise à jour.

Ce qui change, version par version

Seuls les changements qui peuvent toucher une entreprise qui utilise Dolibarr sont repris ici, pas ceux qui ne concernent que les développeurs du cœur.

• 16 : les actions sensibles exigent désormais un jeton de sécurité, y compris dans les liens. Un ancien module qui ne le transmet pas voit ses boutons refusés. Les déclencheurs nommés …_UPDATE deviennent …_MODIFY : un module ou un automatisme qui les attendait ne se déclenche plus.
• 17 : dans les champs supplémentaires calculés, l’objet courant s’écrit $objectoffield. Le réglage caché MAIN_LIST_ALLOW_NOTES devient MAIN_LIST_HIDE_NOTES.
• 18 : c’est la version qui a le plus cassé de modules externes sur notre banc d’essai (4 pannes sur 6), à cause de méthodes du cœur dont la forme a changé. Les clés sensibles des pages de réglages, comme les clés d’API, sont désormais chiffrées en base.
• 19 : les images Docker officielles passent de PHP 8.1 à PHP 8.2. Dans les conditions des champs supplémentaires, les variables $soc et $right ne sont plus disponibles.
• 20 : les filtres des champs supplémentaires de type lien doivent être écrits dans la nouvelle syntaxe de filtre universelle (champ:=:valeur), et non plus en SQL. Un module qui remplit case par case un tableau qu’il n’a pas déclaré ($this->liste['clé'] = …) perd ces valeurs. Ce point n’est pas dans le journal : constaté sur notre banc d’essai, puis reproduit.
• 21 : la variable __MEMBER_CIVILITY__ des modèles devient __MEMBER_TITLE__. L’extension json de PHP devient indispensable.
• 22 : le réglage caché STOCK_ALLOW_NEGATIVE_TRANSFER est inversé et renommé STOCK_DISALLOW_NEGATIVE_TRANSFER. GETPOST est interdit dans les conditions des champs supplémentaires.
• 23 : $obj ne fonctionne plus dans les champs calculés et les conditions ; écrivez $objectoffield, demandé depuis la 17. Le journal des modifications annonce aussi la fin de $object, mais il fonctionne encore en 23.0.4, 24.0.1 et 24.0.2 : remplacez-le sans attendre. La concaténation est désactivée par défaut dans les champs calculés.
• 24 : la variable __MYCOUNTRY_ID__ disparaît, remplacée par __MYCOMPANY_COUNTRY_ID__. La connexion à l’API par identifiant et mot de passe est coupée par défaut.
• 24, piège du journal inaltérable (module BlockedLog), si vous l’utilisez depuis une ancienne version : si sa clé est restée en clair en base, plus aucune facture ne peut être validée en 24.0.0 ou 24.0.1 (signalement #40153). Le message d’erreur affiche alors la clé en clair : n’en diffusez pas de capture. La 24.0.2, publiée le 2 octobre 2026 sur SourceForge mais pas encore annoncée sur dolibarr.org au 4 octobre, corrige ce cas. Testé : la validation refonctionne, et la clé, inchangée, est rechiffrée à la première facture validée. L’assistant de mise à jour, lui, n’y touche pas. D’ici l’annonce de la 24.0.2, faites vérifier ce point avant de passer en 24.

Comment ces informations ont été établies

• Les versions de PHP viennent du programme d’installation de chaque version (install/check.php), pas de la documentation, qui diverge parfois.
• Les modules retirés viennent de la comparaison des modules du cœur, version par version.
• Les changements viennent du journal officiel des modifications de Dolibarr.
• Les chiffres de pannes viennent de 45 modules libres réellement mis à jour sous Docker, avec l’assistant officiel, sur les images officielles de Dolibarr 16 à 24.

Ce tableau sera tenu à jour à chaque nouvelle version.

Se faire aider

Si vous préférez ne pas jouer cette opération sur votre outil de facturation, c’est exactement le forfait Mise à jour sécurisée : votre instance est copiée, la mise à jour est répétée à blanc sur la copie jusqu’à ce qu’elle passe, on vérifie vos factures, vos PDF et vos modules, et on ne bascule qu’ensuite. Si vous voulez d’abord savoir où vous en êtes, le diagnostic à 90 € fait le point sur votre version, votre PHP et vos modules, et son prix se déduit du forfait si vous le commandez ensuite.

À lire aussi

• Dolibarr et la facture électronique
• Sauvegarder et restaurer Dolibarr
• Erreur 500 ou page blanche dans Dolibarr
• Le fichier install.lock