Migrazio-gida: 9.8.5 → 9.9.0

9.9.0 bertsioak Filter zaharren runtime-a faseetan oinarritutako Middleware sistemarekin ordezkatzen du eta Osumi Framework-en aplikazio-migrazio bertsionatuen lehen motorra gehitzen du.

Filterrak erabiltzen dituzten aplikazioentzat bateragarritasun-haustura duen bertsioa da.

Framework-ak migrazio automatiko bat dauka, onartutako Filter erabilerak Middleware sistemara bihurtzeko eta jatorrizko Filter negozio-logika mantentzeko.

Laburpena

Gehitua

• Hiru fasetako Middleware pipeline natiboa:
  • before
  • afterRender
  • afterResponse
• Middleware globalak, taldekoak eta ibilbidekoak.
• src/Middleware/Middlewares.php konfigurazio globalerako.
• ORequest::getMiddleware().
• ORequest::getMiddlewareValue().
• ODTOField-en Middleware iturburuak:
  • middleware
  • middlewareProperty
• stop bidezko errore-erantzun tipatuak.
• Framework migrazio-motorra.
• vendor/bin/ofw-migrate.
• Migrazio-kopia transakzionalak.
• Migrazio-egoera ofw/tmp/state.json fitxategian.
• Composer integrazioa osumionline/plugin-updater bidez.

Aldatua

• Ibilbideko Filterrak faseen arabera definitutako Middlewareekin ordezkatzen dira.
• Filter zaharren irteera Middleware testuinguru gisa azaltzen da migrazio automatikoaren ondoren.
• ODTOField(filter: ..., filterProperty: ...) → middleware / middlewareProperty.
• $req->getFilter('Name') → $req->getMiddleware('Name').
• Autentifikazioa, baimena eta eskaera-interzepzioa Middleware natiboekin egin behar dira.

9.9 runtime-tik kendua

• Filter pipeline-a.
• CLI bidez Filter berriak sortzea.
• Filterrei lotutako ORequest API legacy-ak.

Filter klase zaharrak aldi baterako gera daitezke migratutako proiektuetan, migrazioak haien gaineko bateragarritasun Middleware adapterrak sortzen dituelako.

1. Eguneratu aurreko baldintzak

Osumi Framework 9.9k behar ditu:

• PHP 8.5 edo berriagoa.
• Composer 2.x.
• osumionline/plugin-updater.
• Composer-ek updater plugina exekutatzeko baimena.

Eguneratu aurretik, gehitu hau proiektuaren erroko composer.json fitxategian oraindik ez badago:

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

Composer-ek lehen instalazioan pluginean konfiantza izateko galdetu dezake.

2. Gomendatutako eguneratze-prozedura

Eguneratu aurretik:

1. Egin commit edo stash aplikazioaren aldaketekin.
2. Ziurtatu proiektua egoera funtzional ezagun batean dagoela.
3. Produkzioan, egin datu iraunkorren kopia.
4. Eguneratu framework-a Composer bidez.

Adibidea:

composer update osumionline/framework --with-dependencies

Composer-ek autoloader-a berreraiki ondoren, osumionline/plugin-updater-ek instalatutako framework bertsioa egiaztatzen du eta zain dauden migrazio guztiak exekutatzen ditu.

9.8.5 → 9.9.0 eguneratzean 9.9.0 migrazio-pausoa exekutatzen da.

3. Composer bidezko migrazio automatikoa

Fluxua:

Composer update
↓
osumionline/plugin-updater
↓
post-autoload-dump
↓
Runner::runPending()
↓
9.9.0 migrazioaren preflight-a
↓
proiektuaren aldaketa transakzionalak
↓
state.json eguneratzea

Migrazio-egoera da iturri autoritarioa. Horri esker migrazioak ondo exekutatzen dira nahiz eta:

• framework-aren hainbat bertsio batera saltatu;
• updater plugina Composer operazio berean instalatu;
• Composer-ek autoload event bat baino gehiago jaulki.

Composer-ek abiarazitako migrazioetan Git egiaztapenak bi fitxategi hauek bakarrik baztertzen ditu:

composer.json
composer.lock

Aplikazio-kodeko edo beste fitxategietako aldaketek migrazioa geldiarazten jarraitzen dute, exekuzio behartua esplizituki aktibatu ezean.

4. Composer migrazioen aurrebista

Updater-ak ingurune-aldagaiak onartzen ditu.

Dry-run

OFW_DRY_RUN=1 composer update osumionline/framework --with-dependencies

Honek framework migrazioa dry-run moduan exekutatzen du.

Garrantzitsua: Composer-ek bere pakete-operazioa egiten jarraitzen du. OFW_DRY_RUN-ek Osumi Framework migrazioaren proiektu-aldaketak bakarrik saihesten ditu.

Irteera xehea

OFW_VERBOSE=1 composer update osumionline/framework --with-dependencies

Segurtasun-egiaztapenak behartzea

OFW_FORCE=1 composer update osumionline/framework --with-dependencies

Erabili kontu handiz. Exekuzio behartua onartzen duten migrazio-segurtasun egiaztapenak saihesten ditu.

Balio boolean onartuak:

1
true
yes
y
on

eta:

0
false
no
n
off

5. Migrazioen CLI manuala

Framework paketeak hau eskaintzen du:

php vendor/bin/ofw-migrate --help

Zain dauden migrazioak exekutatzeko:

php vendor/bin/ofw-migrate

Ikuskapenerako gomendatutako komandoa:

php vendor/bin/ofw-migrate --dry-run --verbose

Aukerak:

--from=VERSION
--to=VERSION
--dry-run
--force
--verbose
--no-interaction
--help

--from

Migrazio-egoeratik jasotako jatorrizko bertsioa ordezkatzen du.

Adibidea:

php vendor/bin/ofw-migrate --from=9.8.5 --to=9.9.0

Erabili soilik bertsio-tarte esplizitua nahita behar duzunean.

--to

Helburuko bertsioa ordezkatzen du. Ez bada adierazten, instalatutako framework bertsioa automatikoki detektatzen da.

--dry-run

Planifikatutako eragiketak erakusten ditu proiektu-fitxategiak aldatu gabe.

--force

Exekuzio behartua onartzen duten segurtasun-egiaztapenak saihesten ditu, Git lan-zuhaitz garbiaren egiaztapena barne.

--verbose

Migrazioen eta fitxategi-eragiketen xehetasunak erakusten ditu.

--no-interaction

Portaera interaktiboa desgaitzen du.

6. Git lan-zuhaitzaren babesa

Migrazio manual normal batean, Git bidez kudeatutako proiektu batek lan-zuhaitz garbia izan behar du.

Ustekabeko aldaketak badaude, migrazioa gelditzen da proiektua aldatu beharrean.

.git gabeko proiektuak ere onartzen dira; migrazio-kopia transakzionalak erabiltzen jarraitzen dute.

Dry-run moduak ez du lan-zuhaitz garbirik behar, ez duelako aldaketarik gordetzen.

Composer bidezko migrazio automatikoan composer.json eta composer.lock bakarrik baztertzen dira egiaztapen horretatik.

Hobe da commit edo stash egitea --force erabiltzea baino.

7. Zer egiten du 9.9.0 migrazioak

Migrazioak preflight osoa egiten du aplikazio-fitxategirik idatzi aurretik.

Filter zaharrak hemen bilatzen ditu:

src/Filter/

Onartutako Filterrek Osumi Framework-en ohiko PSR-4 namespace eta fitxategi-izen konbentzioak bete behar dituzte.

Jatorrizko Filter fitxategiak ez dira ezabatzen edo berridazten.

Filter bakoitzeko bateragarritasun Middleware bat sortzen da hemen:

src/Middleware/

Adibidea:

src/Filter/LoginFilter.php
↓ mantentzen da

src/Middleware/LoginMiddleware.php
↓ sortutako bateragarritasun adapterra

Adapter sortuek Filter originala fase honetan bakarrik exekutatzen dute:

OMiddleware::PHASE_BEFORE

8. Filter zaharraren emaitzaren bihurketa

Adapterrak Filter emaitza 9.9 Middleware kontratura bihurtzen du.

Filter zuzena

Emaitza zaharra:

[
	'status' => 'ok',
	'id' => 42
]

testuinguru bihurtzen da:

[
	'context' => [
		'status' => 'ok',
		'id' => 42
	]
]

Hau irakur daiteke:

$login = $req->getMiddleware(
	'Login'
);

edo:

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

Huts egindako Filterra

Zuzena ez den Filter emaitza stop bihurtzen da HTTP 403rekin.

Redirect zaharra

Filterrak return balioan URL balioduna itzultzen badu, adapterrak sortzen du:

• HTTP 302
• Location goiburua
• stop

Horrek legacy portaera mantentzen du migrazioan.

9. Kodearen transformazio automatikoak

Migrazioak src/Filter/ eta src/Middleware/ kanpoko kode bateragarria eraldatzen du.

ORequest

Aurretik:

$login = $req->getFilter(
	'Login'
);

Ondoren:

$login = $req->getMiddleware(
	'Login'
);

DTOak

Aurretik:

#[ODTOField(
	filter: 'Login',
	filterProperty: 'id'
)]
public ?int $idUser = null;

Ondoren:

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

Ibilbideak

Aurretik:

ORoute::get(
	'/profile',
	ProfileComponent::class,
	[
		LoginFilter::class
	]
);

Ondoren:

ORoute::get(
	'/profile',
	ProfileComponent::class,
	[
		'before' => [
			\Osumi\OsumiFramework\App\Middleware\LoginMiddleware::class
		]
	]
);

Onartutako ORoute deietako Filter array literalak before Middleware zerrendetara bihurtzen dira.

10. Middleware konfigurazio globala

Fitxategi hau ez badago:

src/Middleware/Middlewares.php

migrazioak sortzen du:

<?php

declare(strict_types=1);

namespace Osumi\OsumiFramework\App\Middleware;

use Osumi\OsumiFramework\Core\OMiddleware;

OMiddleware::setGlobal([
	OMiddleware::PHASE_BEFORE => [],
	OMiddleware::PHASE_AFTER_RENDER => [],
	OMiddleware::PHASE_AFTER_RESPONSE => []
]);

Lehendik badago, bere edukia zehazki mantentzen da.

11. Automatikoki migratzen ez diren kasuak

Migrazioa nahita gelditzen da kodea modu seguruan eraldatu ezin duenean.

Ibilbideetako Filter adierazpen dinamikoak

Ez da onartzen:

$filters = [
	LoginFilter::class
];

ORoute::get(
	'/profile',
	ProfileComponent::class,
	$filters
);

Migrazio automatikorako ibilbideetako Filter adierazpenek klase-array literalak izan behar dute.

ORequest metodo legacy-ak

Eskuz aldatu behar dira:

$req->getFilters()
$req->setFilter(...)
$req->setFilters(...)

Migrazioa gelditzen da dei horiek aurkitzen baditu.

Ebatzi ezin diren Filter erreferentziak

Migratu daitekeen Filter definizio batekin lotu ezin den Filter bati erreferentzia egiten dion ibilbidea baztertzen da.

Lehendik dauden Middlewareekin gatazkak

Sortu beharreko Middleware fitxategia lehendik edukia desberdinarekin badago, migrazioa gelditzen da gainidatzi beharrean.

Fitxategi-egitura ez-seguruak

Esteka sinbolikoen bidezko ibilbideak eta proiektu-bide ez-seguruak baztertzen dira.

Migrazioa nahita kontserbadorea da: kode anbiguoa eskuz migratu behar da, bere asmoa asmatzen saiatu beharrean.

12. Segurtasun transakzionala eta rollback-a

Aldaketak sistema transakzional baten bidez idazten dira.

Kopiak hemen gordetzen dira:

ofw/tmp/migrations/

Transakzio bakoitzak timestamp/identifikatzaile ausazkoa duen direktorio propioa eta aldatu diren fitxategien manifest bat dauka.

Migrazio-egoera aplikazioaren aldaketen transakzio berean idazten da.

Eragiketa batek huts egiten badu:

1. aldatutako fitxategiak leheneratzen dira;
2. huts egindako migrazioak sortutako fitxategiak ezabatzen dira;
3. egoera proiektuarekin batera leheneratzen da;
4. migrazioa errorearekin amaitzen da.

Ondo bukatutako transakzioen kopiak diskoan mantentzen dira ikuskapenerako.

13. Migrazio-egoera

Egoera hemen gordetzen da:

ofw/tmp/state.json

9.9.0 ondo amaitu ondoren:

{
	"last_migrated": "9.9.0"
}

Egoera-fitxategirik ez badago, runner-ak 0.0.0 erabiltzen du hasierako migrazio-bertsio gisa eta instalatutako helburura arteko pauso aplikagarri guztiak hautatzen ditu.

Horri esker migrazio-motorra existitu aurretik sortutako proiektuak eguneratu daitezke.

Ondorengo exekuzio normal batek ez du 9.9.0 berriro aplikatzen.

14. Idempotentzia

Migrazio-sistema idempotentea izateko diseinatuta dago.

Adibidez:

• Egoerak exekuzio normal batean bukatutako pausoak errepikatzea saihesten du.
• Lehendik sortutako adapter bat onartzen da edukia zehazki berdina bada.
• Lehendik dagoen Middlewares.php mantentzen da.
• Bigarren exekuzio normal batek ez du 9.9.0 migrazioa zain aurkitzen.

Ez erabili --from bukatutako migrazio bat nahita berriro hautatzeko, ondorioak ezagutzen ez badituzu.

15. Migrazioaren ondorengo egiaztapena

Migrazioaren ondoren:

1. Berrikusi src/Middleware/ barruan sortutako fitxategiak.
2. Berrikusi eraldatutako ibilbideak.
3. Berrikusi middleware / middlewareProperty erabiltzen dituzten DTOak.
4. Bilatu runtime legacy erabilerak.
5. Exekutatu test guztiak.
6. Egin autentifikazio/baimen proba funtzionalak.
7. Egin commit migratutako kodearekin.

Bilaketa erabilgarriak:

getFilter(
getFilters(
setFilter(
setFilters(
filterProperty

Normala da src/Filter/-eko legacy klaseak oraindik egotea bateragarritasun adapterrak erabiltzen diren bitartean.

16. Sortutako adapterrak Middleware natibo bihurtzea

Sortutako adapterrak bateragarritasun-zubia dira, ez gomendatutako azken arkitektura.

Migratutako proiektua egiaztatu ondoren, Filter logika pixkanaka Middleware klasera eraman daiteke.

Middleware natibo batek hau erabiltzen du:

public static function handle(
	string $phase,
	array $data
): array

eta emaitza esplizituak itzultzen ditu, adibidez:

return [
	'context' => [
		'id' => 42
	]
];

edo:

return [
	'stop' => true,
	'status_code' => 401,
	'message' => 'Unauthorized'
];

Gomendatutako prozesua:

Filter legacy-a
↓
sortutako bateragarritasun Middlewarea
↓
egiaztapen funtzionala
↓
logika Middleware natibora eraman
↓
erabiltzen ez den Filterra ezabatu

Mantendu ahal denean sortutako Middleware klasearen izena, dagoeneko migratutako ibilbideak eta testuinguru-izen publikoak berriro aldatu behar ez izateko.

Adapter guztiak bihurtu ondoren, src/Filter/ ezaba daiteke beharrezko legacy logikarik geratzen ez bada.

17. Middlewareen gaitasun berriak

Middleware natiboak ez daude Filter zaharren portaerara mugatuta.

Fase hauetan exekuta daitezke:

before
afterRender
afterResponse

Honako hauek argitaratu edo alda ditzakete:

• testuingurua
• gorputza
• goiburuak
• HTTP egoera
• stop bidezko errore-erantzunak

Middleware globalak, talde habiaratuetakoak eta ibilbidekoak fase bakoitzean ordena honetan metatzen dira:

globala
↓
kanpoko taldea
↓
barneko taldea
↓
ibilbidea

Ikusi:

docs/eu/concepts/middlewares.md

9.9 Middleware API osoa ezagutzeko.

18. Garatzaileak egin beharrekoa

9.8.5etik eguneratzen diren aplikazioetan:

1. Ziurtatu PHP 8.5+ erabiltzen dela.
2. Baimendu osumionline/plugin-updater Composer konfigurazioan.
3. Egin commit edo stash tokiko aldaketekin.
4. Eguneratu Osumi Framework Composer bidez.
5. Berrikusi migrazio automatikoaren irteera.
6. Konpondu eskuz migratzaileak adierazitako onartu gabeko legacy egiturak.
7. Exekutatu test osoak eta proba funtzionalak.
8. Egin commit migratutako kodearekin.
9. Aukeran, ordezkatu bateragarritasun adapterrak Middleware natiboekin.

Filterrik erabiltzen ez duten proiektuetan ere, 9.9 migrazioak beharrezkoa denean src/Middleware/Middlewares.php sortzen du eta migrazio-egoera erregistratzen du.

19. Aurreko bertsioekiko bateragarritasuna

9.9.0k nahita kentzen du Filter runtime arkitektura.

Adapter automatikoek eguneratze-bide bat eskaintzen dute onartutako legacy proiektuentzat, baina 9.9ko kode berriak Middlewareak erabili behar ditu.

Ez gehitu Filter berririk migrazioaren ondoren.