دليل تطوير الإضافات

ابدأ من القالب الجاهز

حمّل starter-plugin.zip - إضافة SICMS كاملة وتعمل فعلياً (وليست مجرد أمثلة كود): صفحة عامة، قسم في لوحة التحكم بقائمة إضافة/حذف، صلاحية مخصصة، جدول قاعدة بيانات خاص، إعدادات تُبنى تلقائياً، وودجت في لوحة التحكم الرئيسية. ارفعها من لوحة تحكم SICMS > الإضافات لتجربتها مباشرة، ثم انسخها كنقطة بداية لإضافتك.

بنية أي إضافة

مجلد يحوي plugin.json (البيانات الوصفية)، وملف دخول (plugin.php افتراضياً) يُعيد كائن كلاس يرث من Sicms\Plugin، ومجلدات src/ (الكلاسات، بنطاق Plugin\{PascalCaseSlug}\) وviews/ وassets/ وlang/ar.php+en.php.

plugin.json - الحقول المهمة

slug معرّف فريد (حروف/أرقام/شرطات) يُستخدم في اسم الجدول ومفاتيح الإعدادات ومسار الأصول. name/description ثنائية اللغة. version بصيغة Semver. requires_core وrequires_plugins. entry اسم ملف الدخول. settings مصفوفة حقول (type: bool/number/text/select...) تُبنى تلقائياً في شاشة إعدادات الإضافة بلوحة التحكم بلا أي كود عرض أو حفظ من جانبك - اقرأ القيمة بـ $this->setting('key').

دورة حياة الإضافة

install() مرة واحدة عند أول تثبيت (أنشئ جداولك بـ Schema::create()) - activate() عند كل تفعيل - register() على كل طلب طالما الإضافة مفعّلة (سجّل المسارات والقوائم والـhooks هنا فقط، بلا استعلامات ثقيلة) - deactivate() عند الإيقاف (لا تحذف بيانات) - uninstall($purge) عند الحذف النهائي (احذف الجداول فقط إن $purge === true).

الاصطلاحات الأساسية

• قاعدة البيانات: Db::all()/one()/val() بجملة SQL تضع فيها اسم الجدول بين {} (مثل {my_table}) لتُستبدل تلقائياً ببادئة قاعدة البيانات. للكتابة: Db::insert('table', [...]), Db::update('table', [...], 'id = ?', [$id]), Db::delete('table', 'id = ?', [$id]) (اسم الجدول هنا بلا {}).
• المسارات: Router::get/post($path, [Controller::class, 'method'], $opts) أو Router::group($prefix, $opts, function(){...}). الخيار admin => true يفرض تسجيل الدخول وصلاحية admin.access، وperm => 'x.y' صلاحيتك المخصصة.
• CSRF: يُتحقق منه تلقائياً بواسطة النواة لكل POST - لا تتحقق منه يدوياً في متحكمك. كل نموذج POST يحتاج csrf_field() (أو f_action() الذي يضيفه تلقائياً).
• القوالب: $this->view($tpl, $data) للواجهة العامة، $this->adminView($tpl, $data, $title, $activeKey) للوحة التحكم؛ من متحكم منفصل استخدم Plugins::instance('slug').
• الصلاحيات: $this->permissions([...]) تسجّل مفاتيح تظهر في شاشة الأدوار، وAuth::can('key') للتحقق.
• عناصر النماذج الجاهزة: f_input(), f_textarea(), f_select(), f_check(), f_submit(), f_action() (للحذف/التبديل، تضيف CSRF تلقائياً) - تعطيك شكل النواة نفسه بلا HTML يدوي.

راجع README.md داخل القالب للتفاصيل الكاملة مع أمثلة، وإضافات SICMS الرسمية المُدرجة في سوق الإضافات لأمثلة حقيقية أكبر.