Datos, base de datos y contenidos
ffDB_Sqlpara el SQL,Storagepara la abstracción multi-driver, el modelo vgallery para los contenidos. Y cuatro trampas deffDB_Sqlque cuestan media jornada a quien no las conoce.
1. ffDB_Sql: el acceso a la base de datos
$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 = valor PHP, no objeto ffData
}
$db->execute("INSERT INTO tabella (nome) VALUES (" . $db->toSql($nome, "Text") . ")");
$nuovo = $db->getInsertID(true);
Las cuatro trampas
1.1 execute() para escribir, query() para leer ⚠️
affectedRows() y getInsertID() no funcionan después de query(). Con FF_DB_MYSQLI_SHARELINK activo (por defecto true, ff/classes/ffDb_Sql/ffDb_Sql_mysqli.php:14) ambos leen propiedades en búfer que solo execute() rellena. Después de un INSERT hecho con query(), getInsertID() devuelve un valor viejo o nulo — y ningún error.
La distinción debe volverse estructural: un helper que escribe usa execute(), los helpers que leen usan query(). No dejarla a la memoria de quien escribe la línea.
El método es
getInsertID(). En otros proyectos del ecosistema existe un wrapper llamadoinsertID(): no es el mismo nombre, y la diferencia se manifiesta como fatal.
1.2 factory() devuelve una instancia nueva
new static() en cada llamada (línea ~189), con la conexión compartida. Cada instancia tiene su propio recordset: una query anidada dentro de un bucle nextRecord() no hace perder filas si usa un handle nuevo. El bug clásico nace de reutilizar la misma variable $db en el bucle interno.
1.3 toSql() ya pone las comillas
$db->toSql($v, "Text") produce 'valor'. No añadir comillas a mano. Con transform_null = true (por defecto) la cadena vacía sigue siendo '', no se convierte en NULL.
1.4 Las fechas
El locale del driver es ISO9075, así que el formato es Y-m-d H:i:s. Conviene pasarlas de todos modos como "Text": con "DateTime" un valor vacío se convierte en '0000-00-00 00:00:00', que MariaDB en modo strict rechaza. Para un campo de fecha vacío se escribe NULL literal.
Otras notas útiles
getField($nombre, $tipo, true)— el tercer parámetro devuelve el valor PHP en lugar de un objetoffData. Olvidarlo lleva a comparaciones que nunca cuadran.- Las fechas se calculan en PHP, no en SQL: el
@@time_zonedel servidor suele serSYSTEM, así queCURDATE()no es el "día" que entiende la aplicación. Si el huso importa (reinicios diarios, franjas horarias), se calcula en PHP con el huso explícito.
Servidores strict: las reglas
El código funciona con el sql_mode por defecto de los servidores modernos (MySQL 8, Aiven, MariaDB): ONLY_FULL_GROUP_BY, STRICT_TRANS_TABLES, NO_ZERO_DATE. El sql_mode no se relaja: se corrige la consulta o el esquema. El banco de pruebas es un MySQL 8 con su valor por defecto.
GROUP BY: cada columna delSELECTestá agrupada, agregada, o depende de la clave primaria agrupada (MySQL lo reconoce incluso a través de losJOINsobre la clave). El viejo modismoSELECT * FROM (... ORDER BY x) AS tbl_src GROUP BY IDpara "quedarse con la primera fila" está prohibido (#1055, y MariaDB ignora de todos modos elORDER BYde la subconsulta): se ordena la consulta plana y se toma la primera fila por clave en PHP (library/gallery/process/init_modules.php), o bienROW_NUMBER() OVER (...)(conf/gallery/manage/block/modify.php), o bien unJOINsobreMIN(ID)(library/gallery/common/get_layout_settings.php).DISTINCTconORDER BY: las columnas de la ordenación deben estar en elSELECT(#3065). Aquí las dependencias funcionales no valen: si se ordena porvgallery_fields.order_thumb, hay que seleccionarla.- Columnas nuevas:
NOT NULLsiempre conDEFAULT(#1364), fechasNULL DEFAULT NULL. - Fechas vacías:
NULL, nunca'0000-00-00'.toSql()de una fecha vacía ya devuelvenull; en las comparaciones se escribeIS NULL(= '0000-00-00'es un error incluso en lectura, #1525). - Valores vacíos en columnas numéricas (#1366): en las consultas escritas a mano se pasa el tipo,
toSql($v, "Number"), o bien, si el valor puede ser unffDatade tipo texto, la variante que conoce la columna:$db->toSqlColumn("tabella", "colonna", $v)(''→0, fecha vacía →NULL).ffRecord,ffDetailsyStorageya la usan. Atención:toSql($ffDataTesto, "Number")lee el valor como número no valorizado y escribe0. - Clave autoincremental:
NULLen elINSERT, no''. - Textos largos: un valor más largo que la columna se rechaza (#1406), no se trunca. El campo del formulario lleva
$oField->properties["maxlength"]. - Dialecto
ANSI(Aiven): conPIPES_AS_CONCATel||concatena en lugar de hacer OR, sin dar error, y conANSI_QUOTESuna cadena entre comillas dobles se convierte en un nombre de columna. En el SQL se escribeOR, y las cadenas van entre comillas simples, como las escribetoSql().
2. Storage: la misma API sobre drivers distintos
vendor/wolfgan/storage/Storage.php abstrae la persistencia con una única interfaz (lookup, find, read, insert, update, write, delete, cmd) sobre varios servicios:
| Servicio | Driver |
|---|---|
sql_mysql.php | MySQL/MariaDB |
nosql_mongodb.php | MongoDB (está vendor/mongodb/) |
fs_json.php, fs_xml.php, fs_php.php | archivos en el filesystem |
$st = Storage::getInstance("sql_mysql");
$st->setTable("tabella");
$rows = $st->read(array("ID_utente" => $id), array("ID", "nome"), array("nome" => "ASC"), 50);
Incluye también conversión entre formatos (convertData, convertWhere) y una caché interna por query.
Cuando el store no está. Storage no lanza excepciones: si el driver no consigue abrir el device, controller_nosql() escribe una línea en cache/logs/AAAA-MM-GG_storage_nosql.txt (con la acción pedida) y la llamada no devuelve nada. Antes, con DEBUG_MODE activo, hacía exit dentro de vgCommon::isError(): un servicio accesorio como las estadísticas de página tumbaba la página entera. La rama SQL en cambio sigue siendo bloqueante — una base de datos relacional que falta es un error de configuración que se tiene que ver.
Cuándo usarla.
Storagecompensa cuando los datos pueden estar en soportes distintos (una configuración en archivo, un log en Mongo) o cuando se quiere un modelo uniforme. Para el SQL de aplicación ordinario,ffDB_Sqldirecto sigue siendo más legible y más fácil de perfilar — y es lo que usa el resto del CMS.
3. El modelo de contenidos (vgallery)
Es la parte que hay que entender antes de diseñar cualquier cosa sobre este CMS.
| Tabla | Significado |
|---|---|
vgallery | la colección/sección (reglas, niveles, multilingüe, e-commerce) |
vgallery_nodes | el esqueleto del nodo: página o carpeta (is_dir). Jerarquía vía parent (ruta, no ID) + name; permalink, orden, visibilidad, SEO básico |
vgallery_type + vgallery_fields | el esquema dinámico de los campos por tipo de contenido |
extended_type | el widget de edición/render del campo (String, Text, TextBB, Selection, GMap, UploadImage…) — separa el dato de la interfaz |
vgallery_rel_nodes_fields | el contenido real: una fila por (nodo × campo × idioma) |
vgallery_nodes_rel_languages | metadatos SEO por idioma |
users_rel_vgallery | permisos usuario↔nodo, con herencia cascading |
rel_nodes | relaciones nodo↔nodo |
Consecuencia arquitectónica: no existen tablas por tipo de contenido. Un "artículo" o un "producto" es un tipo con un conjunto de campos; el modelo no cambia. Añadir un tipo de contenido es configuración (desde el backend), no código.
El reverso de la moneda: una query "dame todos los artículos con el campo X" es un join sobre vgallery_rel_nodes_fields, no un SELECT * FROM articulos. Para las lecturas pesadas se pasa por los helpers (library/gallery/common/get_node_by_permalink.php, get_vgallery_card.php, get_schema_fields_by_type.php…) y por la caché.
Escribir un nodo
⚠️ No reimplementar el guardado. update_vgallery (en library/gallery/common/) gestiona relaciones, permalink/smart_url, multilingüe e invalidación de la caché. El principio adoptado para la nueva área de administración es "lectura nueva, escritura reutilizada": una UI nueva hace POST con los mismos name que esperan los controladores existentes. Ver VGALLERY_NEXT_PIANO.md.
Las otras tablas que hay que conocer
| Tabla | Uso |
|---|---|
access_users, access_groups, access_users_groups | cuentas, grupos, pertenencia (el admin es ID=1 en el seed) |
anagraph, anagraph_company | perfil de persona (vía anagraph.ID_user) y datos de empresa |
access_users.locale, access_users.ID_lang, anagraph.ID_lang | preferencia de idioma del usuario: son tres columnas para la misma información, escritas juntas por language_pref_write_db(). NULL quiere decir "nunca ha elegido", que es distinto de "ha elegido el idioma predeterminado" (ver 06 §2) |
cm_mod_security_domains | el dominio gestionado (ID=1 en el seed), company_name |
cm_mod_security_domains_fields | configuración de los servicios: (field, group, value) con group = nombre del servicio |
ff_languages, ff_international | idiomas activos (status) y diccionario (word_code → texto por idioma) |
layout, layout_path, layout_location | bloques de página; layout_path.visible enciende/apaga header (ID 2) y footer (ID 3) |
cm_mod_security_users | segunda tabla de usuarios legacy: existe, contiene el mismo admin, no es la ruta de login activa |
cm_api_client, cm_api_token | credenciales y tokens de la API pública |
4. Migraciones y database.sql
Regla férrea del proyecto: toda migración debe reflejarse también en el database.sql de la raíz.
El volcado de la raíz es el seed del instalador (218 CREATE TABLE, 90 INSERT) y debe seguir siendo autosuficiente: agnóstico de BD (ningún CREATE DATABASE/USE), sin DELIMITER, triggers ni views, así la importación es trivial en cualquier hosting.
Procedimiento (desde la 3.0.3; antes las migraciones estaban en docs/sql/ y se aplicaban a mano):
- escribir la migración en
migrations/schema_000N_<nome>.sqlo.php, con N el esquema nuevo, idempotente: la ejecutaMigrationsRunner(library/updater/MigrationsRunner.php) desde el updater, desdephp bin/update.php --migrations-only --vaio desde/restricted/updater, y la registra enjc_migrations; - copiar los mismos
CREATE TABLE/ALTER, o las mismas filas, al final dedatabase.sql; - incrementar
JC_SCHEMA_VERSION(eninstall/lib.php): una instalación nueva nace con ese número en su config, y el runner, en su primera ejecución, marca como ya aplicadas las migraciones hasta ese número; - anotarla en
CHANGELOG.mdbajo [Sin publicar], en el grupo### Schema: al publicar la versión es lo que hace que joecms.it avise de la actualización de la base de datos, y sin él la build se detiene (14 §5).
También cuentan las filas de datos del seed: las entradas nuevas del diccionario cambian database.sql, y por tanto el esquema. La migración no las inserta con ID fijos, que en un sitio en producción pueden estar ya ocupados por los marcadores de posición que crea ffTranslator: los rellena e inserta solo lo que falta, sin tocar las traducciones escritas por el administrador (migrations/schema_0005_testi_multilingua.php).
Excepción: el esquema 4 (servidores strict) no tiene un archivo SQL sino una herramienta, bin/db-allinea-schema.php, porque tiene que leer las columnas reales de cada instalación (las antiguas tienen tipos distintos de database.sql, y la herramienta no cambia ninguno). Prueba en vacío por defecto, --vai para ejecutar, --config <file> para otra config; idempotente. Si la conexión se cae a mitad se reconecta una vez, y si no vuelve se detiene: relanzada, retoma desde donde había llegado. En un sitio existente se ejecuta antes de subir el código nuevo (ver 14 §4).
Excepción: una migración que solo repara datos en instalaciones existentes, sin tocar el esquema, no va en database.sql y no sube JC_SCHEMA_VERSION, porque una instalación nueva no tiene datos que reparar. El archivo lo declara en la cabecera. Ejemplo: docs/sql/2026-09_lingua-profili-allineamento.sql, que realinea el idioma en los perfiles creados antes de la corrección del registro.
El código que depende de una migración debe ser defensivo: una función ..._has_schema() que verifica las tablas, y un 503 (API) o un salto con log (cron) en lugar de un fatal. Un despliegue hecho a medias se diagnostica solo.
Convenciones sobre el esquema
- Nada de
FOREIGN KEY, en coherencia con las 218 tablas existentes; los índices sí, todos. utf8mb4en las tablas nuevas que contienen texto libre: las tablas históricas sonutf8mb3y truncan emoji y CJK.- Prefijo reconocible para las tablas de aplicación (
cm_mod_<proyecto>_...), así un volcado se lee y una limpieza no toca el CMS. - Monobase de datos: las constantes
ANAGRAPH/TRACE/NOTIFYapuntan todas a la misma BD.
5. Importación, exportación, backup
library/gallery/common/ contiene ya las herramientas:
| Archivo | Qué hace |
|---|---|
import.php, importcsv.php | importación de contenidos, también desde CSV |
export.php | exportación |
clone_by_schema.php | duplicación de estructuras según el esquema |
convert_db.php | conversiones de esquema |
check_fs.php, check_system.php | verificaciones sobre filesystem y sistema |
Más conf/gallery/backup/ y conf/gallery/import/ en el lado del backend. Son herramientas upstream: hay que probarlas sobre el esquema propio antes de contar con ellas para una migración real.