ابدأ مع MOFTemplate

جهّز الملفات

حمّل الحزمة وضع ملف المحرك في مشروعك. أنشئ هذا الهيكل:

my-app/
├── index.php
├── moftemplate-engine.php
├── templates/
│   ├── home.html
│   └── partials/
│       └── header.html
└── cache/

يكفي أن يستطيع PHP قراءة templates والكتابة إلى cache. في الإنتاج يفضل وضع cache خارج public web root.

أنشئ index.php

<?php

declare(strict_types=1);

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

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

$data = [
    'title' => 'متجر مفيد',
    'logged_in' => true,
    'user' => ['name' => 'سالم'],
];

echo $tpl->render('home.html', $data);

الفكرة الأساسية: PHP يجهز البيانات، والقالب يعرضها. لا تنقل منطق التطبيق إلى القالب.

أنشئ templates/home.html

<!doctype html>
<html lang="ar" dir="rtl">
<head>
    <meta charset="utf-8">
    <title>{title}</title>
</head>
<body>
    <h1>{title}</h1>
</body>
</html>

{title} تُطبع مع HTML escaping تلقائي. لو كانت القيمة تحتوي <script> فلن تُنفذ كـ HTML.

أضف قائمة منتجات

في PHP أضف:

'products' => [
    ['name' => 'Keyboard', 'price' => 199],
    ['name' => 'Mouse', 'price' => 99],
    ['name' => 'Monitor', 'price' => 799],
],

وفي القالب:

<ul>
{loop=products}
    <li>{position}. {name} — {price} ر.س</li>
{/loop}
</ul>

داخل الحلقة، {name} و{price} يؤخذان من العنصر الحالي. {position} يبدأ من 1.

أضف شرطًا

{if logged_in}
    <p>مرحبًا {user.name}</p>
{else}
    <p>مرحبًا بالزائر</p>
{/if}

إذا احتجت شرطًا مركبًا، لا تكتبه داخل القالب. احسبه في PHP:

$data['can_checkout'] = $loggedIn && $cartHasItems;

{if can_checkout}
    <button>إتمام الطلب</button>
{/if}

قسم القالب إلى أجزاء

ضع في templates/partials/header.html:

<header>
    <strong>{title}</strong>
</header>

ثم في home.html:

{include_tpl partials/header.html}

الجزء المضمّن يرى نفس بيانات الصفحة. لا يمكنه الخروج من مجلد القوالب أو تضمين ملف PHP.

استخدم raw فقط عندما تعرف لماذا

الوضع الطبيعي:

{description}

هذا آمن للـ HTML. إذا كنت تملك HTML موثوقًا أو منقّى مسبقًا فقط:

{raw trusted_description_html}

عالج أخطاء القوالب

try {
    echo $tpl->render('home.html', $data);
} catch (MOFTemplateException $e) {
    error_log($e->getMessage());
    http_response_code(500);
    echo 'حدث خطأ في عرض الصفحة.';
}

لا تعرض رسالة الاستثناء التفصيلية للزائر في production. سجلها للمطور.

قبل الإنتاج

• شغّل php tests/run.php بعد أي تعديل على المحرك.
• اجعل القوالب قابلة للكتابة فقط للجهة التي تدير الكود.
• ضع الكاش خارج public web root متى أمكن.
• استخدم raw للقيم الموثوقة فقط.
• نفّذ SQL وpagination والتحقق من الصلاحيات في التطبيق، لا في القالب.
• تعامل مع MOFTemplateException في طبقة العرض المناسبة لتطبيقك.