Twig/default

يعيد المرشح default القيمة الافتراضية الممررة إليه إذا كانت غير معرفة أو فارغة، وإلا فإنه يعيد قيمة المتغير:

{{ var|default('var is not defined') }}

{{ var.foo|default('foo item on var is not defined') }}

{{ var['foo']|default('foo item on var is not defined') }}

{{ ''|default('passed var is empty')  }}

إذا استُخدم default على تعبير يستخدم المتغيرات في بعض استدعاءات التوابع فتأكد أن تستخدمه في كل حالة يكون المتغير فيها غير معرف:

{{ var.method(foo|default('foo'))|default('foo') }}

قد يطلِق استخدام المرشح default على قيمة بوليانية سلوكًا غير متوقع، وذلك لأن false تعامَل كقيمة فارغة، وعندئذ استخدم ??:

{% set foo = false %}
{{ foo|default(true) }} {# true #}
{{ foo ?? true }} {# false #}

الوسائط

default: القيمة الافتراضية

---

<noinclude>{{DISPLAYTITLE: المرشح escape في Twig}}</noinclude>

يهرِّب المرشح escape سلسلة نصية باستخدام خطط تعتمد على السياق، وهي تستخدم خطة تهريب HTML افتراضيًا:

<p>
    {{ user.username|escape }}
</p>

يعرَّف المرشح باسم بديل هو e من أجل التيسير وتوفير الوقت:

<p>
    {{ user.username|e }}
</p>

يمكن استخدام المرشح escape في سياقات أخرى كذلك غير HTML مستفيدين من وسيط اختياري يعرّف خطة التهريب التي يجب استخدامها:

{{ user.username|e }}
{# يكافئ #}
{{ user.username|e('html') }}

انظر كيف يمكن تهريب المتغيرات المدرَجة في شيفرة جافاسكربت:

{{ user.username|escape('js') }}
{{ user.username|e('js') }}

يدعم المرشح escape خطط التهريب التالية لمستندات HTML:

• html: يهرب سلسلة نصية لسياق متن HTML.
• js: تهرب سلسلة نصية لسياق جافاسكربت.
• css: تهرب سلسلة نصية لسياق CSS. يمكن تطبيق تهريب css على أي سلسلة نصية تُدخل في CSS، وتهرِّب كل شيء عدا الأحرف والأرقام.
• url: تهرب سلسلة نصية لمحدد الموارد الموحد (URI)، ولا يُدخل إلا مكونٌ فرعي.
• html_attr: تهرب سلسلة نصية لسياق سمة HTML.

لاحظ أن التهريب السياقي في مستندات HTML يصعب تنفيذه، ويتوقف اختيار خطة التهريب المناسبة على عوامل كثيرة، فانظر توثيقًا مثل the OWASP prevention cheat sheet لتعلم المزيد عن الأمر.

لاحظ أن المرشح escape يستخدم دالة htmlspecialchars الخاصة بلغة PHP من أجل خطة تهريب HTML.

انتبه عند استخدام التهريب التلقائي إذ أن Twig يحاول ألا يهرب متغيرًا تهريبًا مضاعفًا (double-escape) إذا كانت خطة التهريب التلقائية هي نفسها التي يستخدمها مرشح escape، لكن ذلك لا يعمل عند استخدام متغير ما كخطة تهريب:

{% set strategy = 'html' %}

{% autoescape 'html' %}
    {{ var|escape('html') }}   {# لن يهرَّب تهريبًا مضاعفًا #}
    {{ var|escape(strategy) }} {# سيهرَّب تهريبًا مضاعفًا #}
{% endautoescape %}

التهريب التلقائي يجب أن يعطَّل عند استخدام متغير كخطة تهريب:

{% set strategy = 'html' %}

{% autoescape 'html' %}
    {{ var|escape(strategy)|raw }} {# won't be double-escaped #}
{% endautoescape %}

المهرِّبات الخاصة

تستطيع تعريف مهربات خاصة باستدعاء التابع setEscaper()‎ على نسخة توسيع المهرب، ويجب أن يكون أول وسيط هو اسم المهرب ليستَخدم في استدعاء escape، والثاني يجب أن يكون نوع بيانات PHP قابل للاستدعاء "callable":

$twig = new \Twig\Environment($loader);
$twig->getExtension(\Twig\Extension\EscaperExtension::class)->setEscaper('csv', 'csv_escaper');

عند استدعاء Twig لنوع البيانات callable فإن الأخير يستلم نسخة من بيئة Twig والسلسلة النصية التي يجب تهريبها، ومجموعة محارف (charset).

لاحظ أن المهربات لا يمكن تخطيها لأنها تُعد التطبيق الأخير، وكذا من أجل تحسين الأداء.

الوسائط

strategy: خطة التهريب.

charset: مجموعة محارف السلسلة النصية.

---

<noinclude>{{DISPLAYTITLE: المرشح filter في Twig}}</noinclude>

المرشح filter يرشح العناصر من تسلسل أو ربط (mapping) باستخدام دالة سهمية تستقبل القيمة من ذلك التسلسل أو الربط:

{% set sizes = [34, 36, 38, 40, 42] %}

{{ sizes|filter(v => v > 38)|join(', ') }}
{# output 40, 42 #}

وهو يسمح -مع الوسم for- بترشيح العناصر التي يراد التكرار عليها:

{% for v in sizes|filter(v => v > 38) -%}
    {{ v }}
{% endfor %}
{# output 40 42 #}

كما يعمل مع الربط أيضًا:

{% set sizes = {
    xs: 34,
    s:  36,
    m:  38,
    l:  40,
    xl: 42,
} %}

{% for k, v in sizes|filter(v => v > 38) -%}
    {{ k }} = {{ v }}
{% endfor %}
{# output l = 40 xl = 42 #}

تستقبل الدالة السهمية المفتاح كوسيط ثاني:

{% for k, v in sizes|filter((v, k) => v > 38 and k != "xl") -%}
    {{ k }} = {{ v }}
{% endfor %}
{# output l = 40 #}

لاحظ أن الدالة السهمية لها وصول إلى السياق الحالي.

الوسائط

array: التسلسل أو الربط.

arrow: الدالة السهمية.

---

<noinclude>{{DISPLAYTITLE: المرشح first في Twig}}</noinclude>

يعيد المرشح first أول عنصر في تسلسل أو ربط (mapping) أو سلسلة نصية:

{{ [1, 2, 3, 4]|first }}
{# outputs 1 #}

{{ { a: 1, b: 2, c: 3, d: 4 }|first }}
{# outputs 1 #}

{{ '1234'|first }}
{# outputs 1 #}

لاحظ أن هذا المرشح يعمل مع الكائنات التي تستخدم واجهة Traversable.

----

<noinclude>{{DISPLAYTITLE: المرشح format في Twig}}</noinclude>

يهيئ المرشح format السلسلة النصية باستبدال العناصر النائبة (placeholders) التي تتبع ترميز sprintf. انظر المثال التالي الذي يطبع "I like foo and bar" إذا كان معامِل foo مساويًا لسلسلة foo النصية:

{{ "I like %s and %s."|format(foo, "bar") }}

---

<noinclude>{{DISPLAYTITLE: المرشح format_currency في Twig}}</noinclude>

يهيئ المرشح format_currency العدد ليكون على صيغة العملة:

{# €1,000,000.00 #}
{{ '1000000'|format_currency('EUR') }}

يمكن تمرير سمات (attributes) من أجل تعديل الخرج:

{# €12.34 #}
{{ '12.345'|format_currency('EUR', {rounding_mode: 'floor'}) }}

{# €1,000,000.0000 #}
{{ '1000000'|format_currency('EUR', {fraction_digit: 4}) }}

القائمة التالية تحتوي على الخيارات المدعومة:

• grouping_used.
• decimal_always_shown.
• max_integer_digit.
• min_integer_digit.
• integer_digit.
• max_fraction_digit.
• min_fraction_digit.
• fraction_digit.
• multiplier.
• grouping_size.
• rounding_mode.
• rounding_increment.
• format_width.
• padding_position.
• secondary_grouping_size.
• significant_digits_used.
• min_significant_digits_used.
• max_significant_digits_used.
• lenient_parse.

يستخدم المرشح الإعدادات المحلية افتراضيًا، ويمكن تمريرها صراحة إليه:

{# 1.000.000,00 £ #}
{{ '1000000'|format_currency('EGP', locale='eg') }}

لاحظ أن المرشح format_currency جزء من IntlExtension وهذا لا يكون مثبتًا افتراضيًا، لذا ثبته أولًا:

$ composer require twig/intl-extra

ثم ثبت twig/extra-bundle في حالة مشاريع Symfony:

$ composer require twig/extra-bundle

أما غير ذلك فأضف التوسيع صراحة إلى بيئة Twig:

use Twig\Extra\Intl\IntlExtension;

$twig = new \Twig\Environment(...);
$twig->addExtension(new IntlExtension());