ضبط محرك القوالب تويغ وتوسيع عمله

لقد تم بناء تويغ ليكون قابلًا للتوسيع بشكل كامل حيث يمكنك التحكم في كل شيء فيه كما يمكنك ضبط بيئة العمل بما يناسب المستخدم و تعريف دوال ومرشحات مخصصة تلبية أي متطلبات تريدها.

خيارات بيئة العمل في تويغ

عند استدعاء تويغ فإننا نكتب السطر التالي:

$options = array();
$twig = new \Twig\Environment($loader, $options);

يحوي الوسيط الثاني options خيارات التحكم بطريقة عمل تويغ مثلا لتفعيل وضع تصحيح الأخطاء:

$options = ['debug' => true]; 

حيث تخزن خيارات بيئة العمل على شكل مصفوفة كل عنصر منها يشمل خيارًا محددًا هي:

• debug: تفعيل وضع تصحيح الأخطاء، القيمة الافتراضية غير مفعل false، وفي حال استخدام تويغ مع ووردبريس فيرتبط بتفعيل الخيار wp_denug في ووردبريس.
• charset: تحديد طريقة ترميز الأحرف القيمة الافتراضية utf8.
• cache: فيه نجد المسار الذي سوف نخزن به ملفات PHP الناتجة عن القالب أو نستعمل القيمة false في حال عدم رغبتنا بتخزينها وهذا هو الوضع الافتراضي.
• auto_reload: يطلب من محرك القالب أن يعيد توليد أو تصريف ملف PHP الناتج عن القالب كل مرة حتى في حال عدم تغير القالب.
• strict_variables: في حال كون قيمته true، فإن تويغ يعطي خطأ في حال استخدام اسم متغير غير موجود أما في حال ضبطه على false وهو الوضع الافتراضي فإن تويغ يعيد قيمة فارغة في حال لم يعثر على المتغير المطلوب.
• autoescape: يطلب من تويغ القيام بعملية تهريب آمنة مناسبة عند إخراج أي متغير.

استخدام الدالة dump في وضع تصحيح الأخطاء

يختلف عمل هذه الدالة تبعا للخيار debug وهو الخيار المسؤول عن تفعيل وضع تصحيح الأخطاء في بيئة عمل تويغ، وإذا كان وضع تصحيح الأخطاء غير مفعل لا تعيد الدالة dump أي قيمة أما عندما يكون وضع تصحيح الأخطاء مفعلًا فإن للدالة السابقة استخدامين اثنين، الأول عند استدعائها دون تمرير أي وسيط فإنه تظهر كافة المتغيرات المتعلقة بالقالب مع قيمتها مثل:

{{ dump() }}

أما الطريقة الثانية فهي أن نمرر لها متغيرًا ما، فإنها تعيد قيمة ذلك المتغير وفي حال كان المتغير مصفوفة فإنها تطبع جميع عناصر المصفوفة:

{{ dump( user ) }}

يفيد استعمال هذه الدالة كثيرًا في استكشاف الأخطاء. حيث تستخدم لطباعة البيانات في وضع تصحيح الأخطاء، كما تتميز بطباعة كل محتويات المتغير مهما كان نوعه، فإذا كان المتغير مصفوفة طبعت كافة محتويات المصفوفة و إذا كان المتغير كائن طبعت جميع خصائص الكائن.

لنفرض أن التعبير التالي لا يعيد قيمة

{{ post.title }}

فإننا يمكن أن نعدل الكود ليصبح على الشكل التالي:

{{ post.title }}
{{ dump( post ) }}
{# the last line output:
 object (post)
 public ‘title’ => string ‘’ 
 public content => string ‘my post’ 
#}

لاحظ أن الدالة السابقة تعيد جميع خصائص الكائن post مع نوع كل خاصية مما يسهل تتبع الأخطاء.

توسيع عمل تويغ

يهدف توسيع تويغ إلى تمكين المستخدِم من العديد من التقنيات غير المتوفرة بشكل افتراضي في تويغ.

التوسيع بواسطة مكتبات جاهزة

Twig مرن جدا بحيث يسمح للمطور بسهول بتعريف مرشحات ودوال خاصة، كما توجد العديد من المكتبات الجاهزة التي تدعم تويغ وتضيف له العديد من المرشحات والدوال الإضافية مثلا يمكن الاطلاع من هذه الصفحة على قائمة ببعض المكتبات الشهيرة وتحميلها.

استخدام التوسعات Extensions

توسعات Twig هي حزم تضيف مزايا جديدة إليه، وتستطيع تسجيل توسعة من خلال التابع addExtension()‎:

• عند العمل بدون composer

$twig->addExtension(new ExtensionClassName());

• كما يمكن أن يتم تسجيل التوسعة من خلال composer:

$ composer require twig/extension-file

بعد إضافة توسعة إلى تويغ يمكن استخدام الدوال أو المرشحات الجديدة التي تحتويها، مثلا المكتبة markdown-extra تضيف عددًا من المرشحات التي تتعامل مع نصوص من نوع ماركدون:

{% apply html_to_markdown %}
    <h2>Title 2</h2>
    <h3>Title 3</h3>
{% endapply %}
{# output: 
## Title 2 
### Title 3 
#}

التوسيع بواسطة الشيفرة الجامعة macro

أن أبسط طريقة لتوسيع تويغ هو استخدام تويغ نفسه ويتم ذلك من خلال الوسم macro حيث يمكننا من تعريف شيفرة جامعة خاصة بنا يمكننا إعادة استخدامها:

{% macro EcoHello( student ) %} 
    Hello {{ student }}! 
{% endmacro %}
{{ _self.EcoHello('Ziad') }}
{# output: Hello Ziad! #}

يمكن تعريف الشيفرات الجامعة في ملف تويغ منفصل ثم استيراده في الملف الحالي، مثلا ننشأ ملف اسمه macros.twig، ونكتب به ما يلي:

{# macros.twig #}
{% macro EcoHello( student ) %}
Hello {{ student }}!
{% endmacro %}

ثم عند الرغبة في استخدام هذا الماكرو نستورد الملف على النحو التالي:

{% import "macros.twig" as mymacros %}
{% if mymacros.EcoHello is defined %}
    {{ mymacros.EcoHello('Ziad') }}
{% endif %}
{{ mymacros.EcoHello('Ziad') }}
{# output: Hello Ziad! #}

كما لا حظنا في المثال السابق يمكن أن نتحقق من وجود شيفرة جامعة قبل استخدامها للتأكد من أنها مُعرَّفة في الملف الذي استوردته.

ملاحظة: يمكن كتابة السطر الأول على النحو التالي وذلك يؤدي نفس الهدف:

{% from "macros.twig" import mymacros %}

المتغيرات العامة

هي متغيرات متاحة في جميع قوالب تويع ويمكن أن نضيفها إلى تويغ بعدة طرق أبسطها هو الشكل التالي:

$twig = new Twig_Environment($loader);
$twig->addGlobal('MyWebsite', 'example.com');

بعد ذلك يمكن استعمال المغير السابق في أي قالب على النحو التالي:

{{ MyWebsite }}

إنشاء مرشحات مخصصة

لإضافة أي مرشح إلى تويغ نقوم بتعديل الملف الذي نستدعيه لتثيبت تويغ أو لإخراج القالب ونضيف المرشح عليه، ويمكنك مراجعة المقال الأول لمعرفة المزيد عن تثبيت تويغ. مثلا في الأسطر الثلاث الأخيرة من الشيفرة التالية سوف نلاحظ أننا قمنا بتعريف مرشح ثم أضفناه إلى تويغ ثم أعطينا الأمر بإخراج المستند المنسق:

<?php
spl_autoload_register(function ($classname) {
    $filename = './' . str_replace('\\', '/', $classname) .'.php';
    if (file_exists($filename)) require_once $filename;
};
require_once 'Twig\Loader\FilesystemLoader.php';
$loader = new Twig\Loader\FilesystemLoader('.');
$twig = new Twig\Environment($loader);
$filter = new Twig\TwigFilter('countchars', 'count_chars');
$twig->addFilter($filter);
echo $twig->render('template.twig', ['var1' => 'value1', 'var2' => 'value2']);

لقد أضفنا مرشح أسميناه countchars يستدعي هذا المرشح دالة PHP موجدة اسمها count_chars وهي تعيد عدد الأحرف في نص ما و لاستدعاء هذا المرشح في ملف تويغ نستعمله مثل أي مرشح آخر قد تم استدعائها في القالب التالي عند كتابة اسم المرشح الذي اضفناه countchars مسبوقا بـ | :

{{ 'Ziad'|countchars }}
{# output: 4 #}

يمكن لإنشاء المرشح استخدام دالة PHP جاهزة أو إنشاء دالة PHP خاصة بنا، ثم إضافتها مثل مرشح في تويغ، أي أن المرشحات في تويغ هي عبارة عن دوال في PHP.

قد تكون تلك الدوال مبية في لغة PHP وقد تكون دوال من إنشاء المطور نفسه.

إضافة دوال خاصة

يمكن بسهول إضافة دالة إلى تويغ بطريقة مشابهة لإضافة مرشح وكمثال يمكن أن نكتب التالي:

$function = new \Twig\TwigFunction('SayHello', function () { return 'Hello'; });
$twig->addFunction($function);

بعد ذلك يمكن استدعائها في أي قالب على النحو التالي:

{{ SyaHello() }}
{# output: Hello #}

تهدف المرشحات والدوال الخاصة إلى اضافة مزايا إضافية غير متوفرة مباشرة في بنية تويغ بحيث تلبي الاحتياجات للموقع.

كلمة الختام

لقد تحدثنا في هذا المقال عن تهيئة بيئة العمل في تويغ وعن استخدام الدالة dump في وضع تصحيح الأخطاء ثم انتقلنا إلى كيفية اضافة مرشحات ودوال خاصة بنا إلى تويغ.

بهذا القدر من المفترض بك عزيزي القارئ أن تكون قد وصلت فكرة واضحة عن تويغ بحيث يمكن الانطلاق بقوة في العمل مع تويغ وفي حال رغبتك بالمزيد من التفاصيل يمكنك مراجعة الترجمة العربية للتوثيق الرسمي لتويغ في موسوعة حسوب.