المرشح escape في Twig

يهرِّب المرشح 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: مجموعة محارف السلسلة النصية.

انظر أيضًا

المصادر

صفحة توثيق المرشح escape في توثيق Twig الرسمي