Guía de migración: 9.11.0 → 9.12.0
Osumi Framework 9.12.0 añade soporte nativo para columnas SQL DATE, DATETIME y BIGINT y redefine el significado de OField::DATE.
Esta versión incluye un paso automático de migración para mantener la compatibilidad de los modelos existentes.
DATE y DATETIME
Hasta Osumi Framework 9.11, OField::DATE generaba realmente una columna SQL DATETIME.
Desde 9.12 los tipos quedan separados:
OField::DATE → SQL DATE → PHP ?string → Y-m-d
OField::DATETIME → SQL DATETIME → PHP ?string → Y-m-d H:i:s
Por ejemplo:
#[OField(
type: OField::DATE
)]
public ?string $event_date = null;
#[OField(
type: OField::DATETIME
)]
public ?string $processed_at = null;
Los valores temporales se validan estrictamente y se rechazan fechas u horas imposibles.
Los campos #[OCreatedAt], #[OUpdatedAt] y #[ODeletedAt] continúan representando timestamps completos y utilizan internamente DATETIME.
Migración automática de OField::DATE
Los modelos creados con versiones anteriores a 9.12 utilizaban OField::DATE con semántica DATETIME.
Al actualizar, la migración 9.12.0 transforma automáticamente:
OField::DATE
en:
OField::DATETIME
dentro de los modelos existentes en src/Model/.
La migración modifica únicamente tokens PHP reales y no cambia apariciones dentro de comentarios o cadenas de texto.
No modifica el esquema de la base de datos: conserva la semántica DATETIME que ya tenían esos campos.
Después de completar la migración, los nuevos usos de OField::DATE representan verdaderas columnas SQL DATE.
BIGINT
9.12 añade OField::BIGINT.
#[OField(
type: OField::BIGINT
)]
public ?int $external_id = null;
También puede utilizarse en #[OPK], incluido autoincremento.
BIGINT requiere PHP de 64 bits.
No se admiten UNSIGNED ni ZEROFILL.
generateModelFromDB
generateModelFromDB reconoce ahora:
DATE → OField::DATE
DATETIME → OField::DATETIME
BIGINT → OField::BIGINT
Las columnas SQL TIMESTAMP siguen rechazándose porque no pueden representarse fielmente mediante la semántica DATETIME del ORM.
Pipes y formato
El pipe date admite tanto DATE como DATETIME.
Sin máscara explícita:
DATE → d/m/Y
DATETIME → d/m/Y H:i:s
El método OModel::get() también admite ambos tipos temporales con una máscara explícita.
Estado de migraciones
9.12 mueve el estado autoritativo de migraciones desde:
ofw/tmp/state.json
a:
.ofw-migrations.json
en la raíz del proyecto.
Este archivo forma parte del estado versionado de la aplicación y debe incluirse en Git.
Durante la primera actualización a 9.12, si .ofw-migrations.json aún no existe, el runner puede leer ofw/tmp/state.json para recuperar el último paso ejecutado.
Una vez completada una migración con 9.12, el nuevo archivo pasa a ser la fuente autoritativa.
Este cambio evita que la limpieza de ofw/tmp/ pueda provocar la repetición accidental de una migración antigua.
Actualización
Antes de actualizar, asegúrese de que el árbol Git de la aplicación esté limpio.
Actualice normalmente mediante Composer:
composer update osumionline/framework --with-dependencies
La migración 9.12.0 se ejecutará automáticamente cuando corresponda.
Después de la actualización:
- Revise los modelos modificados.
- Añada
.ofw-migrations.jsonal repositorio. - Ejecute la batería de tests de la aplicación.
- Verifique funcionalmente los campos temporales y BIGINT utilizados por la aplicación.