Ir al contenido
JoeCMS Descargar 3.1.5
Manual · 07

Datos, base de datos y contenidos

ffDB_Sql para el SQL, Storage para la abstracción multi-driver, el modelo vgallery para los contenidos. Y cuatro trampas de ffDB_Sql que 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 llamado insertID(): 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 objeto ffData. Olvidarlo lleva a comparaciones que nunca cuadran.
  • Las fechas se calculan en PHP, no en SQL: el @@time_zone del servidor suele ser SYSTEM, así que CURDATE() 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 del SELECT está agrupada, agregada, o depende de la clave primaria agrupada (MySQL lo reconoce incluso a través de los JOIN sobre la clave). El viejo modismo SELECT * FROM (... ORDER BY x) AS tbl_src GROUP BY ID para "quedarse con la primera fila" está prohibido (#1055, y MariaDB ignora de todos modos el ORDER BY de la subconsulta): se ordena la consulta plana y se toma la primera fila por clave en PHP (library/gallery/process/init_modules.php), o bien ROW_NUMBER() OVER (...) (conf/gallery/manage/block/modify.php), o bien un JOIN sobre MIN(ID) (library/gallery/common/get_layout_settings.php).
  • DISTINCT con ORDER BY: las columnas de la ordenación deben estar en el SELECT (#3065). Aquí las dependencias funcionales no valen: si se ordena por vgallery_fields.order_thumb, hay que seleccionarla.
  • Columnas nuevas: NOT NULL siempre con DEFAULT (#1364), fechas NULL DEFAULT NULL.
  • Fechas vacías: NULL, nunca '0000-00-00'. toSql() de una fecha vacía ya devuelve null; en las comparaciones se escribe IS 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 un ffData de tipo texto, la variante que conoce la columna: $db->toSqlColumn("tabella", "colonna", $v) ('' → 0, fecha vacía → NULL). ffRecord, ffDetails y Storage ya la usan. Atención: toSql($ffDataTesto, "Number") lee el valor como número no valorizado y escribe 0.
  • Clave autoincremental: NULL en el INSERT, 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): con PIPES_AS_CONCAT el || concatena en lugar de hacer OR, sin dar error, y con ANSI_QUOTES una cadena entre comillas dobles se convierte en un nombre de columna. En el SQL se escribe OR, y las cadenas van entre comillas simples, como las escribe toSql().

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:

ServicioDriver
sql_mysql.phpMySQL/MariaDB
nosql_mongodb.phpMongoDB (está vendor/mongodb/)
fs_json.php, fs_xml.php, fs_php.phparchivos 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. Storage compensa 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_Sql directo 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.

TablaSignificado
vgalleryla colección/sección (reglas, niveles, multilingüe, e-commerce)
vgallery_nodesel 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_fieldsel esquema dinámico de los campos por tipo de contenido
extended_typeel widget de edición/render del campo (String, Text, TextBB, Selection, GMap, UploadImage…) — separa el dato de la interfaz
vgallery_rel_nodes_fieldsel contenido real: una fila por (nodo × campo × idioma)
vgallery_nodes_rel_languagesmetadatos SEO por idioma
users_rel_vgallerypermisos usuario↔nodo, con herencia cascading
rel_nodesrelaciones 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

TablaUso
access_users, access_groups, access_users_groupscuentas, grupos, pertenencia (el admin es ID=1 en el seed)
anagraph, anagraph_companyperfil de persona (vía anagraph.ID_user) y datos de empresa
access_users.locale, access_users.ID_lang, anagraph.ID_langpreferencia 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_domainsel dominio gestionado (ID=1 en el seed), company_name
cm_mod_security_domains_fieldsconfiguración de los servicios: (field, group, value) con group = nombre del servicio
ff_languages, ff_internationalidiomas activos (status) y diccionario (word_code → texto por idioma)
layout, layout_path, layout_locationbloques de página; layout_path.visible enciende/apaga header (ID 2) y footer (ID 3)
cm_mod_security_userssegunda tabla de usuarios legacy: existe, contiene el mismo admin, no es la ruta de login activa
cm_api_client, cm_api_tokencredenciales 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):

  1. escribir la migración en migrations/schema_000N_<nome>.sql o .php, con N el esquema nuevo, idempotente: la ejecuta MigrationsRunner (library/updater/MigrationsRunner.php) desde el updater, desde php bin/update.php --migrations-only --vai o desde /restricted/updater, y la registra en jc_migrations;
  2. copiar los mismos CREATE TABLE / ALTER, o las mismas filas, al final de database.sql;
  3. incrementar JC_SCHEMA_VERSION (en install/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;
  4. anotarla en CHANGELOG.md bajo [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.
  • utf8mb4 en las tablas nuevas que contienen texto libre: las tablas históricas son utf8mb3 y 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 / NOTIFY apuntan todas a la misma BD.

5. Importación, exportación, backup

library/gallery/common/ contiene ya las herramientas:

ArchivoQué hace
import.php, importcsv.phpimportación de contenidos, también desde CSV
export.phpexportación
clone_by_schema.phpduplicación de estructuras según el esquema
convert_db.phpconversiones de esquema
check_fs.php, check_system.phpverificaciones 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.