ADR-002 - Abstraksi Pangkalan Data

ADR-002: Abstraksi Pangkalan Data> Rekod Keputusan Seni Bina untuk corak capaian pangkalan data berorientasikan objek XOOPS.---

StatusDiterima - Corak teras sejak XOOPS 2.0---

KonteksXOOPS memerlukan strategi interaksi pangkalan data yang akan:1. Abstrak sintaks SQL khusus pangkalan data

2. Menyediakan operasi CRUD yang konsisten merentas semua modul
3. Dayakan pembersihan data automatik dan melarikan diri
4. Menyokong perubahan enjin pangkalan data masa hadapan
5. Permudahkan operasi biasa untuk pembangunAlternatifnya ialah:

• SQL mentah di seluruh pangkalan kod
• ORM penuh (Doktrin, Fasih)
• Abstraksi ringan tersuai---

Gambarajah Keputusan

mermaid
graph TB
    subgraph "Application Layer"
        A[Module Code]
        B[Handler Methods]
    end

    subgraph "Abstraction Layer"
        C[XoopsObjectHandler]
        D[XoopsPersistableObjectHandler]
        E[Criteria System]
    end

    subgraph "Database Layer"
        F[XoopsDatabase]
        G[MySQLDatabase]
        H[PDO Wrapper]
    end

    subgraph "Storage"
        I[(MySQL/MariaDB)]
    end

    A --> B
    B --> C
    B --> D
    C --> E
    D --> E
    E --> F
    F --> G
    F --> H
    G --> I
    H --> I

---

KeputusanKami akan melaksanakan Corak Pengendali dengan:### 1. XoopsObject - Bekas DataSetiap entiti data memanjangkan XoopsObject:

php
class Item extends XoopsObject
{
    public function __construct()
    {
        $this->initVar('id', XOBJ_DTYPE_INT, null, false);
        $this->initVar('title', XOBJ_DTYPE_TXTBOX, '', true, 255);
        $this->initVar('content', XOBJ_DTYPE_TXTAREA, '', false);
        $this->initVar('status', XOBJ_DTYPE_INT, 0, false);
    }
}

2. Pengendali - Pengurus OperasiSetiap objek mempunyai pengendali yang sepadan:

php
class ItemHandler extends XoopsPersistableObjectHandler
{
    public function __construct($db)
    {
        parent::__construct($db, 'mymodule_items', Item::class, 'id', 'title');
    }

    // CRUD methods inherited:
    // - create(), get(), insert(), delete()
    // - getObjects(), getCount(), getAll()
}

3. Kriteria - Pembina PertanyaanSyarat pertanyaan berorientasikan objek:

php
$criteria = new CriteriaCompo();
$criteria->add(new Criteria('status', 1));
$criteria->add(new Criteria('created', time() - 86400, '>='));
$criteria->setSort('created');
$criteria->setOrder('DESC');
$criteria->setLimit(10);

$items = $handler->getObjects($criteria);

---

Pemalar Jenis Data

php
// Variable types with automatic sanitization
XOBJ_DTYPE_INT       // Integer
XOBJ_DTYPE_TXTBOX    // Single-line text (escaped)
XOBJ_DTYPE_TXTAREA   // Multi-line text (escaped)
XOBJ_DTYPE_EMAIL     // Email validation
XOBJ_DTYPE_URL       // URL validation
XOBJ_DTYPE_ARRAY     // Serialized array
XOBJ_DTYPE_OTHER     // No processing
XOBJ_DTYPE_FLOAT     // Floating point

---

Warisan Pengendali

mermaid
classDiagram
    class XoopsObjectHandler {
        <<abstract>>
        #db: XoopsDatabase
        +create(): XoopsObject
        +get(id): XoopsObject
        +insert(object): bool
        +delete(object): bool
    }

    class XoopsPersistableObjectHandler {
        +getObjects(criteria): array
        +getCount(criteria): int
        +getAll(criteria): array
        +deleteAll(criteria): bool
        +updateAll(field, value, criteria): bool
    }

    class ItemHandler {
        +getPublishedItems(): array
        +getByCategory(catId): array
    }

    XoopsObjectHandler <|-- XoopsPersistableObjectHandler
    XoopsPersistableObjectHandler <|-- ItemHandler

---

Akibat### Positif1. Ketekalan: Semua modul menggunakan corak yang sama

2. Keselamatan: Melarikan diri automatik menghalang suntikan SQL
3. Kesederhanaan: Operasi biasa memerlukan kod minimum
4. Kebolehselenggaraan: Perubahan pada lapisan pangkalan data tidak menjejaskan modul
5. Kebolehujian: Pengendali boleh diejek untuk ujian### Negatif1. Prestasi: Overhed abstraksi tambahan
6. Kerumitan: Keluk pembelajaran untuk pembangun baharu
7. Limitation: Pertanyaan kompleks mungkin memerlukan SQL mentah
8. N+1 Masalah: Tiada pemuatan eager terbina dalam### Tebatan- Prestasi: Cache objek yang kerap diakses

• Pertanyaan rumit: Benarkan SQL mentah apabila diperlukan
• N+1: Gunakan getAll() dengan kriteria yang betul---

Evolusi kepada XOOPS 4.0

mermaid
flowchart LR
    subgraph "Current (2.5.x)"
        A[XoopsDatabase]
        B[Handlers]
        C[Criteria]
    end

    subgraph "Future (4.0.x)"
        D[PDO/DBAL]
        E[Repository Pattern]
        F[Query Builder]
        G[DI Container]
    end

    A --> D
    B --> E
    C --> F
    D --> G
    E --> G

Pelan XOOPS 4.0:

• Doktrin DBAL untuk abstraksi pangkalan data
• Corak repositori menggantikan pengendali
• Pembina pertanyaan untuk pertanyaan kompleks
• Penyepaduan kontena PSR-11 penuh---

Contoh Kod### Asas CRUD

php
$helper = Helper::getInstance();
$handler = $helper->getHandler('Item');

// Create
$item = $handler->create();
$item->setVar('title', 'New Item');
$handler->insert($item);

// Read
$item = $handler->get($id);
$title = $item->getVar('title');

// Update
$item->setVar('title', 'Updated Title');
$handler->insert($item);

// Delete
$handler->delete($item);

Pertanyaan Kompleks

php
$criteria = new CriteriaCompo();
$criteria->add(new Criteria('status', 'published'));
$criteria->add(new Criteria('category_id', '(1,2,3)', 'IN'));
$criteria->add(new Criteria('created', strtotime('-30 days'), '>='));
$criteria->setSort('views');
$criteria->setOrder('DESC');
$criteria->setLimit(10);
$criteria->setStart(0);

$items = $handler->getObjects($criteria);
$total = $handler->getCount($criteria);

---

Keputusan Berkaitan- ADR-001: Seni Bina Modular

• ADR-003: Enjin Templat Smarty---

Rujukan- Martin Fowler - Corak Seni Bina Aplikasi Perusahaan

• Konsep Reka Bentuk Dipacu Domain
• Corak Rekod Aktif lwn Data Mapper---

#XOOPS #architecture #adr #database #handler #design-decision