Données, base de données et contenus
ffDB_Sqlpour le SQL,Storagepour l'abstraction multi-driver, le modèle vgallery pour les contenus. Et quatre pièges deffDB_Sqlqui coûtent une demi-journée à qui ne les connaît pas.
1. ffDB_Sql : l'accès à la base de données
$db = ffDB_Sql::factory();
$db->query("SELECT ID, nome FROM tabella WHERE ID_utente = " . $db->toSql($id, "Number"));
while ($db->nextRecord()) {
$nome = $db->getField("nome", "Text", true); // true = valeur PHP, pas un objet ffData
}
$db->execute("INSERT INTO tabella (nome) VALUES (" . $db->toSql($nome, "Text") . ")");
$nuovo = $db->getInsertID(true);
Les quatre pièges
1.1 execute() pour écrire, query() pour lire ⚠️
affectedRows() et getInsertID() ne fonctionnent pas après query(). Avec FF_DB_MYSQLI_SHARELINK actif (par défaut true, ff/classes/ffDb_Sql/ffDb_Sql_mysqli.php:14) tous deux lisent des propriétés en tampon que seul execute() renseigne. Après un INSERT fait avec query(), getInsertID() renvoie une valeur périmée ou nulle — et aucune erreur.
La distinction doit devenir structurelle : un helper qui écrit utilise execute(), les helpers qui lisent utilisent query(). Ne pas la laisser à la mémoire de qui écrit la ligne.
La méthode est
getInsertID(). Sur d'autres projets de l'écosystème existe un wrapper appeléinsertID(): ce n'est pas le même nom, et la différence se manifeste par un fatal.
1.2 factory() renvoie une nouvelle instance
new static() à chaque appel (ligne ~189), avec la connexion partagée. Chaque instance a son propre recordset : une requête imbriquée dans une boucle nextRecord() ne fait pas perdre de lignes si elle utilise un nouveau handle. Le bug classique naît de la réutilisation de la même variable $db dans la boucle interne.
1.3 toSql() met déjà les apostrophes
$db->toSql($v, "Text") produit 'valeur'. Ne pas ajouter d'apostrophes à la main. Avec transform_null = true (par défaut) la chaîne vide reste '', elle ne devient pas NULL.
1.4 Les dates
La locale du driver est ISO9075, donc le format est Y-m-d H:i:s. Il vaut quand même mieux les passer en "Text" : avec "DateTime" une valeur vide devient '0000-00-00 00:00:00', que MariaDB en mode strict refuse. Pour un champ date vide on écrit NULL littéral.
Autres notes utiles
getField($nom, $type, true)— le troisième paramètre renvoie la valeur PHP au lieu d'un objetffData. L'oublier mène à des comparaisons qui ne tombent jamais juste.- Les dates se calculent en PHP, pas en SQL : le
@@time_zonedu serveur est typiquementSYSTEM, doncCURDATE()n'est pas le « jour » qu'entend l'application. Si le fuseau compte (remises à zéro quotidiennes, créneaux horaires), on calcule en PHP avec le fuseau explicite.
Serveurs strict : les règles
Le code tourne avec le sql_mode par défaut des serveurs modernes (MySQL 8, Aiven, MariaDB) : ONLY_FULL_GROUP_BY, STRICT_TRANS_TABLES, NO_ZERO_DATE. On n'assouplit pas le sql_mode : on corrige la requête ou le schéma. Le banc d'essai est un MySQL 8 avec sa valeur par défaut.
GROUP BY: chaque colonne duSELECTest groupée, agrégée, ou dépend de la clé primaire groupée (MySQL le reconnaît même à travers lesJOINsur la clé). Le vieil idiomeSELECT * FROM (... ORDER BY x) AS tbl_src GROUP BY IDpour « garder la première ligne » est interdit (#1055, et MariaDB ignore de toute façon l'ORDER BYde la sous-requête) : on trie la requête à plat et on garde la première ligne par clé en PHP (library/gallery/process/init_modules.php), ou bienROW_NUMBER() OVER (...)(conf/gallery/manage/block/modify.php), ou bien unJOINsurMIN(ID)(library/gallery/common/get_layout_settings.php).DISTINCTavecORDER BY: les colonnes du tri doivent être dans leSELECT(#3065). Ici les dépendances fonctionnelles ne comptent pas : si l'on trie parvgallery_fields.order_thumb, on la sélectionne.- Nouvelles colonnes :
NOT NULLtoujours avec unDEFAULT(#1364), datesNULL DEFAULT NULL. - Dates vides :
NULL, jamais'0000-00-00'.toSql()d'une date vide renvoie déjànull; dans les comparaisons on écritIS NULL(= '0000-00-00'est une erreur même en lecture, #1525). - Valeurs vides dans les colonnes numériques (#1366) : dans les requêtes écrites à la main on passe le type,
toSql($v, "Number"), ou bien, si la valeur peut être unffDatade type texte, la variante qui connaît la colonne :$db->toSqlColumn("tabella", "colonna", $v)(''→0, date vide →NULL).ffRecord,ffDetailsetStoragel'utilisent déjà. Attention :toSql($ffDataTesto, "Number")lit la valeur comme un nombre non renseigné et écrit0. - Clé auto-incrémentée :
NULLdans l'INSERT, pas''. - Textes longs : une valeur plus longue que la colonne est refusée (#1406), pas tronquée. Le champ du formulaire porte
$oField->properties["maxlength"]. - Dialecte
ANSI(Aiven) : avecPIPES_AS_CONCAT,||concatène au lieu de faire un OR, sans erreur, et avecANSI_QUOTESune chaîne entre guillemets doubles devient un nom de colonne. En SQL on écritOR, et les chaînes vont entre apostrophes simples, comme les écrittoSql().
2. Storage : la même API sur des drivers différents
vendor/wolfgan/storage/Storage.php abstrait la persistance par une interface unique (lookup, find, read, insert, update, write, delete, cmd) sur plusieurs services :
| Service | Driver |
|---|---|
sql_mysql.php | MySQL/MariaDB |
nosql_mongodb.php | MongoDB (vendor/mongodb/ est présent) |
fs_json.php, fs_xml.php, fs_php.php | fichiers sur le filesystem |
$st = Storage::getInstance("sql_mysql");
$st->setTable("tabella");
$rows = $st->read(array("ID_utente" => $id), array("ID", "nome"), array("nome" => "ASC"), 50);
Il inclut aussi la conversion entre formats (convertData, convertWhere) et un cache interne par requête.
Quand le store n'est pas là. Storage ne lève pas d'exceptions : si le driver n'arrive pas à ouvrir le device, controller_nosql() écrit une ligne dans cache/logs/AAAA-MM-GG_storage_nosql.txt (avec l'action demandée) et l'appel ne renvoie rien. Avant, avec DEBUG_MODE activé, il faisait exit dans vgCommon::isError() : un service accessoire comme les statistiques de page faisait tomber la page entière. La branche SQL reste en revanche bloquante — une base de données relationnelle manquante est une erreur de configuration qui doit se voir.
Quand l'utiliser.
Storageest rentable quand les données peuvent vivre sur des supports différents (une configuration en fichier, un log dans Mongo) ou quand on veut un modèle uniforme. Pour le SQL applicatif ordinaire,ffDB_Sqldirect reste plus lisible et plus facile à profiler — et c'est ce qu'utilise le reste du CMS.
3. Le modèle des contenus (vgallery)
C'est la partie à comprendre avant de concevoir quoi que ce soit sur ce CMS.
| Table | Signification |
|---|---|
vgallery | la collection/section (règles, niveaux, multilingue, e-commerce) |
vgallery_nodes | le squelette du nœud : page ou dossier (is_dir). Hiérarchie via parent (chemin, pas ID) + name ; permalien, ordre, visibilité, SEO de base |
vgallery_type + vgallery_fields | le schéma dynamique des champs par type de contenu |
extended_type | le widget d'édition/rendu du champ (String, Text, TextBB, Selection, GMap, UploadImage…) — sépare la donnée de l'interface |
vgallery_rel_nodes_fields | le vrai contenu : une ligne par (nœud × champ × langue) |
vgallery_nodes_rel_languages | métadonnées SEO par langue |
users_rel_vgallery | permissions utilisateur↔nœud, avec héritage cascading |
rel_nodes | relations nœud↔nœud |
Conséquence architecturale : il n'existe pas de tables par type de contenu. Un « article » ou un « produit » est un type avec un ensemble de champs ; le modèle ne change pas. Ajouter un type de contenu est de la configuration (depuis le backend), pas du code.
Le revers de la médaille : une requête « donne-moi tous les articles avec le champ X » est une jointure sur vgallery_rel_nodes_fields, pas un SELECT * FROM articles. Pour les lectures lourdes on passe par les helpers (library/gallery/common/get_node_by_permalink.php, get_vgallery_card.php, get_schema_fields_by_type.php…) et par le cache.
Écrire un nœud
⚠️ Ne pas réimplémenter l'enregistrement. update_vgallery (dans library/gallery/common/) gère relations, permalien/smart_url, multilingue et invalidation du cache. Le principe adopté pour le nouvel espace d'administration est « lecture nouvelle, écriture réutilisée » : une nouvelle UI fait un POST avec les mêmes name qu'attendent les contrôleurs existants. Voir VGALLERY_NEXT_PIANO.md.
Les autres tables à connaître
| Table | Usage |
|---|---|
access_users, access_groups, access_users_groups | comptes, groupes, appartenance (l'admin est ID=1 dans le seed) |
anagraph, anagraph_company | profil de la personne (via anagraph.ID_user) et données d'entreprise |
access_users.locale, access_users.ID_lang, anagraph.ID_lang | préférence de langue de l'utilisateur : trois colonnes pour la même information, écrites ensemble par language_pref_write_db(). NULL signifie « n'a jamais choisi », ce qui est différent de « a choisi la langue par défaut » (voir 06 §2) |
cm_mod_security_domains | le domaine géré (ID=1 dans le seed), company_name |
cm_mod_security_domains_fields | configuration des services : (field, group, value) avec group = nom du service |
ff_languages, ff_international | langues actives (status) et dictionnaire (word_code → texte par langue) |
layout, layout_path, layout_location | blocs de page ; layout_path.visible allume/éteint le header (ID 2) et le footer (ID 3) |
cm_mod_security_users | seconde table d'utilisateurs legacy : elle existe, contient le même admin, n'est pas le chemin de connexion actif |
cm_api_client, cm_api_token | identifiants et tokens de l'API publique |
4. Migrations et database.sql
Règle d'or du projet : toute migration doit aussi être reportée dans le database.sql de la racine.
Le dump racine est le seed de l'installeur (218 CREATE TABLE, 90 INSERT) et doit rester autosuffisant : agnostique de la BD (aucun CREATE DATABASE/USE), sans DELIMITER, triggers ni vues, pour que l'import soit trivial sur n'importe quel hébergement.
Procédure (depuis la 3.0.3 ; avant, les migrations étaient dans docs/sql/ et s'appliquaient à la main) :
- écrire la migration dans
migrations/schema_000N_<nome>.sqlou.php, avec N le nouveau schéma, idempotente :MigrationsRunner(library/updater/MigrationsRunner.php) l'exécute depuis l'updater, depuisphp bin/update.php --migrations-only --vaiou depuis/restricted/updater, et l'enregistre dansjc_migrations; - reporter les mêmes
CREATE TABLE/ALTER, ou les mêmes lignes, à la fin dedatabase.sql; - incrémenter
JC_SCHEMA_VERSION(dansinstall/lib.php) : une nouvelle installation naît avec ce numéro dans son config, et le runner, à sa première exécution, marque comme déjà appliquées les migrations jusqu'à ce numéro ; - la noter dans
CHANGELOG.mdsous [Non publié], dans le groupe### Schema: à la publication, c'est ce qui fait que joecms.it prévient de la mise à jour de la base de données, et sans lui le build s'arrête (14 §5).
Les lignes de données du seed comptent aussi : de nouvelles entrées du dictionnaire changent database.sql, donc le schéma. La migration ne les insère pas avec des ID fixes, qui sur un site en service peuvent déjà être pris par les entrées de substitution que crée ffTranslator : elle les remplit et n'insère que ce qui manque, sans toucher aux traductions écrites par l'administrateur (migrations/schema_0005_testi_multilingua.php).
Exception : le schéma 4 (serveurs strict) n'a pas de fichier SQL mais un outil, bin/db-allinea-schema.php, parce qu'il doit lire les colonnes réelles de chaque installation (les anciennes ont des types différents de database.sql, et l'outil n'en change aucun). Essai à blanc par défaut, --vai pour exécuter, --config <file> pour une autre config ; idempotent. Si la connexion tombe en cours de route, il se reconnecte une fois, et si elle ne revient pas il s'arrête : relancé, il reprend là où il en était. Sur un site existant, il s'exécute avant l'envoi du nouveau code (voir 14 §4).
Exception : une migration qui répare seulement des données sur des installations existantes, sans toucher au schéma, ne va pas dans database.sql et n'augmente pas JC_SCHEMA_VERSION, parce qu'une nouvelle installation n'a pas de données à réparer. Le fichier le déclare en tête. Exemple : docs/sql/2026-09_lingua-profili-allineamento.sql, qui réaligne la langue sur les profils créés avant le correctif de l'inscription.
Le code qui dépend d'une migration doit être défensif : une fonction ..._has_schema() qui vérifie les tables, et un 503 (API) ou un saut journalisé (cron) au lieu d'un fatal. Un déploiement fait à moitié se diagnostique tout seul.
Conventions sur le schéma
- Pas de
FOREIGN KEY, par cohérence avec les 218 tables existantes ; les index oui, tous. utf8mb4sur les nouvelles tables contenant du texte libre : les tables historiques sont enutf8mb3et tronquent emoji et CJK.- Préfixe reconnaissable pour les tables applicatives (
cm_mod_<projet>_...), pour qu'un dump se lise et qu'un nettoyage ne touche pas le CMS. - Base unique : les constantes
ANAGRAPH/TRACE/NOTIFYpointent toutes vers la même BD.
5. Import, export, sauvegarde
library/gallery/common/ contient déjà les outils :
| Fichier | Ce qu'il fait |
|---|---|
import.php, importcsv.php | import de contenus, aussi depuis CSV |
export.php | export |
clone_by_schema.php | duplication de structures selon le schéma |
convert_db.php | conversions de schéma |
check_fs.php, check_system.php | vérifications du filesystem et du système |
Plus conf/gallery/backup/ et conf/gallery/import/ côté backend. Ce sont des outils upstream : il faut les tester sur son propre schéma avant de compter dessus pour une vraie migration.