Migration Guide: 9.11.0 → 9.12.0
Osumi Framework 9.12.0 adds native support for SQL DATE, DATETIME and BIGINT columns and redefines the meaning of OField::DATE.
This version includes an automatic migration step to preserve compatibility with existing models.
DATE and DATETIME
Until Osumi Framework 9.11, OField::DATE actually generated an SQL DATETIME column.
Starting with 9.12, the types are represented independently:
OField::DATE → SQL DATE → PHP ?string → Y-m-d
OField::DATETIME → SQL DATETIME → PHP ?string → Y-m-d H:i:s
For example:
#[OField(
type: OField::DATE
)]
public ?string $event_date = null;
#[OField(
type: OField::DATETIME
)]
public ?string $processed_at = null;
Temporal values are strictly validated and invalid calendar dates or times are rejected.
#[OCreatedAt], #[OUpdatedAt] and #[ODeletedAt] fields continue to represent full timestamps and internally use DATETIME.
Automatic OField::DATE Migration
Models created with versions earlier than 9.12 used OField::DATE with DATETIME semantics.
During the upgrade, migration step 9.12.0 automatically transforms:
OField::DATE
into:
OField::DATETIME
inside existing models under src/Model/.
The migration modifies only actual PHP code tokens and does not alter occurrences inside comments or string literals.
It does not modify the database schema: it preserves the DATETIME semantics those fields already had.
After the migration has completed, new uses of OField::DATE represent real SQL DATE columns.
BIGINT
9.12 adds OField::BIGINT.
#[OField(
type: OField::BIGINT
)]
public ?int $external_id = null;
It can also be used with #[OPK], including auto-increment primary keys.
BIGINT requires a 64-bit PHP environment.
UNSIGNED and ZEROFILL are not supported.
generateModelFromDB
generateModelFromDB now recognizes:
DATE → OField::DATE
DATETIME → OField::DATETIME
BIGINT → OField::BIGINT
SQL TIMESTAMP columns are still rejected because they cannot be represented faithfully by the ORM DATETIME semantics.
Pipes and Formatting
The date template pipe supports both DATE and DATETIME.
Without an explicit mask:
DATE → d/m/Y
DATETIME → d/m/Y H:i:s
OModel::get() also supports both temporal types with an explicit formatting mask.
Migration State
9.12 moves the authoritative migration state from:
ofw/tmp/state.json
to:
.ofw-migrations.json
at the project root.
This file is part of the versioned application state and must be committed to Git.
During the first upgrade to 9.12, when .ofw-migrations.json does not yet exist, the runner can read ofw/tmp/state.json to recover the last executed migration step.
Once a migration has completed under 9.12, the new file becomes the authoritative source.
This prevents cleaning ofw/tmp/ from accidentally causing an old migration to run again.
Updating
Before upgrading, make sure the application Git working tree is clean.
Update normally through Composer:
composer update osumionline/framework --with-dependencies
Migration step 9.12.0 will run automatically when applicable.
After upgrading:
- Review the modified models.
- Add
.ofw-migrations.jsonto the repository. - Run the application's complete test suite.
- Functionally verify any temporal and BIGINT fields used by the application.