Iragazkiak

Osumi Framework-eko iragazkiak osagai bat exekutatu aurretik exekutatzen diren klase txiki eta berrerabilgarriak dira. Ohikoena honetarako da:

• Autentifikazioa eta baimena
• API giltza / token baliozkotzea
• Eskaerak aurre-prozesatzea
• Baimen-egiaztapenak
• Testuinguru-datuak (erabiltzailea, maizterra, lokalea...) aurre-kargatzea

Iragazkiek bide jakin batzuetarako eskaera bakoitzaren aurretik exekutatu behar den logika zentralizatzea ahalbidetzen dute, osagaiak garbi eta fokatuta mantenduz.

1. Zer da iragazki bat?

Iragazki bat PHP klase bat da —normalean src/App/Filter/-n jartzen dena—, metodo estatiko bat inplementatzen duena:

public static function handle(array $params, array $headers): array

Gutxienez honako hauek dituen array asoziatibo bat itzuli behar du:

[
  'status' => 'ok' | 'error',
  // beste balio batzuk...
]

Iragazkiak Authorization goiburua egiaztatzen du, token bat balioztatzen du eta "ok" egoera edo "error" itzultzen du, gehi aukerako erabiltzaile ID bat.

2. Iragazkiaren adibidea

Hona hemen benetako LoginFilter:

class LoginFilter {
  public static function handle(array $params, array $headers): array {
    global $core;
    $ret = ['status' => 'error', 'id' => null];

    $tk = new OToken($core->config->getExtra('secret'));

    if ($tk->checkToken($headers['Authorization'])) {
      $ret['status'] = 'ok';
      $ret['id'] = intval($tk->getParam('id'));
    }

    return $ret;
  }
}

Adibide honek honako hau erakusten du:

• Goiburuak irakurtzea
• Token bat balioztatzea
• Geroago DTOek edo osagaiek erabiliko dituzten testuinguru-datuak (id) itzultzea

3. Nola exekutatzen diren iragazkiak (Framework Fluxua)

Iragazkiak OCore-k exekutatzen ditu eskaeraren bizi-zikloaren barruan, osagaia instantziatu aurretik.

Prozesua laburbildu daiteke:

1. Bideratze-sistemak bat datorren ibilbidea eta bere iragazkien zerrenda identifikatzen ditu.
2. OCore-k $url_result sortzen du eskaeratik.
3. Iragazki bakoitzerako (ordenan):
   • Iragazki klasea instantziatu
   • Bere handle($params, $headers) deitu
   • Itzulitako "status" balioztatu
   • Emaitza gorde "ok" bada
   • Gelditu eta errore bat itzuli "error" bada

Logika zehatza OCore-n:

foreach ($url_result['filters'] as $filter) {
  $filter_instance = new $filter();
  $value = $filter_instance->handle(
    $url_result['params'],
    $url_result['headers']
  );

  if ($value['status'] !== 'ok') {
    // Errore edo birbideratzea kudeatu
    ...
    break;
  }

  $filter_results[$class_name] = $value;
}

4. Zer gertatzen da iragazki batek huts egiten duenean?

Iragazkiren batek "status" !== "ok" itzultzen badu:

Eskaera berehala gelditzen da

OCore-k gainerako iragazkiak prozesatzeari uzten dio eta osagaia exekutatzea eragozten du.

"return" sartzen bada

Framework-ak zehaztutako URL-ra birbideratzen du.

Bestela, framework-ak 403 Forbidden itzultzen du

OCore-k HTTP 403 ezartzen du eta errore-orri bat bistaratzen du.

Horrek bermatzen du baimenik gabeko eskaerak ez direla inoiz zure negozio-logikara iritsiko.

5. Zure aplikazioaren barruan iragazki-emaitzetara sartzea

Iragazki guztiek arrakasta izan ondoren, OCore-k ORequest objektu bat sortzen du:

$req = new ORequest($url_result, $filter_results);

Horrek iragazki-emaitza guztiak eskuragarri jartzen ditu honen bidez:

$req->getFilter('Login');

Adibidez:

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

if ($login['status'] === 'ok') {
  $userId = $login['id'];
}

Iragazkien izenak normalizatzen dira klase-izenetik "Filter" atzizkia kenduz, OCore-k islapena erabiliz egiten duen bezala.

6. DTO bateko iragazkien datuak erabiltzea

DTO eremuek automatikoki mapa ditzakete iragazkien balioak honako hau erabiliz:

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

Horrek esan nahi du:

• Bezeroak ezin du balio hau faltsutu edo gainidatzi.
• DTO-k erabiltzaile-IDa modu seguruan injektatzen du.
• Osagaiak ez du eskuz sartu behar iragazkira.

Honek funtzionatzen du ODTOk iragazkiaren datuak $req->getFilter() bidez irakurtzen dituelako eremuak betetzean.

7. Iragazkiak Ibilbideetan Definitzea

Ibilbide fitxategi batean:

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

Amaierako puntu hau deitzen denean:

1. Bideratzaileak /profile detektatzen du.
2. Osagaia exekutatu aurretik, OCorek LoginFilter exekutatzen du.
3. Iragazkiak huts egiten badu → eskaera amaitzen da.
4. Gainditzen badu → osagaia normal exekutatzen da.

OCore-ren iragazkiaren prozesamenduak fluxu zehatz hau baieztatzen du.

8. Iragazkiaren Itzulera Formatua

Iragazki batek beti itzuli behar du array bat honela:

[
  'status' => 'ok' | 'error',
  'return' => '/login', // hautazko birbideraketa
  // balio pertsonalizatuak...
]

Adibidez:

[
  'status' => 'ok',
  'id'     => 123,
  'role'   => 'admin'
]

9. Praktika Onak

Iragazkiak egoerarik gabe mantendu

Ez lukete egoera aldakor globalaren menpe egon behar (konfigurazioa edo saioa irakurtzea izan ezik).

Beti itzuli "status" => "ok" edo "error"

OCore-k eremu honen menpe dago eskaera jarraitu ala ez erabakitzeko.

Erabili iragazkiak autentifikaziorako / baimenerako

DTOek ez lukete kredentzialik zuzenean erabiltzaileengandik jaso behar segurtasunez injektatu daitezkeenean.

Izendatu iragazkiak XxxFilter-rekin

Horrek ziurtatzen du OCore-ren klase-izenaren normalizazioa aurreikusteko moduan jokatzen dela.

Saihestu logika astuna

Mantendu iragazkiak txikiak; mugitu negozio-logika zerbitzuetara.

Erabili "return" erabiltzaileak birbideratzeko

Erabilgarria saioa hasteko babesleentzat edo onboarding fluxuentzat.

10. Noiz Erabili Behar Duzu Iragazki Bat?

Erabili iragazki bat honako kasuetan:

• Ibilbide batek autentifikazioa behar du.
• Ibilbide batek API gako edo token bat baliozkotzea behar du.
• Osagai bat exekutatu aurretik baimenik gabeko erabiltzaileak blokeatu edo birbideratu nahi dituzu.
• Erabiltzailearen, maizterraren edo saioaren informazioa aurrez kargatu nahi duzu.
• Ibilbide anitzek segurtasun-egiaztapen berdinak partekatzen dituzte.

Ez erabili iragazkiak honetarako:

• Modeloaren balidazioa
• Erantzunak formateatzea
• Datu-egitura konplexuak eraikitzea (hauek DTOetan edo zerbitzuetan egon beharko lirateke)

11. Eskaera-fluxu osoa, iragazkiak barne

Bezeroaren eskaera
      ↓
Bideratzea → ibilbidea aurkitu da
      ↓
Iragazkiak exekutatzen dira (ordenan)
      ↓
Iragazkiren batek huts egiten badu → 403 edo birbideratu
      ↓
ORequest sortzen da (iragazki-datuekin)
      ↓
Component::run($dtoOrRequest)
      ↓
Txantiloiaren errendatzea
      ↓
Erantzuna