Documentation du module DocDB

Objectif
Principe de fonctionnement
Limitations
Différences
Avantages et Inconvénients
Pérennité
Utilisation par des modules tiers
Tests et mesures réalisés

Conditions des tests
Comparatif performances
Jeux de caractères

Référence des commandes
Étendre docDB
Dépannage
Licence

Objectif

Dolibarr offre une GED (gestion électronique de documents) intégrée.
Ces documents sont téléchargés par les utilisateurs sur le système de fichiers du serveur. Certains documents sont générés comme par exemple les factures, stockées elles aussi dans la GED. Par ailleurs, les données de gestion sont localisées dans une base de données. On parle ici de toutes les données des formulaires : numéros des facture, noms des clients, montants, libellés, etc. Le module docDB permet de stocker les documents dans la base de données, plutôt que d'utiliser le système de fichiers du serveur.

Principe de fonctionnement

Dolibarr est codé en langage PHP. Ce langage fournit au programmeur une quantité de fonctions qui lui permettent de connaître et d'agir sur l'environnement du programme. Par exemple la fonction echo affiche un texte sur l'écran du navigateur, ou strpos donne la position d'une chaîne de caractères dans une autre, ou encore sort va trier un tableau de valeurs. Ces fonctions sont très nombreuses et couvrent la quasi totalité des problèmes auxquels sont confrontés les développeurs.
Le code PHP d'une application est contenu dans des fichiers, souvent appelés scripts, qui sont utilisés par le serveur web au moment exact où l'utilisateur fait une requête dans son navigateur. Sans trop rentrer dans les détails, l'utilisateur clique ou actionne son clavier, le navigateur envoie une requête, le serveur analyse les scripts correspondants, et renvoie les résultats produits par l'exécution de ces scripts.

Pour ce qui concerne les documents GED, Dolibarr utilise des fonctions dédiées à la gestion des fichiers. Citons par exemple opendir, readdir ou readfile qui lisent des répertoires ou des fichiers contenus sur le disque du serveur, ou aussi exif_read_data, imagejpeg, ou getimagesize qui traitent les images. Il y en a bien d'autres, j'en recense 99 au moment ou j'écris ces lignes.
Ce système fonctionne bien, mais offre un certain nombre de limitations qui sont entre autres celles des systèmes de fichiers utilisés pour le stockage. Ces systèmes n'offrent pas la souplesse et la puissance des bases de données pour la conservation et l'accès des documents.
Il n'est pas simple par exemple de mettre en place une réplication d'un serveur à l'autre. La réplication permet de conserver en temps réel deux espaces de données exactement identiques, ce qui est un avantage puissant pour la sécurité et facilite les sauvegardes périodiques. Ne pas l'utiliser de nos jours implique de fonctionner dans un mode qui devient de plus en plus archaïque et qui consiste à tolérer la perte d'une certaine quantité de données en cas d'accident sur un serveur.
Il n'est pas très aisé non plus de déployer et de maintenir deux systèmes de gestion de données distincts. On parle des documents sur le système de fichiers d'un côté, et des données de gestion sur la base de données de l'autre. Un bug, un incident, une opération malheureuse et pas forcément consciente sur l'un des deux systèmes, et les données seront désynchronisées. Encore une fois cela fonctionne, mais n'a pas été aisé à développer et ne serait pas facile à faire évoluer.
Enfin, les jeux de caractères ne sont pas traités de la même façon dans les deux systèmes, ce qui implique des avatars et des limitations à propos des noms des documents.

Alors pourquoi Dolibarr a-t-il été codé ainsi ? La réponse reviendrait assez logiquement aux développeurs initiaux, mais on peut postuler qu'à l'époque les bases de données ne géraient pas très bien les gros volume unitaires de données. Ceux-ci sont stockés dans ce qu'on appelle des blob, qui ne sont pas apparus très tôt dans l'histoire des bases de données, alors qu'au contraire les gros fichiers ont été une problématique réglée dès le début dans la conception des systèmes de fichiers.

C'est l'idée qui est à l'origine de docDB : le traitement des blob est au point de nos jours et on a donc avantage à l'utiliser dans Dolibarr.

Il n'a aucunement été question de réécrire toute une partie importante de Dolibarr. D'abord, ceci ne laisserait pas le choix aux techniciens chargés du déploiement. Ensuite, le bon sens impose d'éprouver docDB sur une période de temps suffisamment importante. Enfin, parce que ce serait beaucoup de travail.
La solution réalisée se contente de modifier les fonctions php qui concernent la gestion des documents et de les remplacer par des fonctions donnant des résultats équivalents aux programmes, mais faisant autre chose en réalité. Par exemple opendir est remplacé par opendir_Bypass. Là ou opendir ouvrait un répertoire sur le disque, opendir_Bypass va ouvrir et lire une table de la base de donnée. C'est ce qu'on appelle un émulateur. Les fonctions initiales sont émulées par les fonctions d'émulation. Elles produisent les mêmes résultats, mais avec une méthode sous-jacente totalement différente, et on agit de même pour toutes les fonctions qui concernent les documents. Une terminologie plus moderne parlerait peut-être de programmation orientée aspects.
Concrètement, une fois docDB activé, le répertoire des documents est presque complètement inutile. Il ne contient plus que la log des évènements Dolibarr et le célèbre install.lock, ainsi que le sous-répertoire api nécessaire à certaines opérations. En tout cas, il ne stocke plus rien, les documents peuvent être supprimés. Ils sont maintenant stockés dans deux tables (llx_doc_data et llx_doc_directory) et sont donc associés de façon naturelle à toute opération de production concernant la base de données.

On active docDB avec deux scripts (docDBmigrateScripts.py et docDBmigrateFiles.py) à utiliser une fois chacun. Le premier modifie le code des scripts Dolibarr, et le deuxième pompe le répertoire des documents pour le charger dans la base de données. Ces deux opérations sont réversibles, ce qui permet de tester et de revenir en arrière si nécessaire.
Le détail de la procédure est exposé dans le document d'installation install-fr_FR.html livré avec le module. L'opération est assez simple et rapide pour qui dispose d'un minimum d'expérience de la ligne de commande.

Limitations

En l'état actuel, docDB impose certaines limitations, heureusement peu nombreuses.

La principale est qu'il ne fonctionne qu'avec MySQL, autrement dit MariaDB. Il serait tout-à-fait possible d'écrire l'adaptation pour PostgreSQL, mais j'attends qu'un utilisateur en exprime le besoin. La réalisation ne va pas de soi car le principe de gestion des blobs de PostgreSQL est différent de celui exploité dans MySQL/MariaDB. Pour faire court, on ne peut pas mettre de blob dans n'importe quelle table, une gestion différente est nécessaire.

Par ailleurs, il existe un cas où les performances sont assez mauvaises. Il se produit uniquement sous Windows, et à condition que le serveur soit saturé. Si la mémoire est pleine et que le système se met à paginer, alors la gestion des documents sera très ralentie. Dans la pratique, ceci n'a guère d'importance, car c'est l'ensemble du système qui est lent, et de toutes façons une action correctrice est nécessaire pour exploiter Dolibarr dans des conditions acceptables. J'ai rencontré le cas au cours des tests, les serveurs étant installés sur des machines virtuelles avec peu de mémoire. Notons que ceci ne se produit pas sous Linux.

Au chapitre des limitations mineures, les dossiers vides ne sont pas recréés après un retour arrière de migration. Si vous migrez vers docDB, et que par la suite, après avoir supprimé les documents sur le disque, vous utilisez l'option --reverse pour recréer ces mêmes documents, seuls les dossiers non vides seront générés. Aucune importance en réalité, Dolibarr sait créer un dossier quand il en a besoin, et cela ne gênera pas le fonctionnement.

Et voilà, c'est tout. L'ensemble des fonctions de Dolibarr sont accessibles de façon transparente, et c'est bien le but recherché.

Différences

Il existe tout de même une légère différence de fonctionnement, qui est la suivante : quand on demande la suppression d'un dossier dans la GED, Dolibarr demande confirmation en prévenant si des documents sont contenus dans ce dossier, et en signalant qu'il seront détruits. Mais si l'on confirme, la suppression échoue, et on doit alors supprimer les contenus un à un.
Si docDB est activé, la suppression de toute l'arborescence fonctionne, après confirmation évidemment.

Avantages et Inconvénients

Le fait que vous activiez docDB signifie que vous n'aurez plus qu'une gestion technique pour exploiter votre ERP favori.
À chaque fois que la question des données se pose, le technicien chargé de l'exploitation s'occupe de la base de données et rien d'autre. En ce qui me concerne, je trouve cela appréciable. C'est le cas lors de la mise en place et de la gestion des sauvegardes et des restaurations. C'est aussi le cas pour toute réflexion au sujet de la sécurité.
Ceci diminue de façon non négligeable le temps passé et aussi le risque d'erreur.

Par ailleurs, il devient possible de profiter pleinement de certaines possibilités de la base de données. Pensons notamment à la réplication, qui permet de maintenir simultanément plusieurs copies identiques d'une même base. Ou aux sauvegardes incrémentielles, beaucoup plus difficiles à réaliser et si utiles pour garantir une sécurité maximale.

Il y a aussi l'aspect transactionnel. Quand vous faites une série de requêtes et de mise-à-jour sur une base sql, elles s'inscrivent dans ce qu'on appelle une transaction. Cette transaction vous garantit que toutes ces requêtes et mises-à-jour seront effectuées en une fois, ou pas du tout. Autrement dit, votre base reste cohérente quoi qu'il arrive en cas d'échec d'un programme ou d'un matériel. Dans le cas standard de Dolibarr, ceci peut ne pas être complètement effectif. On peut très bien imaginer des choses assez désagréables comme une sauvegarde pas tout-à-fait complète, ou un ensemble de données pas tout-à-fait synchronisé. Dans la réalité, ce cas devrait se produire très rarement, mais l'idée n'est quand même pas très confortable.

Enfin, pour ce qui concerne le développement Dolibarr, on constate qu'il est difficile de programmer des opérations de masse concernant les documents. Elles ne s'inscrivent pas dans une logique normale de programmation de base de données, et la double réflexion s'impose à chaque fois, ce qui augmente la quantité de travail de programmation et réduit fatalement la faisabilité des nouvelles fonctions à développer.

L'intérêt du module docDB est de permettre justement que les documents soient stockés dans la base avec le reste des autres données.
Transactionnel, réplication, sauvegardes incrémentielles, tout ceci devient plus facile à réaliser.

Pérennité

Une fois activé DocDB, n'est rien d'autre qu'un seul script PHP. Il utilise des fonctions standards, figurant à la documentation officielle PHP. La licence sous laquelle il est diffusé permet d'en disposer pleinement (voir ci-après : licence).
La question se pose de son évolution si une nouvelle fonction apparaissait dans Dolibarr qui ne soit pas gérée dans docDB.
On ne peut l'exclure, et dans ce cas il faudrait étendre docDB (voir ci-après le guide de développement : étendre docDB). Je m'en chargerai bien entendu, mais je ne suis pas éternel. Cependant, on peut affirmer avec certitude qu'un logiciel libre développé par un seul programmeur disparu est plus facile à faire évoluer qu'un progiciel écrit par l'équipe importante d'une société venant de faire faillite. Nous le savons bien, nous autres utilisateurs de Dolibarr, et c'est une des choses qui nous plaît dans ce logiciel.
Par ailleurs, les scripts de migration sont écrits en langage python (www.python.org), un autre langage de script, largement connu et diffusé, au moins aussi important que PHP. Pourquoi avoir choisi python ? Simplement par inclination personnelle. J'estime qu'il est plus pratique pour réaliser ce genre d'opérations. La question d'une évolution de Dolibarr est assez déconnectée du travail réalisé par ces scripts, qui ne sont pas utilisés en production, mais seulement quand on réalise une migration, une opération que l'on planifie à l'avance et jamais de façon inopinée et contrainte. Par ailleurs, il sont également librement accessibles et modifiables. Leur fonctionnement est certes plus complexe que la partie PHP, mais somme toute rien de si ésotérique. Un grand nombre de programmeurs venant de tous horizons serait capable de maintenir et modifier ces scripts.

Utilisation par des modules tiers

Si vous utilisez un module Dolibarr qui n'est pas inclus dans les modules standard, la conséquence première est qu'il n'a pas probablement pas été testé avec docDB, et donc, vous devez vous assurer que tout fonctionne bien.
Voici une des procédures possibles que vous pouvez réaliser si vous êtes dans ce cas :
- installez un environnement de test. Il ne s'agit pas de tester directement en production. Si c'est votre idée, votre confiance m'honore, mais sincèrement, il est préférable d'être prudent... Cet environnement s'installe de la façon classique, migration docDB inclue, et vous aurez soin d'injecter vos données dans la base, documents compris
- installez votre module, à priori dans htdocs/custom
- utilisez la commande docDBmigrateScripts.py pour migrer votre module. La commande verra uniquement les modifications à faire dans le module, puisque les scripts Dolibarr auront déjà été migrés. N'hésitez pas à positionner l'option --dry-run lors d'un premier essai pour bien visualiser ce qui va se passer
C'est tout ce que vous devez faire.
Si votre module ne gère pas les documents GED, il y a de fortes chances qu'il ne soit pas impacté du tout. Et s'il gère directement les documents sans passer par les fonctions de Dolibarr, certains de ses scripts seront modifiés, mais il serait assez improbable qu'ils rencontrent un problème à l'exécution.
On ne peut jurer de rien, particulièrement en informatique. Si vous rencontrez un problème, n'hésitez pas à me solliciter par le formulaire de contact sur le site www.apia-asso.fr

Liste des modules testés avec Dolibarr

Les modules figurants ci-après ont été testés avec succès. Si vous souhaitez que le vôtre figure dans cette liste, utilisez le formulaire de contact sur le site www.apia-asso.fr pour m'envoyer son nom, la version testée, la date du test et votre nom ou alias afin que je les insère dans le tableau ci-après.

Module	Version	Date du test	Nom du testeur
Scanner	17.0.0	15/05/2023	jmbc

Tests et mesures réalisés

Les tests ont été réalisés avec Dolibarr 17.0.0 le 15 mai 2023.

Liste des opérations inclues dans le protocole :

- migration docDB

- comparaison docs initiaux / après reverse

- ajout/retrait logo

- caractères accentués dans le nom d’un document

- vérification génération pdf factures clients

- accès documents thumbnail

- accès documents document complet

- stockage document tiers

- recadrage document tiers

- stockage document projets

- espace GED : création dossier

- espace GED : chargement fichier

- espace GED : création sous-dossier

- espace GED : suppression dossier/sous-dossier

- espace GED : renommer dossier/sous-dossier/dossier avec fichiers

- espace GED : renommer fichier avec accents

- espace GED : arborescence automatique - développement

- espace GED : arborescence automatique - aperçu

- espace GED : arborescence automatique - accès factures clients

- espace GED : arborescence automatique - accès projets

- espace GED : arborescence automatique - accès tiers

- suite test - création 10 clients par API

- suite test - création 100 factures par client

- suite test - téléchargement 100 documents par client

- accès documents après reverse

Conditions des tests

Quatre machines virtuelles, deux avec docDB (Linux et Windows), deux avec Dolibarr natif, sans docDB (Linux et Windows). Les tests sont faits en parallèle sur chaque système.
Systèmes d'exploitation employés : Linux Debian 11, Windows 10 pro 1909
Base de données : MariaDB 10.5.18 (Linux), MariaDB 11.1 x64 (Windows)
PHP : 7.4.33 (Linux et Windows)
Python : 3.9.2 (Linux), 3.11.3 (Windows)
Mémoire RAM : 2GO (Linux), 4GO (Windows)

Comparatif performances

Pas de différence mesurable entre chacun des quatre systèmes pour chacune des fonctions testées, à l'exception du téléchargement des documents avec docDB qui prend environ dix pour cent de temps d'exécution en plus (onze centièmes de secondes au lieu de dix).
Par ailleurs, les systèmes Windows étaient saturés avec la mémoire dont ils disposaient, ce qui les a rendu environ cinq à six fois plus long pour le test de téléchargement en masse (génération de 1000 factures, téléchargement de 1000 documents avec l'API Dolibarr). La différence était plus marquée pour le téléchargement dans ces conditions : environ cinq à sept secondes pour générer une facture et télécharger un document avec docDB, soit environ deux fois plus de temps que sans docDB.
La conclusion est que docDB est moins efficace en environnement Windows saturé (ceci ne représente pas des conditions normales d'exploitation).

Jeux de caractères

Le jeu de caractère testé est utf8, ce qui semble être le cas de fonctionnement standard dans Dolibarr.
Les cas où la base de données utilise un autre jeu de caractères ne sont pas testés (par exemple iso-88959-1). L'utilisation de docDB sans réaliser de tests supplémentaires est déconseillée dans ces cas.
Pour connaître le jeu de caractère utilisé dans la base, on peut utiliser la requête
select default_character_set_name from information_schema.schemata where schema_name = "dolibarr_base_name";
La réponse doit être utf8mb4 ou utf8mb3
Par ailleurs, les tables contenant les données binaires des documents utilisent un autre jeu de caractères et une autre séquence de tri que celles utilisées en standard dans Dolibarr. La raison en est que dans les systèmes de fichiers les caractères accentués sont différents des caractères non accentués équivalents (É est different de E, à est différent de a, etc), alors qu'ils sont considérés comme équivalents lors d'une requête SQL. Ceci est gênant pour émuler un comportement de systèmes de fichiers dans une requête SQL, c'est pourquoi docDB utilise CHARSET=utf8 COLLATE=utf8_bin qui donne les résultats dont il a besoin.

Référence des commandes

Se référer au guide d'installation install-fr_FR.html livré avec le module pour des exemples de fonctionnement.

Commandes de migration

Ces commandes sont utiles hors exploitation, uniquement dans les cas de migration des sources PHP et de chargement des documents GED.

docDBmigrateScripts	Linux : `python3 docDBmigrateScripts.py --dolibarrDir=path_name [--reverse] [--dry-run]` Windows : `py -X utf8 docDBmigrateScripts.py --dolibarrDir=path_name [--reverse] [--dry-run]` Modifie le contenu des scripts du répertoire `htdocs` de Dolibarr de manière à réaliser l'accès en base de données. Par exemple, une séquence d'instructions `if (file_exists($file))` va être transormées en `if (file_exists_Bypass($file))`. Ce traitement est réalisé pour la totalité des scripts PHP, à l'exception de ceux qui sont recopiés depuis le dossier `install/scriptFiles` de docDB. L'option `--reverse` remet les scripts à l'état standard
	--dolibarrDir	Chemin d'accès complet du répertoire `htdocs` de Dolibarr. Si Dolibarr est placé sur `/var/www/dolibarr`, alors `--dolibarrDir=` devra pointer sur `/var/www/dolibarr/htdocs`
	--reverse	Demande la remise à l'état initial des scripts PHP de Dolibarr. Il ne s'agit pas d'une restauration qui reprendrait des fichiers sauvegardés, mais d'un traitement inverse des scripts trouvés dans le dossier
	--dry-run	Demande un traitement d'essai. L'algorithme est suivi de manière exacte jusqu'au moment de la modification de l'élément traité, qui n'a finalement pas lieu
	-X utf8	Windows. Indique à python que le jeu de caractères utilisé dans le script est utf8

docDBmigrateFiles	Linux : `python3 docDBmigrateFiles.py --dolibarrDir=path_name [--reverse] [--dry-run]` Windows : `py -X utf8 docDBmigrateFiles.py --dolibarrDir=path_name [--reverse] [--dry-run] [--phpdir=php_binaries_path]` Lit le contenu du répertoire documents de Dolibarr, et charge celui-ci dans la base de données. Le chemin d'accès du répertoire est connu grâce à la variable `$dolibarr_main_data_root` contenue dans le fichier de configuration de Dolibarr (`htdocs/conf/conf.php`). Celui-ci fournit également les paramètres d'accès à la base de données. Si un fichier est indiqué comme manquant, une correction doit être faite soit au niveau de la base de données (table `llx_ecm_files`) soit au niveau du dossier où le fichier est manquant. L'action correctrice est préférable de manière à éviter les problèmes ultérieurs lors de l'exploitation. On utilisera par exemple une commande sql `delete from llx_ecm_files where filename like '%missing_file_name%';` pour éliminer la référence à un document qui n'existe plus. Dans ce cas, vérifier d'abord l'innocuité de la requête en utilisant d'abord une commande de consultation comme `select filepath,filename from llx_ecm_files where filename like '%missing_file_name%';` afin de lister d'éventuels documents non concernés et risquant d'être supprimés à tord
	--dolibarrDir	Chemin d'accès complet du répertoire `htdocs` de Dolibarr. Si Dolibarr est placé sur `/var/www/dolibarr`, alors `--dolibarrDir=` devra pointer sur `/var/www/dolibarr/htdocs`
	--reverse	Demande le chargement des documents GED depuis la base de données vers le dossier des documents Dolibarr.
	--dry-run	Demande un traitement d'essai. L'algorithme est suivi de manière exacte jusqu'au moment de la modification de l'élément traité, qui n'a pas lieu
	-X utf8	Windows. Indique à python que le jeu de caractères utilisé dans le script est utf8
	--phpdir	Windows. Indique à python le chemin d'accès de l'exécutable PHP. Cette option est nécessaire si ce chemin d'accès n'est pas dans le PATH de Windows. L'accès à PHP sert à obtenir certaines caractéristiques des fichiers images qui sont lues en temps réels par Dolibarr et ne sont de ce fait pas stockées dans la base de données. À l'inverse, docDB stocke ces données dans la base de données afin de les servir à Dolibarr quand il les demande

Requêtes SQL

Ces requêtes sont utiles pour tester et étudier le comportement de Dolibarr et de docDB.
Étant donné qu'il s'agit uniquement de consultation, elles ne présentent aucun risque de destruction de données.

Requête SQL	Exemple de résultat	Explication
`select * from llx_doc_directory;`	\| rowid \| path_name \| \| 1 \| \| \| 2 \| /adherent \| \| 3 \| /adherent/1 \| \| 4 \| /adherent/10 \| \| 5 \| /adherent/11 \|	La table docDB `llx_doc_directory` contient la liste des répertoires censés contenir les documents
`select rowid,path_name,filemtime, octet_length(datablob) as filesize, octet_length(exif_data) as exif_data, octet_length(imagesize) as imagesize from llx_doc_data order by rowid;`	\| rowid \| path_name \| filemtime \| filesize \| exif_data \| imagesize \| \| 1 \| /adherent/1/Jean.pdf \| 2023-01-27 21:36:39 \| 153092 \| 4 \| 4 \| \| 2 \| /adherent/10/Jeanne.pdf \| 2023-01-27 21:36:39 \| 44421 \| 4 \| 4 \| \| 3 \| /adherent/11/Léo.pdf \| 2023-01-30 09:56:36 \| 16135 \| 4 \| 4 \| \| 4 \| /adherent/14/Charlie.pdf \| 2023-01-30 09:56:18 \| 25034 \| 4 \| 4 \| \| 5 \| /adherent/2/Arthur.pdf \| 2023-01-27 21:36:39 \| 44844 \| 4 \| 4 \|	La table docDB `llx_doc_data` contient les documents. La colonne `datablob` n'est pas affichable. À la place `filesize` indique ce qui correspond à la taille du document. `exif_data` et `imagesize` sont des chaînes encodées contenant les caractéristiques des images s'il y a lieu (vides dans le cas des fichiers pdf)
`select filepath,filename from llx_ecm_files;`	\| filepath \| filename \| \| adherent/1 \| Jean.pdf \| \| adherent/10 \| Jeanne.pdf \| \| adherent/11 \| Léo.pdf \| \| adherent/14 \| Charlie.pdf \| \| adherent/2 \| Arthur.pdf \|	La table Dolibarr `llx_ecm_files` contient la liste des documents et des chemins d'accès censés y accéder
`select label from llx_ecm_directories;`	\| label \| \| Documents annuels \|	La table Dolibarr `llx_ecm_directories` contient la liste de certains répertoires, ceux qui sont créés par les utilisateurs dans l'espace GED

Étendre docDB

Nous avons exposé (Principe de fonctionnement) que Dolibarr utilise des fonctions PHP dédiées à la gestion des fichiers.
Ceci étant Dolibarr n'utilise pas toutes les fonctions concernées et par voie de conséquence il est évident qu'il n'était pas nécessaire de programmer l'émulation de toutes ces fonctions.
Prenons par exemple le cas où Dolibarr veut tester la présence du document pdf correspondant à la facture FA2304-0001. Il utilise pour ce faire la fonction file_exists, transformée par docDB en file_exists_Bypass, laquelle fonction utilise pour faire court la requête select rowid from llx_doc_data where path_name='/facture/FA2304-0001/FA2304-0001.pdf'. Si la requête est couronnée de succès, c'est-à-dire si le document existe dans la table llx_doc_data, docDB renvoie la valeur true.
Maintenant imaginons que Dolibarr veuille utiliser la fonction filectime pour connaître la date de création d'un fichier. C'est le cas de temps à autre, mais jamais pour un document. La fonction docDB correspondante filectime_Bypass se contente donc de faire appel à PHP quoi qu'il arrive et renvoie à Dolibarr le résultat renvoyé par PHP.
S'il se trouvait lors d'une version future que Dolibarr fasse appel à PHP pour obtenir la date de création d'un document, il faudrait implémenter correctement filectime_Bypass. Ceci consisterait à tester si le fichier concerné est un document (if ($useByPass && doc_in_db($filename))) et à utiliser dans ce cas la requête SQL appropriée. Les fonctions docDB sont relativement simples et leur utilisation et extension est à la portée d'un programmeur PHP raisonnablement expérimenté.
Si l'on souhaite connaître la liste des fonctions émulées, on la trouve dans le script docDBmigrateScripts.py dans la variable KEYWORDS_FOUND_16.
Les fonctions non implémentées sont listées dans filebypass.php après le commentaire The following functions are not used in the Dolibarr documents context.

Dépannage

En cas de problème, activer le module "Journaux et traces" de Dolibarr, niveau LOG_DEBUG(7).
Vous trouverez alors après exécution des lignes ressemblant à 2023-05-12 15:00:02 DEBUG n.n.n.n DOC_DB ++ filesize /projet/PJ2303-0025/contrat_signé [370816]. Dans cet exemple, la mention DOC_DB ++ indique l'appel à la fonction filesize pour le document /projet/PJ2303-0025/contrat_signé avec une taille de 370816 renvoyée en retour.
Si la mention est DOC_DB --, cela indique que la donnée renvoyée est celle de PHP, sans traitement particulier effectué par docDB.

Vous pouvez lors de l'exécution du script docDBmigrateFiles.py sous Windows, obtenir un plantage avec un message fieldnotfound error. Ceci indique qu'il faut préciser le path de PHP avec l'option --phpdir.

Vous pouvez sous Windows obtenir certains problèmes ayant trait au traitement des fichiers images. Vérifier que l'option PHP exif_data est bien activée. À cet effet, vous pouvez suivre la procédure expliquée dans le guide d'installation.

Licence

La licence sous laquelle est diffusé docDB est la GPL. Voyez le fichier COPYING pour plus de détails.