Osumi Framework
es en eu v9.12.1 GitHub

ORM (Objektu-Erlazio Mapeatzea)

Osumi Framework-ak ORM arin bat dauka, PHP klaseak datu-baseko tauletara PHP Atributuak erabiliz mapatzen dituena. Modelo guztiek OModel klasea zabaldu behar dute.

Modelo bat definitzea

Modeloak src/Model/-n gordetzen dira. Framework-ak automatikoki ondorioztatzen du taularen izena klase-izenetik snake_case erabiliz (adibidez, ProductCategory klasea product_category taulara mapatzen da).

Nahitaezko eremuak

Modelo bat baliozkoa izateko, honako atributu hauek definitu behar ditu:

Ereduaren Adibidea

<?php declare(strict_types=1);

namespace Osumi\OsumiFramework\App\Model;

use Osumi\OsumiFramework\ORM\OModel;
use Osumi\OsumiFramework\ORM\OPK;
use Osumi\OsumiFramework\ORM\OField;
use Osumi\OsumiFramework\ORM\OCreatedAt;
use Osumi\OsumiFramework\ORM\OUpdatedAt;

class User extends OModel {
  #[OPK(comment: 'ID Bakarra')]
  public ?int $id = null;

  #[OField(max: 100, nullable: false)]
  public ?string $name = null;

  #[OCreatedAt(comment: 'Sortze data')]
  public ?string $created_at = null;

  #[OUpdatedAt(comment: 'Azken eguneraketa')]
  public ?string $updated_at = null;
}

Oinarrizko Atributuak

Atributua Deskribapena
#[OPK] Lehen mailako giltza. Gako konposatuetarako hainbat eremutan erabil daiteke. Berez, automatikoki gehitzen da, bestela gehitu incr balioa false gisa.
#[OField] Zutabe estandarra. max, nullable eta ref onartzen ditu.
#[OCreatedAt] Erregistroen sorreraren jarraipenerako nahitaezko eremua.
#[OUpdatedAt] Erregistroen eguneratzeen jarraipenerako nahitaezko eremua.

**Oharra ref**-ri buruz: refparametroa (adibidez,ref: 'user.id') sortutako SQL-an (CREATE TABLE) kanpoko gakoak definitzeko erabiltzen da, baina ez du objektuen kargatze automatikoa abiarazten.

Datuekin lan egitea

Erregistroak aurkitzea

Datuak metodo estatikoak erabiliz berreskuratzea:

  $user = User::where(['id' => 1]);
  if (!is_null($user)) {
    echo "Erabiltzailea ".$user->name." aurkitu da";
  }

Gordetzea eta eguneratzea

save() metodoak automatikoki detektatzen du erregistro bat berria edo lehendik dagoen PK-an oinarrituta.

$user = new User();
$user->name = 'Erabiltzaile Berria';
$user->save(); // INSERT bat egiten du

$user = User::findOne(['id' => 1]);
$user->name = 'Izen berria';
$user->save(); // UPDATE bat egiten du

Balidazioa

Framework-ak validate() deitzen du save() prozesuan. Balio batek max luzera gainditzen badu edo null bada baimenduta ez dagoenean, Salbuespen bat sortzen da.

DECIMAL eremu zehatzak

Puntu mugikorreko irudikapenetik igaro behar ez duten balioetarako, hala nola diru-kopuruak, ehunekoak edo zehaztasun finkoko kantitateak, erabili OField::DECIMAL.

#[OField(
	type: OField::DECIMAL,
	precision: 12,
	scale: 2,
	nullable: false,
	comment: 'Zenbatekoa'
)]
public ?string $amount = null;

DECIMAL eremuak beti ?string bidez irudikatzen dira, inoiz ez ?float bidez.

ORM-ak . eta , onartzen ditu sarrerako bereizle hamartar gisa, eta balioa . erabiliz eta scale finkoarekin normalizatzen du:

$model->amount = '12,5';
$model->save();

// $model->amount === '12.50'

Ez da biribiltze automatikorik egiten. Balio batek konfiguratutako precision edo scale gainditzen badu, ORM-ak errorea sortzen du.

Kontsulten baldintzek arau berak jarraitzen dituzte:

Payment::where([
	'amount' => '12,5'
]);

barnean "12.50" baliora normalizatzen da; aldiz:

Payment::where([
	'amount' => 12.5
]);

ez da baliozkoa, float balio bat ezin baita DECIMAL eremu baterako erabili.

DECIMAL eremuak ezin dira lehen mailako gako gisa erabili.

DATE eta DATETIME eremuak

Osumi Framework 9.12 bertsiotik aurrera, SQL DATE eta DATETIME motak bereizita irudikatzen dira.

SQL DATE eremu batek OField::DATE eta PHP ?string propietate bat erabiltzen ditu:

#[OField(
	type: OField::DATE,
	nullable: false
)]
public ?string $event_date = null;

Bere formatu kanonikoa hau da:

Y-m-d

adibidez:

2026-10-14

SQL DATETIME eremu batek OField::DATETIME erabiltzen du:

#[OField(
	type: OField::DATETIME,
	nullable: false
)]
public ?string $processed_at = null;

Bere formatu kanonikoa hau da:

Y-m-d H:i:s

adibidez:

2026-10-14 15:30:45

ORM-ak denbora-balioak modu zorrotzean balidatzen ditu. 2026-02-30 bezalako existitzen ez diren datak edo baliogabeko orduak baztertzen dira.

#[OCreatedAt], #[OUpdatedAt] eta #[ODeletedAt] atributu automatikoek DATETIME erabiltzen dute barnean.

Osumi Framework 9.12.1 bertsiotik aurrera, DATETIME eremuek OField::CURRENT_TIMESTAMP erabil dezakete balio lehenetsi dinamiko gisa:

#[OField(
	type: OField::DATETIME,
	nullable: false,
	default: OField::CURRENT_TIMESTAMP
)]
public ?string $joined_at = null;

SQL eskema sortzean, definizio horrek hau sortzen du:

`joined_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP

Modelo berrietan, ORM-ak OField::CURRENT_TIMESTAMP uneko timestamp-era bihurtzen du Y-m-d H:i:s formatuan balio lehenetsiak aplikatzen direnean.

OField::CURRENT_TIMESTAMP OField::DATETIME eremuekin soilik erabil daiteke. CURRENT_TIMESTAMP edukia duen testu literal bat testu-balio arrunta izaten jarraitzen du eta ez da SQL adierazpen gisa interpretatzen.

generateModelFromDB tresnak CURRENT_TIMESTAMP eta CURRENT_TIMESTAMP() ezagutzen ditu DATETIME zutabeetan eta default: OField::CURRENT_TIMESTAMP sortzen du. Beste SQL adierazpen dinamikoek ez dute euskarririk eta esplizituki baztertzen dira.

get() metodoak bi denbora-motei formatu-maskara bat aplika diezaieke:

$model->get(
	'event_date',
	'd/m/Y'
);

$model->get(
	'processed_at',
	'd/m/Y H:i'
);

Txantiloietako date pipe-ak bi formatuak onartzen ditu. Maskara espliziturik gabe:

BIGINT eremuak

SQL BIGINT sinatutako zutabeek OField::BIGINT eta PHP ?int propietateak erabiltzen dituzte:

#[OField(
	type: OField::BIGINT
)]
public ?int $external_id = null;

Lehen mailako gako gisa ere erabil daitezke:

#[OPK(
	type: OField::BIGINT
)]
public ?int $id = null;

BIGINT erabiltzeko 64 biteko PHP ingurunea behar da.

ORM-ak ez ditu BIGINT UNSIGNED zutabeak edo ZEROFILL modifikatzaileak onartzen.

CLI integrazioa

Praktika onak

llms osumi-framework-llm.md Markdown bertsioa