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

البنية المعمارية

البنية الأساسية، ودورة حياة الطلب، والأعراف الخالية من أطر العمل التي يتبعها TubePress.

TubePress برنامج بسيط بتصميم مقصود. لا يوجد إطار عمل، ولا حاوية حقن تبعيات، ولا خطوة بناء — فقط PHP حديث منظّم تنظيمًا جيدًا باستخدام الكلاسات الثابتة. تشرح هذه الصفحة كيفية تكامل الأجزاء معًا حتى تتمكن من توسيع CMS بثقة ومعرفة أين يقع كودك بالضبط.

فلسفة التصميم

ثلاثة مبادئ تشكّل قاعدة الكود بأكملها:

بدون إطار عمل. PHP خالص مع كلاسات ثابتة مخصصة. لا توجد تبعيات وقت تشغيل لـ Composer قابلة للكسر، ولا شيء تتعلمه خارج PHP ذاته.
نواة ثابتة، إضافات حرة. النواة قابلة للتحديث ويجب ألا تُعدَّل مباشرة. كل ما تخصصه يقع في themes أو plugins أو settings.
مصمّم للتوسع والعمل على الاستضافة الرخيصة. الأعمال الثقيلة تُقسَّم إلى أجزاء، والـ pseudo-cron المدمج يعني عدم الحاجة إلى crontab النظام.

هيكل المجلدات

يفصل المستودع النواة (الثابتة، القابلة للتحديث) عن الإضافات (المثبّتة والمزالة من قِبل المستخدمين).

CORE — never modified by themes/plugins, replaced by updates
  config/            App config, DB config, install marker
  src/Core/          App, Database, Router, Pagination, CronManager,
                     and the managers (Seo, Transcode, Update, …)
  src/Auth/          Auth, Gate (permissions)
  src/Models/        Video, Category, Tag, Performer, Channel,
                     Comment, Page, User, Setting, Favorite, History
  src/Admin/         Admin CRUD controllers
  src/Front/         Public-facing controllers
  src/Install/       InstallController, Migrator
  src/Helpers/       Format, FileUpload, Sanitizer, Slug, SEO,
                     Player, RateLimiter, ImpressionTracker
  src/Plugin/        HookSystem, PluginInterface, PluginManager
  src/Theme/         ThemeManager, ThemeRenderer
  sql/               Numbered migrations (001_…sql → 0xx_…sql)
  templates/admin/   Admin panel templates (layout + partials)
  templates/install/ Install wizard templates
  public/            Web root — index.php, uploads/, symlinks
  cron/              Optional CLI scripts for a system crontab

ADD-ONS — installable / removable by users
  themes/            Theme directories (active: "simply")
  plugins/           Plugin directories (agegate, backup, ctr)
  lang/              Translation files (en, fr, de, es, ar, …)

لا تعدّل النواة للتخصيص. أي شيء في src/ أو config/ أو sql/ أو templates/ قد يُستبدَل بـ التحديث. ضع تغييراتك في theme أو plugin حتى تظل محفوظة.

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

كل طلب يمر عبر public/index.php بالترتيب ذاته:

حارس إصدار PHP. يعمل config/php-guard.php أولًا — بوابة آمنة للتحليل تمنع التشغيل على إصدار PHP غير مدعوم قبل تحميل أي صياغة حديثة.
الإقلاع. يضبط config/app.php التحميل التلقائي والجلسة والخدمات الأساسية.
فحص التثبيت. إذا كانت App::isInstalled() تُرجع false (لا يوجد config/installed.php)، يُحوَّل الطلب إلى معالج التثبيت ولا يتحمّل شيء آخر.
تسجيل المسارات. تسجّل كلٌّ من وحدات التحكم Admin وAPI والواجهة الأمامية مساراتها عبر طريقة ::routes() الثابتة.
التوزيع. تطابق Router::dispatch() عنوان URL وتستدعي طريقة وحدة التحكم المناسبة.
العرض. تعرض إجراءات المشرف templates/admin/*؛ وتعرض إجراءات الواجهة الأمامية الـ theme النشط عبر ThemeRenderer::render().
العمل بعد العرض. تُفرَّغ مرات الظهور ويُطلق CronManager::run() أي مهام مستحقة.

تُسجَّل مسارات الصفحة الأمامية (/{slug} الشامل للصفحات الثابتة) أخيرًا، لذلك لا تحجب المسارات الحقيقية أبدًا.

اتفاقيات النواة

المفهوم	الاتفاقية
وحدات التحكم	`AdminXxxController::routes()` / `FrontXxxController::routes()` تسجّل المسارات؛ والطرق تعالج الطلبات.
النماذج	طرق ثابتة: `Video::find($id)`، `Video::all($filters)`، `Video::create($data)`.
قاعدة البيانات	`Database::fetchOne()`، `fetchAll()`، `insert()`، `update()`، `delete()`، `count()`، `transaction()`.
Router	`Router::get()`، `Router::post()`، `Router::param('name')`، `Router::redirect()`.
قوالب المشرف	`Router::render('admin/videos', […])` → `templates/admin/videos.php` (يحمّل `layout.php` + جزئي `_videos.php`).
قوالب الواجهة الأمامية	`ThemeRenderer::render('home', […])` → قالب الـ theme النشط + ملف `layout.php` الخاص به.
الترحيلات	`sql/NNN_name.sql`، تُنفَّذ تلقائيًا بواسطة `Migrator::run()` أثناء التثبيت والتحديث.
الخطافات	`HookSystem::doAction('event')` و`HookSystem::applyFilter('filter', $value)`.

دعم خادم الويب

يعمل TubePress على كلٍّ من Apache وNginx:

Apache — تتولى ملفات .htaccess إعادة كتابة URL وحماية المجلدات.
Nginx — توجيهات alias تخدم الملفات وقواعد deny all تحمي المسارات الحساسة.
الروابط الرمزية — تكشف public/themes → ../../themes وpublic/templates → ../../templates أصول الـ theme ولوحة المشرف بينما تبقي شيفرة PHP المصدرية خارج جذر الويب.

جذر الويب دائمًا هو public/. كل المحتوى الحساس — config/ وsrc/ وsql/ وstorage/ — يقع خارجه وهو محجوب إضافيًا على مستوى الخادم.

أين تُجري التخصيصات

تريد أن تفعل…	افعله في…
تغيير المظهر والتخطيط	theme (أو إعدادات المظهر لتغييرات بدون كود)
إضافة ميزة أو تكامل	plugin باستخدام الإجراءات والمرشّحات
تغيير السلوك بدون كود	الإعدادات
إضافة عمل مجدوَل	الـ CronManager، من داخل plugin

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

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

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

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

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