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 نوع مختلف من أنواع الوحدات:

# ‫محدد Delimiter لكتل الشيفرات {% %}
\Twig\Token::BLOCK_START_TYPE
\Twig\Token::BLOCK_END_TYPE

# ‫محدد للمتغيرات {{ }}
‎\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

# ‫عامل Operator
‎\Twig\Token::OPERATOR_TYPE

# علامة ترقيم
‎\Twig\Token::PUNCTUATION_TYPE

# ‫محددات لإقحام النصوص string interpolation
‎\Twig\Token::INTERPOLATION_START_TYPE
\Twig\Token::INTERPOLATION_END_TYPE: 

# نهاية القالب
‎\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 الرسمي.