معمارية XOOPS

يوفر هذا المستند نظرة شاملة على معمارية نظام XOOPS، مع شرح كيفية عمل المكونات المختلفة معاً لإنشاء نظام إدارة محتوى مرن وقابل للتوسع.

نظرة عامة

يتبع XOOPS معمارية معيارية تفصل الاهتمامات إلى طبقات متميزة. يتم بناء النظام حول عدة مبادئ أساسية:

المعيارية: يتم تنظيم الوظائف في وحدات مستقلة قابلة للتثبيت
قابلية التوسع: يمكن توسيع النظام بدون تعديل الكود الأساسي
التجريد: تم فصل قاعدة البيانات وطبقات التقديم عن منطق العمل
الأمان: آليات أمان مدمجة للحماية من الثغرات الشائعة

طبقات النظام

graph TB
    subgraph Presentation["🎨 طبقة العرض"]
        Themes["المواضيع"]
        Templates["قوالب Smarty"]
        Blocks["الكتل"]
    end

    subgraph Application["⚙️ طبقة التطبيق"]
        Modules["الوحدات"]
        Preloads["التحميل المسبق"]
        Controllers["متحكمات"]
        BlockHandlers["معالجات الكتل"]
    end

    subgraph Domain["📦 طبقة المجال"]
        XoopsObject["XoopsObject"]
        Handlers["معالجات الكائنات"]
        Criteria["نظام المعايير"]
    end

    subgraph Infrastructure["🔧 طبقة البنية الأساسية"]
        Database["XoopsDatabase"]
        Cache["نظام الذاكرة المؤقتة"]
        Session["مدير الجلسات"]
        Security["طبقة الأمان"]
    end

    Presentation --> Application
    Application --> Domain
    Domain --> Infrastructure

    style Presentation fill:#e8f5e9,stroke:#388e3c
    style Application fill:#e3f2fd,stroke:#1976d2
    style Domain fill:#fff3e0,stroke:#f57c00
    style Infrastructure fill:#fce4ec,stroke:#c2185b

1. طبقة العرض

تتعامل طبقة العرض مع عرض واجهة المستخدم باستخدام محرك قوالب Smarty.

المكونات الرئيسية:

المواضيع: تصميم الجمال والتخطيط
قوالب Smarty: عرض المحتوى الديناميكي
الكتل: أداة إعادة استخدام محتوى

2. طبقة التطبيق

تحتوي طبقة التطبيق على منطق الأعمال والمتحكمات ووظائف الوحدات.

المكونات الرئيسية:

الوحدات: حزم الوظائف المستقلة
المعالجات: فئات معالجة البيانات
التحميل المسبق: مستمعي الأحداث والخطاطيف

3. طبقة المجال

تحتوي طبقة المجال على كائنات الأعمال الأساسية والقواعد.

المكونات الرئيسية:

XoopsObject: فئة أساسية لجميع كائنات المجال
المعالجات: عمليات CRUD لكائنات المجال

4. طبقة البنية الأساسية

توفر طبقة البنية الأساسية خدمات أساسية مثل الوصول إلى قاعدة البيانات والتخزين المؤقت.

دورة حياة الطلب

يعتبر فهم دورة حياة الطلب حاسماً لتطوير XOOPS الفعال.

تدفق متحكم الصفحة في XOOPS 2.5.x

يستخدم XOOPS 2.5.x الحالي نمط متحكم الصفحة حيث يتعامل كل ملف PHP مع طلبه الخاص. يتم تهيئة المتغيرات العامة ($xoopsDB، $xoopsUser، $xoopsTpl، إلخ) أثناء التمهيد وتتوفر في جميع أنحاء التنفيذ.

sequenceDiagram
    participant Browser
    participant Entry as modules/mymod/index.php
    participant Main as mainfile.php
    participant Kernel as XOOPS Kernel
    participant DB as $xoopsDB
    participant User as $xoopsUser
    participant Handler as MyObjectHandler
    participant Tpl as $xoopsTpl (Smarty)
    participant Theme

    Browser->>Entry: GET /modules/mymod/index.php

    rect rgb(240, 248, 255)
        Note over Entry,User: مرحلة التمهيد (mainfile.php)
        Entry->>Main: include mainfile.php
        Main->>Kernel: تهيئة النواة
        Kernel->>DB: إنشاء XoopsDatabase (singleton)
        Kernel->>User: تحميل الجلسة → $xoopsUser
        Kernel->>Tpl: تهيئة Smarty → $xoopsTpl
        Main-->>Entry: المتغيرات العامة جاهزة
    end

    rect rgb(255, 250, 240)
        Note over Entry,Handler: تنفيذ متحكم الصفحة
        Entry->>Handler: xoops_getModuleHandler('myobject')
        Handler->>DB: الاستعلام عبر Criteria
        DB-->>Handler: مجموعة النتائج
        Handler-->>Entry: XoopsObject[]
    end

    rect rgb(240, 255, 240)
        Note over Entry,Theme: مرحلة العرض
        Entry->>Tpl: $xoopsTpl->assign('items', $objects)
        Entry->>Theme: include header.php
        Entry->>Tpl: $xoopsTpl->display('mymod_index.tpl')
        Entry->>Theme: include footer.php
        Theme-->>Browser: صفحة HTML كاملة
    end

المتغيرات العامة الرئيسية في 2.5.x

المتغير العام	النوع	المهيأة	الغرض
`$xoopsDB`	`XoopsDatabase`	التمهيد	اتصال قاعدة البيانات (singleton)
`$xoopsUser`	`XoopsUser\|null`	تحميل الجلسة	المستخدم الحالي المسجل دخول
`$xoopsTpl`	`XoopsTpl`	تهيئة النموذج	محرك قوالب Smarty
`$xoopsModule`	`XoopsModule`	تحميل الوحدة	سياق الوحدة الحالي
`$xoopsConfig`	`array`	تحميل التكوين	تكوين النظام

1. مرحلة التمهيد

// mainfile.php هو نقطة الدخول
include_once XOOPS_ROOT_PATH . '/mainfile.php';

// تهيئة النواة
$xoops = Xoops::getInstance();
$xoops->boot();

الخطوات:

تحميل التكوين (mainfile.php)
تهيئة محمل التحميل التلقائي
إعداد معالجة الأخطاء
إنشاء اتصال قاعدة البيانات
تحميل جلسة المستخدم
تهيئة محرك قوالب Smarty

2. مرحلة التوجيه

// توجيه الطلب إلى الوحدة المناسبة
$module = $GLOBALS['xoopsModule'];
$controller = $module->getController();
$controller->dispatch($request);

الخطوات:

تحليل عنوان URL للطلب
تحديد الوحدة الهدف
تحميل تكوين الوحدة
التحقق من الأذونات
التوجيه إلى المعالج المناسب

3. مرحلة التنفيذ

// تنفيذ المتحكم
$data = $handler->getObjects($criteria);
$xoopsTpl->assign('items', $data);

الخطوات:

تنفيذ منطق المتحكم
التفاعل مع طبقة البيانات
معالجة قواعد الأعمال
إعداد بيانات العرض

4. مرحلة العرض

// عرض النموذج
include XOOPS_ROOT_PATH . '/header.php';
$xoopsTpl->display('db:module_template.tpl');
include XOOPS_ROOT_PATH . '/footer.php';

الخطوات:

تطبيق تخطيط المظهر
عرض نموذج الوحدة
معالجة الكتل
استجابة الإخراج

المكونات الأساسية

XoopsObject

فئة أساسية لجميع كائنات البيانات في XOOPS.

<?php
class MyModuleItem 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('created', XOBJ_DTYPE_INT, time(), false);
    }
}

الطرق الرئيسية:

initVar() - تحديد خصائص الكائن
getVar() - استرجاع قيم الخصائص
setVar() - تعيين قيم الخصائص
assignVars() - التخصيص الجماعي من المصفوفة

XoopsPersistableObjectHandler

يتعامل مع عمليات CRUD لكائنات XoopsObject.

<?php
class MyModuleItemHandler extends XoopsPersistableObjectHandler
{
    public function __construct(\XoopsDatabase $db)
    {
        parent::__construct($db, 'mymodule_items', 'MyModuleItem', 'id', 'title');
    }

    public function getActiveItems($limit = 10)
    {
        $criteria = new CriteriaCompo();
        $criteria->add(new Criteria('status', 1));
        $criteria->setSort('created');
        $criteria->setOrder('DESC');
        $criteria->setLimit($limit);

        return $this->getObjects($criteria);
    }
}

الطرق الرئيسية:

create() - إنشاء نموذج كائن جديد
get() - استرجاع الكائن حسب المعرف
insert() - حفظ الكائن في قاعدة البيانات
delete() - إزالة الكائن من قاعدة البيانات
getObjects() - استرجاع كائنات متعددة
getCount() - عد الكائنات المطابقة

هيكل الوحدة

تتبع كل وحدة XOOPS هيكل دليل قياسي:

modules/mymodule/
├── class/                  # فئات PHP
│   ├── MyModuleItem.php
│   └── MyModuleItemHandler.php
├── include/                # ملفات التضمين
│   ├── common.php
│   └── functions.php
├── templates/              # قوالب Smarty
│   ├── mymodule_index.tpl
│   └── mymodule_item.tpl
├── admin/                  # منطقة الإدارة
│   ├── index.php
│   └── menu.php
├── language/               # الترجمات
│   └── english/
│       ├── main.php
│       └── modinfo.php
├── sql/                    # مخطط قاعدة البيانات
│   └── mysql.sql
├── xoops_version.php       # معلومات الوحدة
├── index.php               # دخول الوحدة
└── header.php              # رأس الوحدة

حاوية حقن الاعتماديات

يمكن لتطوير XOOPS الحديث الاستفادة من حقن الاعتماديات للحصول على قابلية اختبار أفضل.

تنفيذ حاوية أساسي

<?php
class XoopsDependencyContainer
{
    private array $services = [];

    public function register(string $name, callable $factory): void
    {
        $this->services[$name] = $factory;
    }

    public function resolve(string $name): mixed
    {
        if (!isset($this->services[$name])) {
            throw new \InvalidArgumentException("Service not found: $name");
        }

        $factory = $this->services[$name];

        if (is_callable($factory)) {
            return $factory($this);
        }

        return $factory;
    }

    public function has(string $name): bool
    {
        return isset($this->services[$name]);
    }
}

حاوية متوافقة مع PSR-11

<?php
namespace Xmf\Di;

use Psr\Container\ContainerInterface;

class BasicContainer implements ContainerInterface
{
    protected array $definitions = [];

    public function set(string $id, mixed $value): void
    {
        $this->definitions[$id] = $value;
    }

    public function get(string $id): mixed
    {
        if (!$this->has($id)) {
            throw new \InvalidArgumentException("Service not found: $id");
        }

        $entry = $this->definitions[$id];

        if (is_callable($entry)) {
            return $entry($this);
        }

        return $entry;
    }

    public function has(string $id): bool
    {
        return isset($this->definitions[$id]);
    }
}

مثال الاستخدام

<?php
// تسجيل الخدمة
$container = new XoopsDependencyContainer();

$container->register('database', function () {
    return XoopsDatabaseFactory::getDatabaseConnection();
});

$container->register('userHandler', function ($c) {
    return new XoopsUserHandler($c->resolve('database'));
});

// حل الخدمة
$userHandler = $container->resolve('userHandler');
$user = $userHandler->get($userId);

نقاط التوسع

يوفر XOOPS عدة آليات توسع:

1. التحميل المسبق

يسمح التحميل المسبق للوحدات بربط أحداث النواة.

<?php
class MymoduleCorePreload extends XoopsPreloadItem
{
    public static function eventCoreHeaderEnd($args)
    {
        // تنفيذ عند انتهاء معالجة الرأس
    }

    public static function eventCoreFooterStart($args)
    {
        // تنفيذ عند بدء معالجة التذييل
    }
}

2. الإضافات البرمجية

تمتد الإضافات البرمجية الوظائف المحددة داخل الوحدات.

<?php
class MymoduleNotifyPlugin
{
    public function onItemCreate($item)
    {
        // إرسال إشعار عند إنشاء عنصر
    }
}

3. المرشحات

تعدل المرشحات البيانات أثناء مرورها عبر النظام.

<?php
// مثال على مرشح المحتوى
$myts = MyTextSanitizer::getInstance();
$content = $myts->displayTarea($rawContent, 1, 1, 1);

أفضل الممارسات

تنظيم الكود

استخدم الأنماط البرمجية للكود الجديد:

namespace XoopsModules\MyModule;

class Item extends \XoopsObject
{
    // التنفيذ
}

اتبع التحميل التلقائي PSR-4:

{
    "autoload": {
        "psr-4": {
            "XoopsModules\\MyModule\\": "class/"
        }
    }
}

افصل الاهتمامات:
- منطق المجال في class/
- العرض في templates/
- المتحكمات في جذر الوحدة

الأداء

استخدم التخزين المؤقت للعمليات المكلفة
حمل الموارد بكسل عند الإمكان
قلل استعلامات قاعدة البيانات باستخدام دفعات معايير
حسّن النماذج بتجنب منطق معقد

الأمان

تحقق من جميع المدخلات باستخدام Xmf\Request
هروب الإخراج في النماذج
استخدم بيانات معدة مسبقاً لاستعلامات قاعدة البيانات
تحقق من الأذونات قبل العمليات الحساسة

الوثائق ذات الصلة

أنماط التصميم - أنماط التصميم المستخدمة في XOOPS
طبقة قاعدة البيانات - تفاصيل تجريد قاعدة البيانات
أساسيات Smarty - توثيق نظام النموذج
أفضل ممارسات الأمان - إرشادات الأمان

#xoops #معمارية #core #تصميم #نظام-التصميم