Dati, database e contenuti
ffDB_Sqlper il SQL,Storageper l'astrazione multi-driver, il modello vgallery per i contenuti. E quattro trappole diffDB_Sqlche costano mezza giornata a chi non le conosce.
1. ffDB_Sql: l'accesso al database
$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 = valore PHP, non oggetto ffData
}
$db->execute("INSERT INTO tabella (nome) VALUES (" . $db->toSql($nome, "Text") . ")");
$nuovo = $db->getInsertID(true);
Le quattro trappole
1.1 execute() per scrivere, query() per leggere ⚠️
affectedRows() e getInsertID() non funzionano dopo query(). Con FF_DB_MYSQLI_SHARELINK attivo (default true, ff/classes/ffDb_Sql/ffDb_Sql_mysqli.php:14) entrambi leggono proprietà bufferizzate che solo execute() valorizza. Dopo un INSERT fatto con query(), getInsertID() restituisce un valore stantio o nullo — e nessun errore.
La distinzione va resa strutturale: un helper che scrive usa execute(), gli helper che leggono usano query(). Non lasciarla alla memoria di chi scrive la riga.
Il metodo è
getInsertID(). Su altri progetti dell'ecosistema esiste un wrapper chiamatoinsertID(): non è lo stesso nome, e la differenza si manifesta come fatal.
1.2 factory() restituisce un'istanza nuova
new static() a ogni chiamata (riga ~189), con la connessione condivisa. Ogni istanza ha il proprio recordset: una query annidata dentro un ciclo nextRecord() non fa perdere righe se usa un handle nuovo. Il bug classico nasce dal riusare la stessa variabile $db nel ciclo interno.
1.3 toSql() racchiude già negli apici
$db->toSql($v, "Text") produce 'valore'. Non aggiungere apici a mano. Con transform_null = true (default) la stringa vuota resta '', non diventa NULL.
1.4 Le date
Il locale del driver è ISO9075, quindi il formato è Y-m-d H:i:s. Conviene passarle comunque come "Text": con "DateTime" un valore vuoto diventa '0000-00-00 00:00:00', che MariaDB in strict mode rifiuta. Per un campo data vuoto si scrive NULL letterale.
Altre note utili
getField($nome, $tipo, true)— il terzo parametro restituisce il valore PHP invece di un oggettoffData. Dimenticarlo porta a confronti che non tornano mai.- Le date calcolate in PHP, non in SQL:
@@time_zonedel server è tipicamenteSYSTEM, quindiCURDATE()non è il "giorno" che intende l'applicazione. Se il fuso conta (reset giornalieri, finestre orarie), si calcola in PHP con il fuso esplicito.
Server strict: le regole
Il codice gira con il sql_mode di default dei server moderni (MySQL 8, Aiven, MariaDB): ONLY_FULL_GROUP_BY, STRICT_TRANS_TABLES, NO_ZERO_DATE. Non si allenta il sql_mode: si corregge la query o lo schema. Il banco di prova è un MySQL 8 con il suo default.
GROUP BY: ogni colonna delSELECTè raggruppata, aggregata, o dipende dalla chiave primaria raggruppata (MySQL lo riconosce anche attraverso iJOINsulla chiave). Il vecchio idiomaSELECT * FROM (... ORDER BY x) AS tbl_src GROUP BY IDper "tenere la prima riga" è vietato (#1055, e MariaDB ignora comunque l'ORDER BYdella sottoquery): si ordina la query piatta e si tiene la prima riga per chiave in PHP (library/gallery/process/init_modules.php), oppureROW_NUMBER() OVER (...)(conf/gallery/manage/block/modify.php), oppure unJOINsuMIN(ID)(library/gallery/common/get_layout_settings.php).DISTINCTconORDER BY: le colonne dell'ordinamento devono stare nelSELECT(#3065). Qui le dipendenze funzionali non valgono: se ordini pervgallery_fields.order_thumb, selezionalo.- Colonne nuove:
NOT NULLsempre conDEFAULT(#1364), dateNULL DEFAULT NULL. - Date vuote:
NULL, mai'0000-00-00'.toSql()di una data vuota restituisce giànull; nei confronti si scriveIS NULL(= '0000-00-00'è un errore anche in lettura, #1525). - Valori vuoti in colonne numeriche (#1366): nelle query scritte a mano si passa il tipo,
toSql($v, "Number"), oppure, se il valore può essere unffDatadi tipo testo, la variante che conosce la colonna:$db->toSqlColumn("tabella", "colonna", $v)(''→0, data vuota →NULL).ffRecord,ffDetailseStoragela usano già. Attenzione:toSql($ffDataTesto, "Number")legge il valore come numero non valorizzato e scrive0. - Chiave auto-incrementale:
NULLnell'INSERT, non''. - Testi lunghi: un valore oltre la lunghezza della colonna è rifiutato (#1406), non troncato. Il campo del form porta
$oField->properties["maxlength"]. - Dialetto
ANSI(Aiven): conPIPES_AS_CONCATil||concatena invece di fare OR, senza dare errore, e conANSI_QUOTESuna stringa tra doppi apici diventa un nome di colonna. Nell'SQL si scriveOR, e le stringhe stanno tra apici singoli, come le scrivetoSql().
2. Storage: la stessa API su driver diversi
vendor/wolfgan/storage/Storage.php astrae la persistenza con un'unica interfaccia (lookup, find, read, insert, update, write, delete, cmd) su più servizi:
| Servizio | Driver |
|---|---|
sql_mysql.php | MySQL/MariaDB |
nosql_mongodb.php | MongoDB (c'è vendor/mongodb/) |
fs_json.php, fs_xml.php, fs_php.php | file su filesystem |
$st = Storage::getInstance("sql_mysql");
$st->setTable("tabella");
$rows = $st->read(array("ID_utente" => $id), array("ID", "nome"), array("nome" => "ASC"), 50);
Include anche conversione fra formati (convertData, convertWhere) e una cache interna per query.
Quando lo store non c'è. Storage non solleva eccezioni: se il driver non riesce ad aprire il device, controller_nosql() scrive una riga in cache/logs/AAAA-MM-GG_storage_nosql.txt (con l'azione richiesta) e la chiamata restituisce niente. Prima, con DEBUG_MODE acceso, faceva exit dentro vgCommon::isError(): un servizio accessorio come le statistiche di pagina si portava via la pagina intera. Il ramo SQL resta invece bloccante — un database relazionale mancante è un errore di configurazione che si deve vedere.
Quando usarla.
Storageripaga quando i dati possono stare su supporti diversi (una configurazione su file, un log su Mongo) o quando si vuole un modello uniforme. Per il SQL applicativo ordinario,ffDB_Sqldiretto resta più leggibile e più facile da profilare — ed è quello che usa il resto del CMS.
3. Il modello dei contenuti (vgallery)
È la parte da capire prima di progettare qualunque cosa sopra questo CMS.
| Tabella | Significato |
|---|---|
vgallery | la collezione/sezione (regole, livelli, multilingua, e-commerce) |
vgallery_nodes | lo scheletro del nodo: pagina o cartella (is_dir). Gerarchia via parent (percorso, non ID) + name; permalink, ordine, visibilità, SEO base |
vgallery_type + vgallery_fields | lo schema dinamico dei campi per tipo di contenuto |
extended_type | il widget di edit/render del campo (String, Text, TextBB, Selection, GMap, UploadImage…) — separa il dato dall'interfaccia |
vgallery_rel_nodes_fields | il contenuto vero: una riga per (nodo × campo × lingua) |
vgallery_nodes_rel_languages | metadati SEO per lingua |
users_rel_vgallery | permessi utente↔nodo, con ereditarietà cascading |
rel_nodes | relazioni nodo↔nodo |
Conseguenza architetturale: non esistono tabelle per tipo di contenuto. Un "articolo" o un "prodotto" è un tipo con un set di campi; il modello non cambia. Aggiungere un tipo di contenuto è configurazione (dal backend), non codice.
Il rovescio della medaglia: una query "dammi tutti gli articoli con il campo X" è una join su vgallery_rel_nodes_fields, non un SELECT * FROM articoli. Per le letture pesanti si passa dagli helper (library/gallery/common/get_node_by_permalink.php, get_vgallery_card.php, get_schema_fields_by_type.php…) e dalla cache.
Scrivere un nodo
⚠️ Non reimplementare il salvataggio. update_vgallery (in library/gallery/common/) gestisce relazioni, permalink/smart_url, multilingua e invalidazione della cache. Il principio adottato per la nuova area di amministrazione è "lettura nuova, scrittura riusata": una UI nuova POSTa con gli stessi name attesi dai controller esistenti. Vedi VGALLERY_NEXT_PIANO.md.
Le altre tabelle da conoscere
| Tabella | Uso |
|---|---|
access_users, access_groups, access_users_groups | account, gruppi, appartenenza (l'admin è ID=1 nel seed) |
anagraph, anagraph_company | profilo persona (via anagraph.ID_user) e dati azienda |
access_users.locale, access_users.ID_lang, anagraph.ID_lang | preferenza di lingua dell'utente: sono tre colonne per la stessa informazione, scritte insieme da language_pref_write_db(). NULL vuol dire "non ha mai scelto", che è diverso da "ha scelto la lingua predefinita" (vedi 06 §2) |
cm_mod_security_domains | il dominio gestito (ID=1 nel seed), company_name |
cm_mod_security_domains_fields | configurazione dei servizi: (field, group, value) con group = nome servizio |
ff_languages, ff_international | lingue attive (status) e dizionario (word_code → testo per lingua) |
layout, layout_path, layout_location | blocchi di pagina; layout_path.visible accende/spegne header (ID 2) e footer (ID 3) |
cm_mod_security_users | seconda tabella utenti legacy: esiste, contiene lo stesso admin, non è il path di login attivo |
cm_api_client, cm_api_token | credenziali e token dell'API pubblica |
4. Migration e database.sql
Regola ferrea del progetto: ogni migration va riportata anche in database.sql di root.
Il dump di root è il seed dell'installer (218 CREATE TABLE, 90 INSERT) e deve restare autosufficiente: DB-agnostico (nessun CREATE DATABASE/USE), senza DELIMITER, trigger o view, così l'import è banale su qualunque hosting.
Procedura (dalla 3.0.3; prima le migration stavano in docs/sql/ e si applicavano a mano):
- scrivere la migration in
migrations/schema_000N_<nome>.sqlo.php, con N il nuovo schema, idempotente: la esegueMigrationsRunner(library/updater/MigrationsRunner.php) dall'updater, daphp bin/update.php --migrations-only --vaio da/restricted/updater, e la segna injc_migrations; - riportare le stesse
CREATE TABLE/ALTER, o le stesse righe, in coda adatabase.sql; - incrementare
JC_SCHEMA_VERSION(ininstall/lib.php): un'installazione nuova nasce con quel numero nel config, e il runner, alla prima esecuzione, segna come già applicate le migration fino a lì; - annotare in
CHANGELOG.mdsotto [Non rilasciato], nel gruppo### Schema: al rilascio è quello che fa avvisare joecms.it dell'aggiornamento del database, e senza il quale la build si ferma (14 §5).
Anche le righe di dati del seed contano: voci nuove del dizionario cambiano database.sql, quindi lo schema. La migration non le inserisce con ID fissi, che su un sito in esercizio possono essere già presi dai segnaposto creati da ffTranslator: le riempie e inserisce solo ciò che manca, senza toccare le traduzioni scritte dall'amministratore (migrations/schema_0005_testi_multilingua.php).
Eccezione: lo schema 4 (server strict) non ha un file SQL ma uno strumento, bin/db-allinea-schema.php, perché deve leggere le colonne reali di ogni installazione (quelle vecchie hanno tipi diversi da database.sql, e lo strumento non ne cambia nessuno). Prova a vuoto di default, --vai per eseguire, --config <file> per un'altra config; idempotente. Se la connessione cade a metà si ricollega una volta, e se non torna si ferma: rilanciato, riparte da dove era arrivato. Su un sito esistente gira prima di caricare il codice nuovo (vedi 14 §4).
Eccezione: una migration che ripara solo dati su installazioni esistenti, senza toccare lo schema, non va in database.sql e non alza JC_SCHEMA_VERSION, perché un'installazione nuova non ha dati da riparare. Il file lo dichiara in testa. Esempio: docs/sql/2026-09_lingua-profili-allineamento.sql, che riallinea la lingua sui profili creati prima del fix alla registrazione.
Il codice che dipende da una migration deve essere difensivo: una funzione ..._has_schema() che verifica le tabelle, e un 503 (API) o uno skip con log (cron) invece di un fatal. Un deploy fatto a metà si diagnostica da solo.
Convenzioni sullo schema
- Niente
FOREIGN KEY, coerentemente con le 218 tabelle esistenti; gli indici sì, tutti. utf8mb4sulle tabelle nuove che contengono testo libero: le tabelle storiche sonoutf8mb3e troncano emoji e CJK.- Prefisso riconoscibile per le tabelle applicative (
cm_mod_<progetto>_...), così un dump si legge e una pulizia non tocca il CMS. - Mono-database: le costanti
ANAGRAPH/TRACE/NOTIFYpuntano tutte allo stesso DB.
5. Import, export, backup
library/gallery/common/ contiene già gli attrezzi:
| File | Cosa fa |
|---|---|
import.php, importcsv.php | import di contenuti, anche da CSV |
export.php | export |
clone_by_schema.php | duplicazione di strutture secondo lo schema |
convert_db.php | conversioni di schema |
check_fs.php, check_system.php | verifiche su filesystem e sistema |
Più conf/gallery/backup/ e conf/gallery/import/ lato backend. Sono strumenti upstream: vanno provati sul proprio schema prima di contarci per una migrazione vera.