Datu Transferentzia Objektuak (DTOak)

Osumi Framework-eko DTOak (Data Transfer Objects) HTTP eskaera batetik datozen sarrera datuak jasotzeko, normalizatzeko eta balioztatzeko erabiltzen diren klase sinpleak dira.

Osagaiek idatzitako eta balioztatutako eskaera balioak, goiburuak edo iragazki irteerak atzitzeko modu egituratu eta segurua eskaintzen dute.

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

1. DTO baten helburua

DTOak honetarako diseinatuta daude:

• Eskaera datuak bildu eta motaz aldatu (URL parametroak, JSON gorputza, formulario eremuak, kontsulta kateak, goiburuak, iragazkiak).
• Balidazio arauak aplikatu osagaien logika exekutatu aurretik.
• Parametroen kudeaketa koherentea izan dadin framework osoan.
• $req->getParam…()-rako eskuzko deiak saihestea osagaien barruan.
• Balio ez-seguruak edo ustekabekoak negozio logikara iristea saihestea.

Osagai batek definitzen duenean:

public function run(MovieDTO $dto): void

...framework-ak automatikoki:

1. MovieDTO instantziatzen du.
2. Eskaeraren datuak kargatzen ditu.
3. Bere atributuetan definitutako balidazio arauak aplikatzen ditu.
4. DTO osagaiaren run() metodoan txertatzen du.

2. Oinarrizko klasea: ODTO

ODTO klaseak islapena erabiltzen du DTOko propietate publiko guztiak ikuskatzeko, haien #[ODTOField] definizioak irakurtzeko eta datuak horren arabera kargatzeko.

2.1 Datuak kargatzeko prozesua

ODTOk balioak lehentasun-ordena honetan kargatzen ditu:

1. Iragazkiaren emaitza Eremu batek filter eta filterProperty definitzen baditu, balioa hemendik hartzen da:

   $req->getFilter($filterName)[$filterProperty]
   

2. Goiburuaren balioa Eremu batek header: 'X-Header' definitzen badu, balioa hemendik hartzen da:

   $req->getHeader('X-Header')
   

3. Eskaera-parametroak Balioa propietate motaren arabera aldatzen da:

• int → $req->getParamInt()
• float → $req->getParamFloat()
• bool → $req->getParamBool()
• string → $req->getParamString()
• array → $req->getParam()
• defektuz → null

2.2 Balidazioa

Balio guztiak kargatu ondoren, ODTOk automatikoki egiaztatzen du:

• required required = true bada eta balioa falta bada, balidazio-errore bat gehitzen da.

• requiredIf Beste eremu batek balio bat badu, eta eremu honek ez, balidazio-errore bat gehitzen da.

Erroreak barnean gordetzen dira eta honen bidez berreskura daitezke:

$dto->getValidationErrors();

DTO baliozkoa den egiaztatu dezakezu honekin:

$dto->isValid();

3. ODTOField atributua

ODTOField atributua DTO propietate bakoitza konfiguratzeko erabiltzen da:

#[ODTOField(
  required: false,
  requiredIf: null,
  filter: null,
  filterProperty: null,
  header: null
)]

Atributuen aukerak

Aukera hauek konbinazio indartsuak ahalbidetzen dituzte, hala nola erabiltzaile-IDak iragazkietatik lortzea, API tokenak goiburuetatik ateratzea edo DTO eremuen arteko baldintzapeko mendekotasunak betearaztea.

4. DTO adibidea

Zure proiektuko adibidea:

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

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

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

  #[ODTOField(required: true)]
  public ?int $coverStatus = null;

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

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

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

  #[ODTOField(required: true)]
  public ?array $companions = null;

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

DTO honek:

• Eskaera-parametroetatik idatzitako balioak kargatzen ditu (int, string, array).
• Beharrezko eremuak betearazten ditu.
• idUser kargatzen du Login iragazkitik bezeroaren eskaeraren ordez.

5. DTO bat osagai baten barruan 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->date = $dto->date;
    $movie->idUser = $dto->idUser;
    $movie->save();
  }
}

Oharrak:

• Osagaiak ez du eskaera-balioak eskuz irakurri beharrik.
• Osagaira pasatako balioak idatzita eta balioztatuta daude dagoeneko.
• Erroreen kudeaketa errazagoa bihurtzen da.

6. Praktika onak

• Erabili ?type = null DTO propietate guztietarako, hasieratu gabeko motatutako propietateen erroreak saihesteko.
• Hobetsi DTOak datu egituratuak jasotzen dituzunean (API amaiera-puntuak, inprimakiak, JSON).
• Erabili requiredIf eremuen arteko mendekotasun logikoak adierazteko.
• Erabili filter eremuak ID sentikorrak bezeroari agerian ez jartzeko.
• Mantendu DTOak sinpleak; ez lukete negozio-logikarik izan behar.
• Egiaztatu beti $dto->isValid() erabili aurretik.

7. Noiz erabili DTOak

DTOak aproposak dira honetarako:

• Sarrera konplexuak jasotzen dituzten API amaiera-puntuak.
• Eremu asko dituzten inprimakien bidalketak.
• Iragazkiek injektatutako autentifikazio-datuak behar dituzten amaiera-puntuak.
• Berrerabilgarriak diren datu-egitura hainbat osagaitan erabiliak.
• Errepikatutako eskaera-analisi logika ordezkatuz.