9.9.0 - Nuevo sistema de Middlewares y migraciones automáticas de proyectos.

Osumi Framework 9.9.0

Osumi Framework 9.9.0 incorpora un nuevo sistema nativo de Middlewares, sustituye la arquitectura anterior de Filters e introduce un motor de migraciones automáticas de proyectos integrado con Composer.

Se trata de una versión importante con cambios incompatibles para aplicaciones que utilicen Filters, pero incluye una migración automática diseñada para conservar su lógica actual mediante adaptadores de compatibilidad.

Middlewares

El nuevo pipeline permite ejecutar Middlewares en tres fases:

• before: antes de ejecutar el componente.
• afterRender: después de renderizar el componente y antes del layout.
• afterResponse: después de generar la respuesta final y antes de enviarla.

Los Middlewares pueden configurarse a nivel:

• global
• grupo
• ruta

En cada fase se ejecutan en este orden:

global
→ grupo exterior
→ grupo interior
→ ruta

Un Middleware puede:

• publicar contexto;
• modificar el cuerpo de la respuesta;
• añadir o sustituir cabeceras;
• cambiar el código de estado HTTP;
• detener el pipeline mediante stop;
• devolver errores tipados según el tipo de respuesta.

Los Middlewares globales se configuran en:

src/Middleware/Middlewares.php

Contexto de Middleware

ORequest incorpora:

$req->getMiddleware('Login');
$req->getMiddlewareValue('Login', 'id');

Los DTO también pueden utilizar contexto de Middleware como origen explícito:

#[ODTOField(
	required: true,
	middleware: 'Login',
	middlewareProperty: 'id'
)]
public ?int $idUser = null;

Esto permite utilizar valores de confianza generados en servidor, como el ID del usuario autenticado, sin aceptar sustituciones desde los parámetros enviados por el cliente.

Filters

Los Filters dejan de formar parte del runtime de Osumi Framework.

El código nuevo debe utilizar Middlewares.

También se elimina la creación de nuevos Filters mediante la CLI:

php of add --option middleware --name Login

es ahora la forma recomendada de generar este tipo de lógica transversal.

Migraciones automáticas

9.9.0 incorpora un sistema de migraciones versionadas para actualizar proyectos cuando cambia la API del framework.

El paquete expone:

php vendor/bin/ofw-migrate

con soporte para:

• --from
• --to
• --dry-run
• --force
• --verbose
• --no-interaction
• --help

El estado se almacena en:

ofw/tmp/state.json

Las migraciones son idempotentes y los cambios se aplican de forma transaccional, con copias de seguridad y rollback automático en caso de error.

Integración con Composer

El nuevo sistema se integra con:

osumionline/plugin-updater

Durante una actualización mediante Composer, el plugin detecta la versión instalada y ejecuta automáticamente las migraciones pendientes después de regenerar el autoloader.

La aplicación debe autorizar el plugin en su composer.json:

{
	"config": {
		"allow-plugins": {
			"osumionline/plugin-updater": true
		}
	}
}

También están disponibles:

OFW_DRY_RUN
OFW_FORCE
OFW_VERBOSE

Migración automática de Filters

El paso de migración 9.9.0:

• detecta Filters antiguos bajo src/Filter/;
• conserva sus archivos y su lógica original;
• genera adaptadores *Middleware.php;
• transforma rutas con Filters a Middlewares before;
• cambia getFilter() por getMiddleware();
• cambia filter / filterProperty de DTO por middleware / middlewareProperty;
• crea src/Middleware/Middlewares.php si no existe.

La migración realiza primero un preflight completo y se detiene ante construcciones ambiguas que no pueda transformar de forma segura.

Entre los casos que requieren intervención manual están:

getFilters()
setFilter()
setFilters()

y las expresiones dinámicas de Filters utilizadas en rutas.

Semántica de stop

stop tiene la misma semántica en las tres fases.

• En before, evita ejecutar el componente y el layout.
• En afterRender, evita aplicar el layout.
• En ambos casos, afterResponse sigue ejecutándose.
• En afterResponse, detiene los Middlewares restantes de esa fase y sustituye la respuesta final por el error tipado.

Los Middlewares afterResponse pueden inspeccionar el estado de errores producidos en fases anteriores.

Robustez y compatibilidad con PHP 8.5

Durante el desarrollo de 9.9 se ha realizado una auditoría amplia del framework, incluyendo mejoras en:

• tipado y contratos internos;
• routing y normalización;
• DTOs y ORequest;
• sesiones y ejecución CLI;
• ORM;
• configuración;
• manejo de errores;
• filesystem y operaciones temporales;
• validaciones de firmas de componentes;
• compatibilidad con PHP 8.5;
• eliminación de avisos deprecados.

También se corrigió OColors para evitar el uso de null como índice de array en PHP 8.5.

Nuevo skeleton

El repositorio osumionline/new ha sido actualizado para crear directamente proyectos 9.9 nativos:

• utiliza src/Middleware/;
• incluye Middlewares.php;
• los ejemplos usan Middlewares nativos;
• ya no incluye Filters;
• requiere osumionline/framework ^9.9.0.

Documentación

La documentación se ha actualizado en:

• inglés;
• castellano;
• euskera.

Incluye:

• concepto completo de Middlewares;
• routing, DTOs, components, layouts, services y CLI;
• quickstart y recipes;
• documentación específica para LLM;
• llms.txt;
• guía completa de migración 9.8.5 → 9.9.0.

Compatibilidad

9.9.0 es incompatible a nivel de API con el antiguo runtime de Filters.

La migración automática proporciona un puente para proyectos existentes, pero los adaptadores generados están pensados como compatibilidad temporal.

Para nuevo desarrollo se deben utilizar siempre Middlewares nativos.