Twig/internals

يتميز محرك القوالب Twig بأنه قابل للتوسيع ويمكن تطويره وتحسينه، لكن انتبه إلى وجوب إنشاء توسعة (extension) أولًا قبل التعديل على النواة (core)، ذلك أن التوسعات يمكنها التعديل على أغلب المزايا والخصائص الموجودة. كذلك فإن هذه الصفحة مفيدة لمن يرغب في معرفة كيف يعمل Twig في الحقيقة.

كيفية عمل Twig

يمكن تلخيص عملية تصيير القالب (template rendering) في Twig في أربع خطوات أساسية:

• حمِّل القالب: إذا كان القالب مصرَّفًا (compiled) فحمِّله وانتقل إلى خطوة التقييم (Evaluation)، وإلا فقم بما يلي:
  • أولًا، يقطِّع المعجم (lexer) شيفرة القالب المصدرية إلى وحدات صغيرة (tokens) من أجل تسهيل المعالجة.
  • ثم يحول المحلل (parser) مجرى تلك الوحدات إلى شجرة عقد مفيدة، وهي شجرة البنية اللغوية المجردة (Abstract syntax tree).
  • وأخيرًا، يحول المصرِّف تلك الشجرة إلى شيفرة PHP.

• والآن، قيِّم القالب، بمعنى أن تستدعي التابع display()‎ من القالب المصرَّف وتمرر السياق إليه.

المعجم (The Lexer)

يقطِّع المعجم شيفرة القالب المصدرية إلى مجرى الوحدات -كل وحدة هي نسخة من ‎\Twig\Token، والمجرى نفسه نسخة من ‎\Twig\TokenStream، والمعجم الافتراضي يتعرف على 13 نوع مختلف من أنواع الوحدات:

• ‎\Twig\Token::BLOCK_START_TYPE و ‎\Twig\Token::BLOCK_END_TYPE: محدِّد (Delimiter) لكتل الشيفرات ({% %}).
• ‎\Twig\Token::VAR_START_TYPE و ‎\Twig\Token::VAR_END_TYPE: محدِّد للمتغيرات ({{ }}).
• ‎\Twig\Token::TEXT_TYPE: نص خارج تعبير ما.
• ‎\Twig\Token::NAME_TYPE: اسم داخل التعبير.
• ‎\Twig\Token::NUMBER_TYPE: عدد داخل التعبير.
• ‎\Twig\Token::STRING_TYPE: سلسلة نصية داخل التعبير.
• ‎\Twig\Token::OPERATOR_TYPE: عامل (Operator).
• ‎\Twig\Token::PUNCTUATION_TYPE: علامة ترقيم.
• ‎\Twig\Token::INTERPOLATION_START_TYPE و ‎\Twig\Token::INTERPOLATION_END_TYPE: محدّدات لإقحام النصوص (string interpolation).
• ‎\Twig\Token::EOF_TYPE: نهاية القالب.

تستطيع تحويل الشيفرة المصدرية يدويًا إلى مجرى وحدات من خلال استدعاء التابع tokenize()‎ الخاص بالبيئة:

$stream = $twig->tokenize(new \Twig\Source($source, $identifier));

وبما أن المجرى به التابع ‎__toString()‎ فتستطيع الحصول على تمثيل نصي له بترديد الكائن باستخدام أمر echo:

echo $stream."\n";

ويكون خرج قالب Hello {{ name }}:

TEXT_TYPE(Hello )
VAR_START_TYPE()
NAME_TYPE(name)
VAR_END_TYPE()
EOF_TYPE()

لاحظ أن المعجم الافتراضي ‎\Twig\Lexer يمكن تغييره باستدعاء التابع setLexer()‎:

$twig->setLexer($lexer);

المحلل (Parser)

يحوِّل المحلل مجرى الوحدات إلى شجرة بُنى مجردة كما ذكرنا أعلاه، أو شجرة من العقد تكون نسخة من ‎\Twig\Node\ModuleNode، وتعرِّف توسعة core العقد الأساسية مثل for و if وغيرهما، إضافة إلى عقد التعبير.

تستطيع تحويل مجرى الوحدات يدويًا إلى شجرة عقد باستدعاء التابع parse()‎ الخاص بالبيئة:

$nodes = $twig->parse($stream);

إذا استخدمت أمر echo على كائن العقدة فسيعطيك تمثيلًا جميلًا للشجرة:

echo $nodes."\n";

انظر خرج القالب Hello {{ name }}:

\Twig\Node\ModuleNode(
  \Twig\Node\TextNode(Hello )
  \Twig\Node\PrintNode(
    \Twig\Node\Expression\NameExpression(name)
  )
)

لاحظ أن المحلل الافتراضي ‎\Twig\TokenParser\AbstractTokenParser يمكن تغييره باستدعاء التابع setParser()‎:

$twig->setParser($parser);

المصرِّف (Compiler)

تتم آخر خطوة باستخدام المصرِّف، إذ يأخذ شجرة العقد كمدخَل ويولد شيفرة PHP قابلة للاستخدام من أجل التنفيذ وقت التشغيل (runtime execution) الخاص بالقالب. تستطيع تصريف شجرة عقد يدويًا إلى شيفرة PHP باستخدام التابع compile()‎ الخاص بالبيئة:

$php = $twig->compile($nodes);

ويكون القالب المولَّد لقالب Hello {{ name }} كما يلي أدناه، وقد يختلف الخرج الحقيقي وفقًا لنسخة Twig التي تستخدمها:

/* Hello {{ name }} */
class __TwigTemplate_1121b6f109fe93ebe8c6e22e3712bceb extends Template
{
    protected function doDisplay(array $context, array $blocks = [])
    {
        // سطر 1
        echo "Hello ";
        echo twig_escape_filter($this->env, (isset($context["name"]) ? $context["name"] : null), "html", null, true);
    }

    // شيفرة إضافية هنا
}

لاحظ أن المصرِّف الافتراضي ‎\Twig\Compiler يمكن تغييره من خلال استدعاء التابع setCompiler()‎:

$twig->setCompiler($compiler);

انظر أيضًا

• توسيع عمل محرك Twig
• مقدمة عن محرك القوالب Twig

المصادر

• صفحة المكونات الداخلية لمحرك القوالب Twig من توثيق Twig الرسمي.