Datu Transferentzia Objektuak (DTOak)

Osumi Framework-eko DTOak HTTP eskaera batetik datozen sarrera-datuak jasotzeko, normalizatzeko eta baliozkotzeko erabiltzen diren klase sinpleak dira.

Osagaiek eskaera-balio tipatu eta balioztatuak, HTTP goiburuak edo Middleware testuingurua modu egituratu eta seguruan atzitzeko aukera ematen dute.

DTO batek ODTO hedatu behar du eta bere eremuak #[ODTOField] atributuarekin definitu.

1. DTO baten helburua

DTOak honetarako diseinatuta daude:

• Eskaera-datuak bildu eta motaz aldatzeko.
• Middleware testuingurutik konfiantzazko balioak irakurtzeko.
• HTTP goiburuetatik balioak irakurtzeko.
• Balidazio-arauak osagaiaren logika exekutatu aurretik aplikatzeko.
• Eskaera-prozesamendua framework osoan koherente mantentzeko.
• Osagaien barruan $req->getParam...() dei errepikatuak saihesteko.

Osagai batek hau definitzen duenean:

public function run(MovieDTO $dto): void

framework-ak automatikoki:

1. MovieDTO instantziatzen du.
2. Bere balioak kargatzen ditu.
3. Balidazio-arauak aplikatzen ditu.
4. run() metodoan injektatzen du.

2. Oinarrizko klasea: ODTO

ODTO-k reflection erabiltzen du DTOaren propietate publikoak eta haien #[ODTOField] definizioak aztertzeko.

2.1 Datu-iturburuak

Eremu batek iturburu esplizitu bat erabil dezake.

Middleware testuingurua

middleware eta middlewareProperty definituta badaude, balioa honela lortzen da:

$req->getMiddlewareValue(
	$middlewareName,
	$middlewareProperty
);

Middleware testuingurua iturburu esplizitua da. Testuinguru-balioa ez badago, DTOaren balioa null izaten jarraitzen du; ez da bezeroaren sarrerara itzultzen.

Goiburua

header definituta badago, balioa dagokion HTTP goiburutik hartzen da.

Eremu batek ezin ditu Middleware iturburua eta goiburu-iturburua aldi berean definitu.

Eskaera-parametroak

Iturburu espliziturik ez dagoenean, balioa eskaera-parametroetatik kargatzen da propietate motaren arabera:

• int → getParamInt()
• float → getParamFloat()
• bool → getParamBool()
• string → getParamString()
• array → getParam()

2.2 Balidazioa

Balioak kargatu ondoren, ODTOk honako hauek ebaluatzen ditu:

• required
• requiredIf

Balidazio-erroreak honela lor daitezke:

$dto->getValidationErrors();

DTOa baliozkoa den egiaztatzeko:

$dto->isValid();

3. ODTOField

#[ODTOField(
	required: false,
	requiredIf: null,
	middleware: null,
	middlewareProperty: null,
	header: null
)]

Arauak:

• middleware eta middlewareProperty batera definitu behar dira.
• Middleware izen edo propietate hutsak ez dira baliozkoak.
• Eremu batek ezin ditu Middleware testuingurua eta goiburua batera erabili iturburu esplizitu gisa.
• requiredIf-ek beste DTO eremu bati egin behar dio erreferentzia eta ezin dio bere buruari erreferentziarik egin.

4. DTO adibidea

class MovieDTO extends ODTO {
	#[ODTOField(required: true)]
	public ?int $idCinema = null;

	#[ODTOField(required: true)]
	public ?string $name = null;

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

Adibide honetan, idUser LoginMiddleware-k argitaratutako testuingurutik lortzen da, ez bezeroak bidalitako datuetatik.

5. DTO bat osagai batean erabiltzea

class AddMovieComponent extends OComponent {
	public function run(MovieDTO $dto): void {
		if (!$dto->isValid()) {
			$this->errors = $dto->getValidationErrors();
			return;
		}

		$movie = new Movie();
		$movie->name = $dto->name;
		$movie->idUser = $dto->idUser;
		$movie->save();
	}
}

6. Praktika onak

• Erabili propietate mota zorrotzak.
• Hobetsi balio nullable-ak eremua hasieran falta daitekeenean.
• Erabili DTOak eskaera-sarrera egituratuetarako.
• Erabili requiredIf eremuen arteko mendekotasunetarako.
• Erabili Middleware testuingurua zerbitzariaren konfiantzazko balioetarako, hala nola autentifikatutako erabiltzailearen IDa.
• Ez sartu negozio-logikarik DTOetan.
• Egiaztatu isValid() balioztatutako sarrera erabili aurretik.