Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 07

Dati, database e contenuti

ffDB_Sql per il SQL, Storage per l'astrazione multi-driver, il modello vgallery per i contenuti. E quattro trappole di ffDB_Sql che 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 chiamato insertID(): 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 oggetto ffData. Dimenticarlo porta a confronti che non tornano mai.
  • Le date calcolate in PHP, non in SQL: @@time_zone del server è tipicamente SYSTEM, quindi CURDATE() 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 del SELECT è raggruppata, aggregata, o dipende dalla chiave primaria raggruppata (MySQL lo riconosce anche attraverso i JOIN sulla chiave). Il vecchio idioma SELECT * FROM (... ORDER BY x) AS tbl_src GROUP BY ID per "tenere la prima riga" è vietato (#1055, e MariaDB ignora comunque l'ORDER BY della sottoquery): si ordina la query piatta e si tiene la prima riga per chiave in PHP (library/gallery/process/init_modules.php), oppure ROW_NUMBER() OVER (...) (conf/gallery/manage/block/modify.php), oppure un JOIN su MIN(ID) (library/gallery/common/get_layout_settings.php).
  • DISTINCT con ORDER BY: le colonne dell'ordinamento devono stare nel SELECT (#3065). Qui le dipendenze funzionali non valgono: se ordini per vgallery_fields.order_thumb, selezionalo.
  • Colonne nuove: NOT NULL sempre con DEFAULT (#1364), date NULL DEFAULT NULL.
  • Date vuote: NULL, mai '0000-00-00'. toSql() di una data vuota restituisce già null; nei confronti si scrive IS 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 un ffData di tipo testo, la variante che conosce la colonna: $db->toSqlColumn("tabella", "colonna", $v) ('' → 0, data vuota → NULL). ffRecord, ffDetails e Storage la usano già. Attenzione: toSql($ffDataTesto, "Number") legge il valore come numero non valorizzato e scrive 0.
  • Chiave auto-incrementale: NULL nell'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): con PIPES_AS_CONCAT il || concatena invece di fare OR, senza dare errore, e con ANSI_QUOTES una stringa tra doppi apici diventa un nome di colonna. Nell'SQL si scrive OR, e le stringhe stanno tra apici singoli, come le scrive toSql().

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:

ServizioDriver
sql_mysql.phpMySQL/MariaDB
nosql_mongodb.phpMongoDB (c'è vendor/mongodb/)
fs_json.php, fs_xml.php, fs_php.phpfile 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. Storage ripaga 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_Sql diretto 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.

TabellaSignificato
vgalleryla collezione/sezione (regole, livelli, multilingua, e-commerce)
vgallery_nodeslo scheletro del nodo: pagina o cartella (is_dir). Gerarchia via parent (percorso, non ID) + name; permalink, ordine, visibilità, SEO base
vgallery_type + vgallery_fieldslo schema dinamico dei campi per tipo di contenuto
extended_typeil widget di edit/render del campo (String, Text, TextBB, Selection, GMap, UploadImage…) — separa il dato dall'interfaccia
vgallery_rel_nodes_fieldsil contenuto vero: una riga per (nodo × campo × lingua)
vgallery_nodes_rel_languagesmetadati SEO per lingua
users_rel_vgallerypermessi utente↔nodo, con ereditarietà cascading
rel_nodesrelazioni 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

TabellaUso
access_users, access_groups, access_users_groupsaccount, gruppi, appartenenza (l'admin è ID=1 nel seed)
anagraph, anagraph_companyprofilo persona (via anagraph.ID_user) e dati azienda
access_users.locale, access_users.ID_lang, anagraph.ID_langpreferenza 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_domainsil dominio gestito (ID=1 nel seed), company_name
cm_mod_security_domains_fieldsconfigurazione dei servizi: (field, group, value) con group = nome servizio
ff_languages, ff_internationallingue attive (status) e dizionario (word_code → testo per lingua)
layout, layout_path, layout_locationblocchi di pagina; layout_path.visible accende/spegne header (ID 2) e footer (ID 3)
cm_mod_security_usersseconda tabella utenti legacy: esiste, contiene lo stesso admin, non è il path di login attivo
cm_api_client, cm_api_tokencredenziali 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):

  1. scrivere la migration in migrations/schema_000N_<nome>.sql o .php, con N il nuovo schema, idempotente: la esegue MigrationsRunner (library/updater/MigrationsRunner.php) dall'updater, da php bin/update.php --migrations-only --vai o da /restricted/updater, e la segna in jc_migrations;
  2. riportare le stesse CREATE TABLE / ALTER, o le stesse righe, in coda a database.sql;
  3. incrementare JC_SCHEMA_VERSION (in install/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ì;
  4. annotare in CHANGELOG.md sotto [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.
  • utf8mb4 sulle tabelle nuove che contengono testo libero: le tabelle storiche sono utf8mb3 e 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 / NOTIFY puntano tutte allo stesso DB.

5. Import, export, backup

library/gallery/common/ contiene già gli attrezzi:

FileCosa fa
import.php, importcsv.phpimport di contenuti, anche da CSV
export.phpexport
clone_by_schema.phpduplicazione di strutture secondo lo schema
convert_db.phpconversioni di schema
check_fs.php, check_system.phpverifiche 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.