مرجع المطوّرين

النماذج وقاعدة البيانات

طبقة بيانات TubePress: فئات النماذج، ومساعد قاعدة بيانات PDO، والعبارات المحضّرة، ومخطط قاعدة البيانات، وعمليات ترحيل SQL المُصدّرة، موضّحة.

يتواصل TubePress مع MySQL/MariaDB عبر طبقتين رفيعتين: النماذج (فئة ثابتة واحدة لكل كيان) ومساعد Database (غلاف بسيط على PDO). لا يوجد ORM ولا منشئ استعلامات للتعلم — مجرد جمل معدّة وأسماء توابع قابلة للتوقع.

طبقة النموذج

لكل كيان أساسي نموذج في src/Models/ يكشف توابع ثابتة. النماذج المتاحة هي Video، وCategory، وTag، وPerformer، وChannel، وComment، وPage، وUser، وSetting، وFavorite، وHistory، وReport، وContactMessage، وMenuConfig، وFooterConfig.

$video  = Video::find($id);            // one row (or null)
$latest = Video::all(['status' => 'published', 'limit' => 20]);
$id     = Video::create($data);        // returns new id
Video::update($id, ['title' => 'New title']);
Video::delete($id);

تُغلّف النماذج عمليات الربط والتصفية الخاصة بكيانها — فعلى سبيل المثال، تُعيد Video::find() الفيديو مع فئاته ووسومه ومؤدّيه وقنواته المرفقة، مما يبقي المتحكمات والقوالب بسيطة.

مساعد Database

لكل ما لا يغطيه النموذج، استخدم مساعد Database مباشرةً. تستخدم كل طريقة جملاً معدّة — ولا تُدرج مدخلات المستخدم في SQL إطلاقاً.

الطريقة	يُعيد	الغرض
`Database::fetchOne($sql, $params)`	array\\|null	أول صف مطابق.
`Database::fetchAll($sql, $params)`	array	جميع الصفوف المطابقة.
`Database::insert($table, $data)`	int	إدراج مصفوفة ترابطية؛ يُعيد المعرّف الجديد.
`Database::update($table, $data, $where, $whereParams)`	int	تحديث؛ يُعيد الصفوف المتأثرة.
`Database::delete($table, $where, $params)`	int	حذف؛ يُعيد الصفوف المتأثرة.
`Database::count($table, $where, $params)`	int	عدد الصفوف.
`Database::query($sql, $params)`	PDOStatement	أي جملة، للتحكم الكامل.
`Database::transaction($callback)`	mixed	تشغيل دالة مجهولة في معاملة (إيداع/تراجع تلقائي).

$rows = Database::fetchAll(
    "SELECT * FROM videos WHERE status = ? ORDER BY id DESC LIMIT ?",
    ['published', 20]
);

$newId = Database::insert('categories', [
    'name' => 'Amateur',
    'slug' => 'amateur',
]);

اتصالات مرنة. يستخدم المساعد utf8mb4 وجملاً معدّة حقيقية (دون محاكاة) ووضع الأخطاء بالاستثناءات، ويُعيد الاتصال تلقائياً مرة واحدة عند حدوث خطأ "انقطاع الاتصال بالخادم" — لكي تستمر العمليات طويلة الأمد رغم انتهاء مهلة MySQL الخاملة.

المعاملات

ضع عمليات الكتابة المتعددة الخطوات في غلاف حتى تنجح جميعها أو تُتراجع جميعها:

Database::transaction(function () use ($videoId, $catIds) {
    Database::delete('video_categories', 'video_id = ?', [$videoId]);
    foreach ($catIds as $cid) {
        Database::insert('video_categories', [
            'video_id' => $videoId, 'category_id' => $cid,
        ]);
    }
});

المخطط

تستخدم قاعدة البيانات مخطط MySQL نظيفاً مُعيَّراً. تشمل الجداول الأساسية users، وsettings، وcategories، وtags، وperformers، وchannels، وvideos، وجداول الربط video_categories، وvideo_tags، وvideo_performers — فضلاً عن comments، وuser_favorites، وuser_history، وvideo_likes، وpages، وplugins، وthemes، وmigrations. تضيف الأنظمة الفرعية الاختيارية جداولها الخاصة (مهام الاستيراد، ووحدات تخزين الوسائط، ومهام/خوادم التحويل، ومناطق/بقع الإعلانات، والتقارير، ومصادر التغذية، وجداول الترجمة وغيرها) عند تفعيلها.

عمليات الترحيل

تُخزَّن تغييرات المخطط في sql/ كملفات مُرقَّمة — 001_users.sql، و002_settings.sql، و… — تُطبَّق بالترتيب بواسطة Migrator::run() أثناء التثبيت وبعد كل تحديث. كل عملية ترحيل تراكمية ومسجّلة في جدول migrations لذا لا تُنفَّذ مرتين أبداً.

لتوسيع المخطط من إضافة، أضف جمل CREATE TABLE الخاصة بك ونفّذها في طريقة install() للإضافة (راجع الخطافات والإضافات).
لا تُعيد ترقيم أو تعديل عملية ترحيل مطبّقة — أضف واحدة جديدة برقم أعلى.

كتابة نموذج

النموذج مجرد فئة ثابتة تُغلّف مساعد Database لجدول واحد:

class Promo
{
    public static function current(): ?array
    {
        return Database::fetchOne(
            "SELECT * FROM promos WHERE active = 1
             ORDER BY id DESC LIMIT 1"
        );
    }
}

الخطوات التالية

Cron & CLIتشغيل المهام الخلفية بأمان. الخطافات والإضافاتشحن نموذج مع إضافة. المعماريةأين تقع النماذج في الطبقات.

لا تزال عالقاً؟

افتح تذكرة من لوحة التحكم وسيساعدك فريقنا.

جرّب العرض التجريبي المباشر → تحميل TubePress →