Osumi Framework
es en eu v9.12.1 GitHub

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:

  1. Review the modified models.
  2. Add .ofw-migrations.json to the repository.
  3. Run the application's complete test suite.
  4. Functionally verify any temporal and BIGINT fields used by the application.