توثيق MOFTemplate

مرجع عملي للمحرك. إذا كانت هذه أول مرة تستخدمه، ابدأ بـ الدرس العملي ثم ارجع هنا عند الحاجة للتفاصيل.

البداية

MOFTemplate محرك قوالب PHP صغير بلا مكتبات تشغيل خارجية. المطلوب PHP 8.1 أو أحدث، مجلد قوالب قابل للقراءة، ومجلد كاش قابل للكتابة.

require __DIR__ . '/moftemplate-engine.php';

$tpl = new MOFTemplate(
    __DIR__ . '/templates',
    __DIR__ . '/cache'
);

echo $tpl->render('home.html', [
    'title' => 'Moffed',
]);

يفضل أن يكون مجلد الكاش خارج الـ public web root متى ما كانت بنية تطبيقك تسمح بذلك.

واجهة PHP

new MOFTemplate($templateDir, $cacheDir)

يحدد مجلد القوالب ومجلد الكاش. لا يتم الوصول إلى أي قالب خارج مجلد القوالب بعد التحقق بـ realpath().

assign()

$tpl->assign('title', 'Moffed');

$tpl->assign([
    'title' => 'Moffed',
    'year' => 2026,
]);

القيم تبقى محفوظة داخل instance حتى تغيّرها. بيانات render() تتغلب عليها في ذلك العرض فقط.

render()

$html = $tpl->render('home.html', [
    'title' => 'Home',
]);

renderString()

لقالب موجود كنص من مصدر موثوق، مثل قاعدة بيانات إدارية:

$html = $tpl->renderString(
    'Hello {name}',
    ['name' => 'Moffed'],
    'welcome-message'
);

show()

موجود فقط للتوافق الأساسي مع الاستخدام القديم. الكود الجديد يفضل render() وrenderString().

echo $tpl->show('home.html');
echo $tpl->show('Hello {name}', 'welcome');

clearCache()

$tpl->clearCache();

يمسح فقط الملفات التي تحمل نمط MOFTemplate داخل مجلد الكاش، ولا يحذف الملفات الأخرى.

المتغيرات

{title}
{user.name}

المتغيرات العادية تمر عبر htmlspecialchars(..., ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8') تلقائيًا.

{raw trusted_html}

raw يتجاوز الـ escaping. استخدمه فقط مع HTML موثوق أو منقّى مسبقًا.

المصفوفات والقيم المتداخلة تستخدم النقطة. Objects تدعم الخصائص public فقط؛ الخصائص private/protected لا تُقرأ ولا تُكشف.

الشروط

{if logged_in}
    أهلاً {user.name}
{else}
    سجل الدخول
{/if}

{if status == 'published'}
    منشور
{elseif status == 'draft'}
    مسودة
{else}
    غير معروف
{/if}

المعاملات: =, ==, eq, !=, <>, ne, neq, <, lt, <=, le, lte, >, gt, >=, ge, gte.

لا توجد تعبيرات مركبة أو عوامل منطقية/حسابية من 1.x مثل && و|| وnot وmod. حضّر القيمة النهائية في PHP. هذا مقصود لإبقاء القالب بسيطًا.

الحلقات

{loop=items}
    {position}. {name}
{/loop}

داخل الحلقة، البحث يبدأ من العنصر الحالي ثم يرجع إلى بيانات الجذر. {position} يبدأ من 1.

{loop=items}
    المفتاح: {%key%}
    القيمة: {%value%}
{/loop}

{%value%} مفيد للحلقات على قيم scalar. Arrays وObjects غير القابلة للتحويل إلى string لا يتم dump لها تلقائيًا.

Nested loops

{loop=groups}
    <h2>{name}</h2>

    {loop=items}
        <p>{position}. {name}</p>
    {/loop}
{/loop}

Limit

{loop=items limit=3}
    {name}
{/loop}

limit يحد عدد العناصر فقط. pagination مسؤولية التطبيق أو قاعدة البيانات.

Odd / Even

{loop=rows}
    {odd position}odd{/odd}
    {even position}even{/even}
{/loop}

تضمين القوالب

{include_tpl partials/header.html}

المسموح قوالب داخل مجلد القوالب فقط. المسارات المطلقة و.. مرفوضة. كما يكتشف المحرك التضمين الدائري مثل A → B → A ويوقفه باستثناء واضح.

وسوم مساعدة

no_tpl_compile

{no_tpl_compile}
{this_is_displayed_as_text}
{/no_tpl_compile}

لا تستخدمها لعرض PHP tags؛ PHP tags مرفوضة من المصدر كاملًا. لعرضها في توثيق HTML استخدم entities مثل <?php.

trim

{trim}
    A
    B
{/trim}

يزيل أسطر وفراغات المسافة المحيطة بينها داخل الكتلة. استخدمه لكتل صغيرة فقط.

الكاش

MOFTemplate لا يخزن HTML النهائي. يخزن PHP مترجمًا من القالب لتجنب إعادة التحليل. اسم ملف الكاش مرتبط بمسار القالب ومحتواه، لذلك أي تغيير في المحتوى يولد نسخة جديدة حتى لو ظل mtime والحجم كما هما.

لا يحذف المحرك نسخة compiled قديمة تلقائيًا أثناء الطلب، حتى لا يصطدم بطلب آخر ما زال يستخدمها. استخدم clearCache() وقت النشر أو الصيانة. الكتابة تتم إلى ملف مؤقت ثم rename لتقليل خطر الملفات الجزئية.

معالجة الأخطاء

كل أخطاء المحرك المتوقعة ترمي MOFTemplateException بدل die().

try {
    echo $tpl->render('home.html', $data);
} catch (MOFTemplateException $e) {
    // سجل الخطأ، واعرض صفحة مناسبة لتطبيقك.
}

الأمان

• HTML escaping افتراضي للمتغيرات في سياق HTML.
• لا يوجد تنفيذ PHP داخل القالب، وتُرفض PHP tags المباشرة.
• لا يوجد include_script أو SQL أو استدعاء دوال PHP حرة.
• لا يتم دمج $GLOBALS مع بيانات القالب.
• خصائص Objects غير العامة لا تُقرأ.
• التضمين محصور داخل مجلد القوالب مع منع path traversal.
• التضمين الدائري ومبالغة عمق التضمين مرفوضان.

الانتقال من 1.x إلى 2.0

للتفاصيل والأسباب راجع MIGRATION.md وBUG_REPORT.md داخل الحزمة.

الاختبارات

php tests/run.php

الحزمة تضم 43 اختبارًا بلا PHPUnit. تغطي escaping، الشروط، nested loops، odd/even، Objects، Traversable، includes، circular includes، cache invalidation، PHP rejection، traversal، وclearCache.

الأصل والحقوق

ترويسة المصدر الأصلي المرفق تعرّف المشروع باسم MOFTemplate Engine 1.4.0.2 والمؤلف Saanina، وآخر تعديل بتاريخ 28 أكتوبر 2008. رابط GitHub الذي زود به مالك المشروع هو github.com/abdumu.

MOFTemplate 2.0 تحديث وصيانة تحت Moffed Developers، مع الإبقاء الصريح على الإسناد للمؤلف الأصلي.