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

التوجيه

واجهة موجّه TubePress: كيف يتم تسجيل مسارات الواجهة الأمامية والإدارة وواجهة برمجة التطبيقات ومطابقتها وإرسالها، بما في ذلك معاملات المسار وطرق HTTP.

يستخدم TubePress موجّهاً صغيراً وسريعاً مبنياً حول الفئة الساكنة Router. تسجّل وحدات التحكم مساراتها في طريقة ::routes()، وتستدعي public/index.php تلك الطرق قبل توزيع الطلب. تغطّي هذه الصفحة كل ما تحتاجه لإضافة مسارات من إضافة أو فهم كيفية مطابقة الطلبات.

تسجيل المسارات

سجّل مساراً باستخدام Router::get() أو Router::post(). يمكن أن يكون المُعالج أي دالة قابلة للاستدعاء — إغلاق أو زوج [Class, 'method'].

// Closure handler
Router::get('/promo', function () {
    ThemeRenderer::render('promo', ['deal' => 'Summer']);
});

// Controller handler
Router::post('/promo/claim', [PromoController::class, 'claim']);

بالاتفاقية، تعرض كل وحدة تحكم طريقةً ساكنة routes() تُسجّل جميع مساراتها، وتُستدعى هذه الطريقة مرةً واحدة عند التشغيل:

class PromoController
{
    public static function routes(): void
    {
        Router::get('/promo', [self::class, 'show']);
        Router::post('/promo/claim', [self::class, 'claim']);
    }
}

معاملات المسار

استخدم العناصر النائبة {name} في المسار؛ يُطابق كل منها جزءاً واحداً من URL (كل شيء عدا /). اقرأ القيمة باستخدام Router::param().

Router::get('/promo/{code}', function () {
    $code = Router::param('code');          // required
    $ref  = Router::param('ref', 'direct'); // with a default
    // …
});

داخلياً، يُجمَّع نمط مثل /promo/{code} إلى regex (?P<code>[^/]+)، لذا لا تمتدّ المعاملات عبر الشرطات المائلة. تُطابَق المسارات الدقيقة أولاً، ثم المسارات ذات المعاملات بترتيب التسجيل.

إرسال الاستجابة

الطريقة	الاستخدام
`ThemeRenderer::render($tpl, $data)`	عرض صفحة واجهة أمامية من خلال السمة النشطة.
`Router::render($tpl, $data)`	عرض قالب إداري (`templates/{$tpl}.php`).
`Router::json($data, $code = 200)`	إرسال استجابة JSON والخروج.
`Router::redirect($url)`	إعادة التوجيه (والخروج). تُضاف بادئة اللغة/النوع النشطة تلقائياً إلى URLs الواجهة الأمامية.

ترتيب المسارات والمسار الشامل

تُخدَم الصفحات الثابتة بواسطة مسار شامل /{slug}، لذا تُسجَّل وحدة التحكم بالصفحات أخيراً في public/index.php — بعد كل مسارات الواجهة الأمامية والإدارة والـ API. إذا سجّلت مسارات من إضافة أثناء التشغيل، فستُضاف قبل المسار الشامل وستُطابَق أولاً.

تجنّب التعارض مع صفحة slug. مسار الإضافة مثل /deals سيُخفي صفحةً ثابتة في /deals. استخدم مساحة أسماء لمسارات الإضافة (مثلاً /promo/deals) للتأمين.

حماية CSRF

يجب أن يكون كل POST يغيّر الحالة محمياً بـ CSRF. يوفّر الموجّه الأدوات المساعدة التالية:

// In your form template
<?= Router::csrfField() ?>          // hidden input

// In your POST handler
if (!Router::verifyCsrf()) {
    Router::json(['error' => 'Invalid token'], 403);
}

تقبل verifyCsrf() الرمز المميّز من حقل POST csrf_token أو ترويسة X-CSRF-Token، وتقارنه باستخدام hash_equals().

URLs المحلّية والمصنّفة

بالنسبة للمواقع متعددة اللغات، يتعامل الموجّه بشفافية مع بادئة اللغة (مثلاً /fr/…) ويترجم صياغات المسارات المعروفة، لذا يُحلَّل /categorie/brunette إلى مسار category. مسارات الإدارة والتثبيت معفاة — سجّل مساراً باستخدام Router::addNoPrefixPath() إذا أردت إخراج مسار مخصص من البادئة. راجع اللغات والترجمة للاطلاع على السلوك الكامل. تتيح لك الأدوات المساعدة Router::langPrefix() وRouter::typePrefix() وRouter::url() بناء روابط صحيحة في أي لغة.

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

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

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

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

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