Aller au contenu
JoeCMS Télécharger 3.1.5
Manuel · 07

Données, base de données et contenus

ffDB_Sql pour le SQL, Storage pour l'abstraction multi-driver, le modèle vgallery pour les contenus. Et quatre pièges de ffDB_Sql qui 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 objet ffData. L'oublier mène à des comparaisons qui ne tombent jamais juste.
  • Les dates se calculent en PHP, pas en SQL : le @@time_zone du serveur est typiquement SYSTEM, donc CURDATE() 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 du SELECT est groupée, agrégée, ou dépend de la clé primaire groupée (MySQL le reconnaît même à travers les JOIN sur la clé). Le vieil idiome SELECT * FROM (... ORDER BY x) AS tbl_src GROUP BY ID pour « garder la première ligne » est interdit (#1055, et MariaDB ignore de toute façon l'ORDER BY de 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 bien ROW_NUMBER() OVER (...) (conf/gallery/manage/block/modify.php), ou bien un JOIN sur MIN(ID) (library/gallery/common/get_layout_settings.php).
  • DISTINCT avec ORDER BY : les colonnes du tri doivent être dans le SELECT (#3065). Ici les dépendances fonctionnelles ne comptent pas : si l'on trie par vgallery_fields.order_thumb, on la sélectionne.
  • Nouvelles colonnes : NOT NULL toujours avec un DEFAULT (#1364), dates NULL DEFAULT NULL.
  • Dates vides : NULL, jamais '0000-00-00'. toSql() d'une date vide renvoie déjà null ; dans les comparaisons on écrit IS 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 un ffData de type texte, la variante qui connaît la colonne : $db->toSqlColumn("tabella", "colonna", $v) ('' → 0, date vide → NULL). ffRecord, ffDetails et Storage l'utilisent déjà. Attention : toSql($ffDataTesto, "Number") lit la valeur comme un nombre non renseigné et écrit 0.
  • Clé auto-incrémentée : NULL dans 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) : avec PIPES_AS_CONCAT, || concatène au lieu de faire un OR, sans erreur, et avec ANSI_QUOTES une chaîne entre guillemets doubles devient un nom de colonne. En SQL on écrit OR, et les chaînes vont entre apostrophes simples, comme les écrit toSql().

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 :

ServiceDriver
sql_mysql.phpMySQL/MariaDB
nosql_mongodb.phpMongoDB (vendor/mongodb/ est présent)
fs_json.php, fs_xml.php, fs_php.phpfichiers 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. Storage est 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_Sql direct 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.

TableSignification
vgalleryla collection/section (règles, niveaux, multilingue, e-commerce)
vgallery_nodesle 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_fieldsle schéma dynamique des champs par type de contenu
extended_typele widget d'édition/rendu du champ (String, Text, TextBB, Selection, GMap, UploadImage…) — sépare la donnée de l'interface
vgallery_rel_nodes_fieldsle vrai contenu : une ligne par (nœud × champ × langue)
vgallery_nodes_rel_languagesmétadonnées SEO par langue
users_rel_vgallerypermissions utilisateur↔nœud, avec héritage cascading
rel_nodesrelations 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

TableUsage
access_users, access_groups, access_users_groupscomptes, groupes, appartenance (l'admin est ID=1 dans le seed)
anagraph, anagraph_companyprofil de la personne (via anagraph.ID_user) et données d'entreprise
access_users.locale, access_users.ID_lang, anagraph.ID_langpré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_domainsle domaine géré (ID=1 dans le seed), company_name
cm_mod_security_domains_fieldsconfiguration des services : (field, group, value) avec group = nom du service
ff_languages, ff_internationallangues actives (status) et dictionnaire (word_code → texte par langue)
layout, layout_path, layout_locationblocs de page ; layout_path.visible allume/éteint le header (ID 2) et le footer (ID 3)
cm_mod_security_usersseconde table d'utilisateurs legacy : elle existe, contient le même admin, n'est pas le chemin de connexion actif
cm_api_client, cm_api_tokenidentifiants 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) :

  1. écrire la migration dans migrations/schema_000N_<nome>.sql ou .php, avec N le nouveau schéma, idempotente : MigrationsRunner (library/updater/MigrationsRunner.php) l'exécute depuis l'updater, depuis php bin/update.php --migrations-only --vai ou depuis /restricted/updater, et l'enregistre dans jc_migrations ;
  2. reporter les mêmes CREATE TABLE / ALTER, ou les mêmes lignes, à la fin de database.sql ;
  3. incrémenter JC_SCHEMA_VERSION (dans install/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 ;
  4. la noter dans CHANGELOG.md sous [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.
  • utf8mb4 sur les nouvelles tables contenant du texte libre : les tables historiques sont en utf8mb3 et 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 / NOTIFY pointent toutes vers la même BD.

5. Import, export, sauvegarde

library/gallery/common/ contient déjà les outils :

FichierCe qu'il fait
import.php, importcsv.phpimport de contenus, aussi depuis CSV
export.phpexport
clone_by_schema.phpduplication de structures selon le schéma
convert_db.phpconversions de schéma
check_fs.php, check_system.phpvé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.