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

الخطّافات وتطوير الإضافات

وسّع TubePress باستخدام نظام خطّافات الإجراءات والمرشّحات على غرار ووردبريس: أكثر من 15 نقطة خطّاف، ودورة حياة الإضافة، وكيفية بناء وتغليف إضافتك الخاصة.

الإضافات هي الطريقة التي تضيف بها ميزات إلى TubePress دون المساس بالنواة. تتصل بنظام CMS من خلال نظام صغير على غرار WordPress يتضمن الأحداث (أحداث تُطلق وتُنسى) والفلاتر (تعديل قيمة وإعادتها). الإضافات الثلاث المدمجة — Age Gate وBackup Pro وCTR Ranking — مبنية بالكامل باستخدام نفس API الموثق هنا.

نظام الخطافات

تدير الفئة الثابتة HookSystem كلا النوعين من الخطافات. تعمل ردود النداء بترتيب تصاعدي للأولوية (الافتراضي 10)؛ يتم التقاط أي استثناء تُطلقه ردود النداء وتسجيله، لذا لا يمكن لإضافة معطوبة أن تُعطل الصفحة.

// Actions — do something when an event fires
HookSystem::addAction('head.meta', function () {
    echo '<meta name="rating" content="adult">';
}, 10);

// Filters — receive a value, return a (possibly) changed value
HookSystem::addFilter('theme.template_data', function ($data, $template) {
    if ($template === 'home') {
        $data['promo'] = Promo::current();
    }
    return $data;
});

الطريقة	الغرض
`addAction($hook, $cb, $priority = 10)`	تسجيل مستمع للحدث.
`doAction($hook, ...$args)`	إطلاق حدث (النواة تستدعي هذه).
`addFilter($hook, $cb, $priority = 10)`	تسجيل فلتر.
`applyFilter($hook, $value, ...$args)`	تمرير قيمة عبر فلاتره وإعادتها.
`hasAction()` / `hasFilter()`	التحقق مما إذا كان هناك مستمعون.
`removeAction()` / `removeFilter()`	فصل جميع المستمعين لخطاف.

نقاط الخطاف المتاحة

تُطلق النواة هذه الخطافات. يمكنك أيضاً تحديد خطافاتك الخاصة وإطلاقها من إضافة.

الأحداث

الخطاف	متى يُطلق
`head.meta`	داخل `<head>`، بعد CSS — أضف وسوم meta ووسوم التحقق وما إلى ذلك.
`footer.scripts`	قبل `</body>`، بعد JS — أضف أدوات التحليل أو الأدوات المصغرة.
`routes.registered`	بعد تسجيل جميع مسارات النواة، قبل المسار الشامل للصفحة.
`router.before_dispatch`	مباشرة قبل تشغيل معالج مطابق. الوسيط: المسار المحلول.

الفلاتر

الخطاف	يعدل (الوسائط)
`theme.template_data`	مصفوفة البيانات قبل عرض القالب. الوسائط: `($data, $templateName)`.
`head.css`	سلسلة إخراج CSS المدمجة.
`footer.scripts`	سلسلة إخراج JS المدمجة.
`video.card.html`	كامل HTML لبطاقة الفيديو. الوسائط: `($html, $video)`. أعد سلسلة غير فارغة لاستبدالها.

تشريح الإضافة

الإضافة هي مجلد تحت plugins/ يحتوي على ملف بيان وفئة تُنفذ PluginInterface.

plugins/myplugin/
├── plugin.json     Manifest (name, slug, version, …)
├── plugin.php      Main class implementing PluginInterface; must end with return new MyPlugin();
├── icon.svg        Optional icon shown in the admin
└── …               Your assets, templates, migrations

البيان يعكس الإضافات المدمجة:

{
  "name": "My Plugin",
  "slug": "myplugin",
  "description": "What it does, in one sentence.",
  "version": "1.0.0",
  "author": "You",
  "requires": "1.0.0",
  "icon": "icon.svg"
}

الفئة الرئيسية تُنفذ أساليب دورة الحياة الست لـ PluginInterface:

الطريقة	تُستدعى عند
`boot()`	كل طلب أثناء نشاط الإضافة — سجّل الخطافات والمسارات والأصول هنا.
`activate()`	تفعيل المشرف للإضافة. تُستدعى عند كل تفعيل — أنشئ هنا جداولك وإعداداتك الافتراضية بطريقة آمنة عند التكرار (`CREATE TABLE IF NOT EXISTS`).
`deactivate()`	تعطيل المشرف للإضافة.
`install()`	تفرضها الواجهة، لكن النواة لا تستدعيها أبداً — نفّذ التهيئة في `activate()`.
`uninstall()`	إزالة الإضافة — التنظيف.
`info()`	تُعيد بيانات البيان كمصفوفة.

تسجيل المسارات والأصول

قم بكل الربط في boot():

public function boot(): void
{
    // A front-end route
    Router::get('/promo/{code}', [PromoController::class, 'show']);

    // Inject a meta tag
    HookSystem::addAction('head.meta', [$this, 'meta']);

    // Tweak every video card
    HookSystem::addFilter('video.card.html', [$this, 'badge'], 20);
}

مكتفٍ بذاته بحسب التصميم. يجب أن تضيف الإضافة كل ما تحتاجه — مخططها الخاص وإعداداتها ومساراتها وصفحات الإدارة والمهام المجدولة — وتزيلها عند إلغاء التثبيت، دون تغييرات على نظام CMS الأساسي. إضافة CTR Ranking نموذج جيد على ذلك.

العمل المجدول في الإضافة

سجّل مهمة متكررة مع CronManager من boot() — تعمل على pseudo-cron المدمج، لذا لا يلزم وجود crontab للنظام. هكذا تعيد إضافة CTR حساب الدرجات ويُشغّل Backup Pro النسخ الاحتياطية المجدولة.

الإضافات المدمجة كمراجع

Age Gateتراكب، وسوم RTA الوصفية، استمرارية ملفات تعريف الارتباط. Backup Proالملفات الشخصية، التخزين عن بُعد، الجدولة. CTR Rankingالتتبع، إعادة حساب cron، ربط الترتيب.

التوزيع والترخيص

يمكنك الاحتفاظ بالإضافة خاصة أو مشاركتها بحرية؛ أما السوق فيوزّع إضافات TubePress الخاصة فقط. راجع تطوير القوالب للمكافئ في جانب العرض، ومرجع Theme API لكل ما هو متاح لكود القالب.

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

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

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