A Drupal entitásrendszerének megértése fejlesztői szemmel

A Drupal egy rendkívül rugalmas és robusztus tartalomkezelő rendszer (CMS), amelynek alapját egy kifinomult és erőteljes adatmodell, az entitásrendszer képezi. Fejlesztői szemmel nézve az entitásrendszer megértése kulcsfontosságú ahhoz, hogy hatékonyan és skálázhatóan fejleszthessünk Drupalon belül. Ez a cikk célja, hogy alaposan körüljárja az entitásokat, azok típusait, működését és a velük való programozott interakciót, segítve ezzel a fejlesztőket abban, hogy a maximumot hozzák ki ebből a központi komponensből.

Mi is az az Entitás?

A legegyszerűbben megfogalmazva, a Drupalban egy entitás egy strukturált adatdarab objektum-orientált reprezentációja. Gondoljunk rá úgy, mint egy generikus objektumra, ami tárolható, lekérdezhető, verziózható és fordítható. Nem csupán egy adatbázis-sorról van szó, hanem egy olyan objektumról, amely rendelkezik egyedi azonosítóval (ID), és számos adattípust (mezőket) tartalmazhat. Az entitások a Drupalban mindenhol jelen vannak, a felhasználóktól (User), a cikkeken (Node), a taxonómiai kifejezéseken (Taxonomy Term) és a blokkokon (Block Content) át, egészen a konfigurációs beállításokig (Config Entity). Ez az egységes megközelítés lehetővé teszi a Drupal számára, hogy konzisztensen kezelje a legkülönfélébb adatokat.

Entitás Típusok és Kötegek: A Rendszer Alapja

Az entitásrendszer rugalmasságának alapját az entitás típusok és az entitás kötegek (bundles) közötti különbségtétel adja.

Entitás Típusok (Entity Types)

Az entitás típus definiálja egy adott entitás alapvető tulajdonságait és viselkedését. Ez egy magasabb szintű absztrakció, amely leírja, hogy egy bizonyos típusú adat hogyan működik a Drupalban. Például a node (tartalom) egy entitás típus, a user (felhasználó) egy másik, vagy a taxonomy_term (taxonómiai kifejezés) egy harmadik. Minden entitás típusnak van egy egyedi azonosítója (pl. node), és meghatározza azokat az alap mezőket (pl. ID, UUID, nyelv, státusz), amelyek minden ilyen típusú entitásra érvényesek. Két fő kategóriája van:

Tartalom Entitások (Content Entities): Ezek azok az entitások, amelyek felhasználói adatok tárolására szolgálnak, jellemzően revíziózhatók és fordíthatók. Például: Node (cikkek, oldalak), User (felhasználók), Comment (hozzászólások), Media (képek, videók), Block Content (egyedi blokkok).
Konfigurációs Entitások (Config Entities): Ezek a Drupal konfigurációját tárolják, mint például a nézetek (View), a tartalomtípusok (NodeType), vagy a képstílusok (ImageStyle). Nincsenek revíziózva és jellemzően csak egyszer fordíthatók (például egy tartalomtípus neve).

Entitás Kötegek (Bundles)

Az entitás köteg egy entitás típus további, specifikusabb „altípusa”. A kötegek teszik lehetővé, hogy az azonos entitás típusba tartozó entitások eltérő mezőkészletekkel és megjelenítési beállításokkal rendelkezzenek. Például a node entitás típusnak lehetnek olyan kötegei, mint az „Article” (cikk) és a „Basic page” (alapoldal). Mindkettő egy node, de egy „Article” tartalomtípus rendelkezhet „Kép” mezővel és „Címkék” taxonómiai hivatkozással, míg egy „Basic page” nem feltétlenül. A user entitás típusnak általában csak egy kötege van (a „User”), de a taxonomy_term entitás típusnak lehetnek kötegei, mint a „Tags” (címkék) vagy „Categories” (kategóriák). A kötegek a rugalmasság és az adatstruktúra pontos testreszabhatóságának kulcsai.

A Mezők és a Field API: Adataink Szerkezete

Az entitások adatait mezők tárolják, amelyeket a Drupal Field API-ja kezel. A Field API absztrahálja az adatok tárolását, kezelését és megjelenítését, lehetővé téve a fejlesztők számára, hogy anélkül definiáljanak és használjanak összetett adatstruktúrákat, hogy közvetlenül az adatbázissal kellene foglalkozniuk.

Alap Mezők (Base Fields)

Az alap mezők az entitás típus szintjén vannak definiálva, és minden az adott típushoz tartozó entitásra vonatkoznak, függetlenül attól, hogy melyik köteghez tartoznak. Például minden node entitásnak van egy title (cím), uid (szerző), status (státusz) és created (létrehozási idő) mezője. Ezek a mezők az entitás definíciójának részét képezik, és jellemzően programozottan, a modul BaseFieldDefinition osztályával definiálódnak.

Konfigurálható Mezők (Configurable Fields)

A konfigurálható mezők azok, amelyeket a felhasználói felületen (adminisztrációs felületen) adhatunk hozzá egy entitás köteghez. Ezek adják meg a Drupal tartalomtípusok és más entitáskötegek valódi rugalmasságát. A Field API számos beépített mezőtípust kínál (szöveg, szám, kép, fájl, entitáshivatkozás stb.), és lehetőséget biztosít egyéni mezőtípusok létrehozására is. Minden konfigurálható mezőnek van egy:

Mező típusa (Field Type): Meghatározza az adat típusát (pl. szöveg, egész szám, kép).
Mező widgetje (Field Widget): Meghatározza, hogyan jelenik meg a mező az űrlapokon a tartalom szerkesztésekor (pl. egy egyszerű szövegbeviteli mező, egy WYSIWYG szerkesztő vagy egy feltöltési gomb).
Mező formázója (Field Formatter): Meghatározza, hogyan jelenik meg a mező az entitás megjelenítésekor (pl. sima szövegként, linkként, egy kép formázott verziójaként).

A mezők és a Field API alapos ismerete elengedhetetlen a robusztus és felhasználóbarát adatbeviteli formák és adatmegjelenítések létrehozásához.

Tárolás és Adatbázis Absztrakció

A Drupal entitásrendszere az adatbázis-tárolást is absztrahálja. Bár a háttérben relációs adatbázisokat használ (MySQL, PostgreSQL stb.), a fejlesztőnek ritkán kell közvetlenül SQL-lekérdezésekkel foglalkoznia. Minden entitás típusnak van egy hozzárendelt tárolási logikája, amelyet az EntityStorageInterface interfész implementációja kezel. A Drupal alapértelmezésben a következő tárolási mechanizmusokat használja tartalom entitások esetén:

Alap táblák: Minden entitás típusnak van egy alap táblája (pl. node, users_field_data), amely az alapvető entitásadatokat és néhány alap mezőt tárolja.
Adat táblák: A Field API által létrehozott konfigurálható mezők külön táblákban tárolódnak (pl. node__field_image), amelyek az entitás ID-jére hivatkoznak. Ez lehetővé teszi a rugalmas mezőhozzáadást anélkül, hogy az alap entitás tábláját módosítani kellene.
Revíziós táblák: Ha egy entitás revíziózható, akkor az alap tábla revíziói egy külön táblában (pl. node_revision) tárolódnak, a mezők revíziói pedig a saját mező revíziós táblájukban (pl. node_revision__field_image).

Ez a moduláris felépítés rendkívül hatékony, és lehetővé teszi az adatok konzisztens kezelését, függetlenül attól, hogy hol és hogyan tárolódnak.

Revíziók és Fordítások: A Modern CMS Képességei

Az entitásrendszer a Drupal azon fejlett képességeinek alapja is, mint a tartalom verziózása és a többnyelvűség.

Revíziók (Revisions)

A revíziók lehetővé teszik a tartalom változásainak nyomon követését és a korábbi verziók visszaállítását. Ez kritikus funkció a tartalomkezelésben, mivel biztosítja a szerkesztési előzményeket és a hibák kijavításának lehetőségét. A legtöbb tartalom entitás (pl. node, media) alapértelmezetten támogatja a revíziókat. Amikor egy entitást frissítünk, a Drupal nem írja felül a meglévő adatokat, hanem létrehoz egy új revíziót, ami tartalmazza a változásokat, miközben az előző állapotok megmaradnak.

Fordítások (Translations)

A Drupal robusztus többnyelvű támogatása szintén az entitásrendszerre épül. Az entitások és a hozzájuk rendelt mezők fordíthatók. A Fordítás API biztosítja a mechanizmust a különböző nyelvi verziók kezelésére. Az entitásoknak lehet egy alapnyelvük, és a fordítások egyszerűen hozzáadhatók az egyes mezőkhöz. Ez lehetővé teszi a tartalom nemzetközivé tételét anélkül, hogy különálló entitásokat kellene létrehozni minden nyelven.

Programozott Interakció az Entitásokkal

Fejlesztőként az entitásokkal való programozott interakció kulcsfontosságú. A Drupal Core számos API-t biztosít ehhez.

Entitások Betöltése, Létrehozása, Frissítése és Törlése

Az EntityTypeManager szolgáltatás a központi belépési pont az entitáskezeléshez:

$entity_type_manager = Drupal::entityTypeManager();

// Entitás betöltése ID alapján:
$node = $entity_type_manager->getStorage('node')->load(1);
if ($node) {
    Drupal::logger('my_module')->info('Betöltött tartalom címe: @title', ['@title' => $node->label()]);
}

// Entitás létrehozása:
$new_node = $entity_type_manager->getStorage('node')->create([
    'type' => 'article',
    'title' => 'Új cikk a Drupalról',
    'uid' => Drupal::currentUser()->id(),
    'status' => 1,
]);
$new_node->save();

// Entitás frissítése:
if ($node) {
    $node->setTitle('Frissített cikk címe');
    $node->save();
}

// Entitás törlése:
// $node->delete();

Entitás Lekérdezések (Entity Queries)

Az EntityQuery szolgáltatás lehetővé teszi az entitások szűrését és lekérdezését kritériumok alapján. Ez a preferált módja az entitások keresésének, szemben a közvetlen adatbázis-lekérdezésekkel:

$query = Drupal::entityQuery('node')
    ->condition('type', 'article')
    ->condition('status', 1)
    ->range(0, 10)
    ->sort('created', 'DESC');
$nids = $query->execute();

$articles = $entity_type_manager->getStorage('node')->loadMultiple($nids);
foreach ($articles as $article) {
    Drupal::logger('my_module')->info('Cikk címe: @title', ['@title' => $article->label()]);
}

Mezők Kezelése

Az entitások mezői is objektumok, amelyek a get() és set() metódusokkal érhetők el:

if ($node) {
    // Mező értékének lekérése:
    $title_value = $node->get('title')->value;
    $body_value = $node->get('body')->value; // A body mező jellemzően egy tömböt ad vissza

    // Mező értékének beállítása:
    $node->set('title', 'Még frissebb cikk címe');
    $node->set('body', [
        'value' => '<p>Ez az új törzs szövege.</p>',
        'format' => 'full_html',
    ]);

    // Többértékű mezők (pl. kép) hozzáadása:
    // $node->get('field_image')->appendItem(['target_id' => $file_id, 'alt' => 'Kép leírása']);

    $node->save();
}

Egyéni Entitások Készítése: Saját Adatmodell

A Drupal entitásrendszere nem csak a beépített entitások használatát teszi lehetővé, hanem egyéni entitások létrehozását is. Ez a képesség teszi a Drupalt rendkívül hatékony keretrendszerré egyedi üzleti logikák és adatmodellek megvalósításához.

Tartalom Entitások (Content Entities)

Egy egyéni tartalom entitás létrehozásához a következő lépésekre van szükség:

Definíció Annotation: Egy PHP osztály, amely kiterjeszti a ContentEntityBase osztályt (vagy egy gyermekét), és tartalmaz egy @ContentEntityType annotációt. Ez az annotáció határozza meg az entitás ID-ját, címkéjét, tároló osztályát, útvonalait és más alapvető tulajdonságait.
Base Field Definitions: Az entitás osztályon belül a baseFieldDefinitions() metódusban kell definiálni az entitás alap mezőit (pl. ID, UUID, cím, dátum). Ezeket a mezőket a BaseFieldDefinition osztály segítségével hozhatjuk létre.
Schema Definition: Bár a Field API kezeli a konfigurálható mezőket, az alap mezőkhöz szükség lehet egy adatbázis séma definícióra, ha nem a Drupal alapértelmezett tárolási mechanizmusát használjuk. Azonban a ContentEntityBase alapértelmezett beállításai gyakran elegendőek.
Hozzáférési vezérlés: Implementálni kell az entitáshoz való hozzáférés logikáját (pl. ki láthatja, ki szerkesztheti).

Példa annotáció részletre:

/**
 * @ContentEntityType(
 *   id = "my_custom_entity",
 *   label = @Translation("Saját Egyéni Entitás"),
 *   handlers = {
 *     "view_builder" = "DrupalCoreEntityEntityViewBuilder",
 *     "list_builder" = "Drupalmy_moduleMyCustomEntityListBuilder",
 *     "form" = {
 *       "add" = "Drupalmy_moduleFormMyCustomEntityForm",
 *       "edit" = "Drupalmy_moduleFormMyCustomEntityForm",
 *       "delete" = "DrupalCoreEntityContentEntityDeleteForm",
 *     },
 *     "route_provider" = {
 *       "html" = "DrupalCoreEntityRoutingDefaultHtmlRouteProvider",
 *     },
 *   },
 *   base_table = "my_custom_entity",
 *   revision_table = "my_custom_entity_revision",
 *   admin_permission = "administer my custom entity",
 *   entity_keys = {
 *     "id" = "id",
 *     "revision" = "vid",
 *     "bundle" = "bundle",
 *     "label" = "name",
 *     "uuid" = "uuid",
 *     "langcode" = "langcode",
 *   },
 *   links = {
 *     "canonical" = "/my-custom-entity/{my_custom_entity}",
 *     "add-form" = "/admin/content/my-custom-entity/add",
 *     "edit-form" = "/admin/content/my-custom-entity/{my_custom_entity}/edit",
 *     "delete-form" = "/admin/content/my-custom-entity/{my_custom_entity}/delete",
 *     "collection" = "/admin/content/my-custom-entity",
 *   },
 *   bundle_entity_type = "my_custom_entity_type", // Ha kötegeket is szeretnénk
 *   field_ui_base_route = "entity.my_custom_entity_type.edit_form",
 * )
 */
class MyCustomEntity extends ContentEntityBase implements MyCustomEntityInterface {
  // ... baseFieldDefinitions() és egyéb metódusok
}

Konfigurációs Entitások (Config Entities)

A konfigurációs entitások létrehozása hasonló, de a ConfigEntityBase osztályt terjeszti ki, és jellemzően nem rendelkezik revíziókkal vagy mező API támogatással. Ezeket a beállításokat általában egyedi YAML fájlokban tárolják a modul konfigurációs mappájában. Az annotáció ebben az esetben @ConfigEntityType.

Például egy egyéni blokk típus definiálása:

/**
 * @ConfigEntityType(
 *   id = "my_custom_block_type",
 *   label = @Translation("Saját egyéni blokk típus"),
 *   handlers = {
 *     "list_builder" = "Drupalmy_moduleMyCustomBlockTypeListBuilder",
 *     "form" = {
 *       "add" = "Drupalmy_moduleFormMyCustomBlockTypeForm",
 *       "edit" = "Drupalmy_moduleFormMyCustomBlockTypeForm",
 *       "delete" = "DrupalCoreEntityEntityDeleteForm"
 *     },
 *     "route_provider" = {
 *       "html" = "DrupalCoreEntityRoutingDefaultHtmlRouteProvider",
 *     },
 *   },
 *   admin_permission = "administer my custom block types",
 *   config_prefix = "my_custom_block_type",
 *   entity_keys = {
 *     "id" = "id",
 *     "label" = "label"
 *   },
 *   links = {
 *     "add-form" = "/admin/structure/my-custom-block-type/add",
 *     "edit-form" = "/admin/structure/my-custom-block-type/{my_custom_block_type}",
 *     "delete-form" = "/admin/structure/my-custom-block-type/{my_custom_block_type}/delete",
 *     "collection" = "/admin/structure/my-custom-block-type"
 *   },
 *   config_export = {
 *     "id",
 *     "label",
 *     "description",
 *   }
 * )
 */
class MyCustomBlockType extends ConfigEntityBase implements MyCustomBlockTypeInterface {
  // ...
}

Az egyéni entitások rendkívül hatékonyak, de jelentős fejlesztői tudást igényelnek, mivel magában foglalják a teljes életciklus kezelését, az adatbázis-sémáktól a felhasználói felületen való megjelenítésig.

Hook-ok és Események: Az Entitás Életciklusának Testreszabása

A Drupal lehetővé teszi az entitás életciklusába való beavatkozást hook-ok és események segítségével.

Hook-ok

A hook-ok a Drupal modulrendszerének hagyományos módja a viselkedés testreszabására. Számos entitással kapcsolatos hook létezik, amelyek a CRUD (Create, Read, Update, Delete) műveletek során aktiválódnak. Néhány fontosabb:

hook_entity_load(array $entities, $entity_type_id): Entitások betöltése után.
hook_entity_presave(DrupalCoreEntityEntityInterface $entity): Entitás mentése előtt.
hook_entity_insert(DrupalCoreEntityEntityInterface $entity): Entitás létrehozása után.
hook_entity_update(DrupalCoreEntityEntityInterface $entity): Entitás frissítése után.
hook_entity_delete(DrupalCoreEntityEntityInterface $entity): Entitás törlése után.

Ezekkel a hook-okkal további logikát (pl. naplózás, adatok ellenőrzése, más rendszerek értesítése) fűzhetünk az entitások kezeléséhez.

Események (Events)

A Drupal 8+ óta az Symfony Event Dispatcher komponense is használatos, ami egy modernebb és rugalmasabb módot kínál a kód beillesztésére az entitás életciklusába. Az eseményeket általában szolgáltatás (Service) osztályokon belül kezelik, amelyek implementálják az EventSubscriberInterface-t. Az entitásokkal kapcsolatos események specifikusabbak lehetnek, mint a hook-ok, és pontosabb kontrollt biztosítanak.

use DrupalCoreEntityEntityTypeEvents;
use DrupalCoreEntityEntityEvent;
use SymfonyComponentEventDispatcherEventSubscriberInterface;

class MyModuleEntitySubscriber implements EventSubscriberInterface {

  /**
   * {@inheritdoc}
   */
  public static function getSubscribedEvents() {
    $events[EntityTypeEvents::INSERT][] = ['onEntityInsert'];
    $events[EntityTypeEvents::UPDATE][] = ['onEntityUpdate'];
    return $events;
  }

  /**
   * React to entity insertion.
   *
   * @param DrupalCoreEntityEntityEvent $event
   *   The event to process.
   */
  public function onEntityInsert(EntityEvent $event) {
    $entity = $event->getEntity();
    Drupal::logger('my_module')->notice('Új entitás "@type" (@id) létrehozva.', [
      '@type' => $entity->getEntityTypeId(),
      '@id' => $entity->id(),
    ]);
  }

  // ... onEntityUpdate() és más metódusok
}

Legjobb Gyakorlatok és Tippek Fejlesztőknek

Használj entitásokat: Ha strukturált adatot kell tárolni és kezelni, szinte mindig az entitásrendszer a helyes választás. Kerüld a közvetlen adatbázis-tábla létrehozását, ha a Field API vagy egy egyéni entitás megoldaná a problémát.
Ismerd a Field API-t: Mielőtt egyéni mezőket vagy tárolási megoldásokat kezdenél fejleszteni, győződj meg róla, hogy a beépített Field API nem kínálja-e már a szükséges funkcionalitást.
Használj EntityQuery-t: Kerüld a közvetlen SQL-lekérdezéseket az entitásadatokhoz. Az EntityQuery absztrakciót és biztonságot nyújt, és figyelembe veszi az entitás hozzáférési szabályait.
Access control: Mindig implementálj megfelelő hozzáférési vezérlést az egyéni entitásaidhoz. A hook_entity_access() vagy az EntityAccessControlHandler segít ebben.
Cache: Értsd meg, hogyan működik a Drupal gyorsítótárazása az entitásokkal. A helytelen gyorsítótárazás súlyos teljesítménybeli problémákat okozhat.
Kódolási standardok: Tartsd be a Drupal kódolási standardjait az olvasható és karbantartható kód érdekében.
Dokumentáció: Alaposan dokumentáld az egyéni entitásaidat, azok mezőit és a velük való interakciót.

Összegzés

A Drupal entitásrendszere a platform egyik legfontosabb és legmeghatározóbb komponense. Az entitás típusok, kötegek és a Field API mélyreható megértése képessé teszi a fejlesztőket arra, hogy robusztus, rugalmas és skálázható alkalmazásokat építsenek. Akár beépített entitásokkal dolgozunk, akár teljesen egyéni adatmodelleket hozunk létre, az entitásrendszer nyújtotta egységes keretrendszer garantálja a konzisztenciát és a hatékonyságot. A rendszer elsajátítása nem csak a Drupal fejlesztők számára alapvető, de egyben rálátást enged a modern tartalomkezelő rendszerek adatmodelljének komplexitására és eleganciájára is.