الفرق بين المراجعتين لصفحة: «PHP/htmlspecialchars»
< PHP
هارون-بوكرش (نقاش | مساهمات) لا ملخص تعديل |
لا ملخص تعديل |
||
| سطر 2: | سطر 2: | ||
((PHP 4, PHP 5, PHP 7 | ((PHP 4, PHP 5, PHP 7 | ||
تُحول الدالة | تُحول الدالة <code>htmlspecialchars()</code> المحارف الخاصة إلى مدخلات HTML (HTML entities). | ||
== الوصف == | |||
<syntaxhighlight lang="php"> | <syntaxhighlight lang="php"> | ||
string htmlspecialchars ( string $string [, int $flags = ENT_COMPAT | ENT_HTML401 [, string $encoding = ini_get("default_charset") [, bool $double_encode = TRUE ]]] ) | |||
</syntaxhighlight> تحمل بعض المحارف معانٍ خاصة بلغة HTML، إذ يجب تحويلها إلى مدخلات HTM للمحافظة على معانيها ومدلولاتها. تُحول الدالة <code>htmlspecialchars()</code> هذه المحارف إلى مدخلات HTML وتعيدها في سلسلة نصية. استعمل الدالة <code>[[PHP/htmlentities|htmlentities()]]</code> إذا أردتَ تحويل كل السلاسل النصية القابلة للتحويل إلى مدخلات HTML. | |||
إذا كان ترميز محارف السلسلة النصية المُمرَّرة إلى هذه الدالة وترميز محارف المستند النهائي متماثلين، فإنَّ هذه الدالة كافية لتحويل المحارف الخاصة إلى مدخلات HTML في أغلبية الحالات؛ أما لو لم تكن المحارف التي تريد ترميزها موجودةً في جدول المحارف الخاص بترميز المستند النهائي، وكنتَ تريد الحفاظ على قيم تلك المحارف، فلن تكفيك هذه الدالة ولا الدالة <code>[[PHP/htmlentities|htmlentities()]]</code>، وعليك حينئذٍ استخدام الدالة <code>[[PHP/mb encode numericenity|mb_encode_numericenity()]]</code>. | |||
=== جدول التحويلات === | |||
{| class="wikitable" | {| class="wikitable" | ||
!المُحرَّف | |||
!البديل | |||
|- | |- | ||
|& (الواو اللاتينية) | |& (الواو اللاتينية) | ||
|&amp; | |<code>&amp;</code> | ||
|- | |- | ||
|" (علامة الإقتباس المزدوجة) | |" (علامة الإقتباس المزدوجة) | ||
|;quot& إذا كانت الخاصية ENT_NOQUOTES | |<code>;quot&</code> إذا كانت الخاصية <code>ENT_NOQUOTES</code> غير مُفَعلة. | ||
|- | |- | ||
|' (علامة الإقتباس المُفرَدة) | |' (علامة الإقتباس المُفرَدة) | ||
|&#039; (في حالة ENT_HTML401) أو ;apos& (في حالة ENT_XML1 أو ENT_XHTML أو ENT_HTML5).إذا كانت الخاصية ENT_NOQUOTES مُفَعلة. | |<code>&#039;</code> (في حالة <code>ENT_HTML401</code>) أو <code>;apos&</code> (في حالة <code>ENT_XML1</code> أو <code>ENT_XHTML</code> أو <code>ENT_HTML5</code>).إذا كانت الخاصية <code>ENT_NOQUOTES</code> مُفَعلة. | ||
|- | |- | ||
|< (علامة أصغر من) | |< (علامة أصغر من) | ||
|&lt; | |<code>&lt;</code> | ||
|- | |- | ||
|> (علامة أكبر من) | |> (علامة أكبر من) | ||
|&gt; | |<code>&gt;</code> | ||
|} | |} | ||
== المعاملات == | |||
=== | === <code>string</code> === | ||
السلسلة النصية المُدخَلة المُرَاد تحويلها. | السلسلة النصية المُدخَلة المُرَاد تحويلها. | ||
=== | === <code>flags</code> === | ||
قناع bitmask يتكون من راية أو أكثر من الرايات المبينة في جدول ثوابت الرايات المُتاحة. تُحدد هذه الرايات كيفية التعامل مع علامات الاقتباس وسلاسل التعليمات البرمجية الخاطئة ونوع المُستند المُستعمل. قيمة القناع الإفتراضي هي ENT_COMPAT | ENT_HTML401. | قناع bitmask يتكون من راية أو أكثر من الرايات المبينة في جدول ثوابت الرايات المُتاحة. تُحدد هذه الرايات كيفية التعامل مع علامات الاقتباس وسلاسل التعليمات البرمجية الخاطئة ونوع المُستند المُستعمل. قيمة القناع الإفتراضي هي <code>ENT_COMPAT | ENT_HTML401</code>. | ||
==== ثوابت الرايات المُتاحة ==== | |||
{| class="wikitable" | {| class="wikitable" | ||
!الثابت | |||
!الوصف | |||
|- | |- | ||
|ENT_COMPAT | |<code>ENT_COMPAT</code> | ||
|يحتوي الجدول مدخلات لعلامات الاقتباس المزدوجة دون علامات الاقتباس المفردة | |يحتوي الجدول مدخلات لعلامات الاقتباس المزدوجة دون علامات الاقتباس المفردة | ||
|- | |- | ||
|ENT_QUOTES | |<code>ENT_QUOTES</code> | ||
|يحتوي الجدول مدخلات لعلامات الاقتباس المزدوجة وعلامات الاقتباس المفردة | |يحتوي الجدول مدخلات لعلامات الاقتباس المزدوجة وعلامات الاقتباس المفردة | ||
|- | |- | ||
|ENT_NOQUOTES | |<code>ENT_NOQUOTES</code> | ||
|لا يحتوي الجدول على علامات اقتباس، مزدوجةً كانت أو مفردة. | |لا يحتوي الجدول على علامات اقتباس، مزدوجةً كانت أو مفردة. | ||
|- | |- | ||
|ENT_IGNORE | |<code>ENT_IGNORE</code> | ||
|تَتَجاهل بصمت سلسلة التعليمات البرمجية الخاطئة. لا ننصح | |تَتَجاهل بصمت سلسلة التعليمات البرمجية الخاطئة. لا ننصح باستعمال هذه الراية لما لها قد ينتج عنها من تداعيات أمنية. | ||
|- | |- | ||
|ENT_SUBSTITUTE | |<code>ENT_SUBSTITUTE</code> | ||
|تَستَبدِل سلاسل التعليمات البرمجية الخاطئة بمحرف الاستبدال في يونيكود ورمزه | |تَستَبدِل سلاسل التعليمات البرمجية الخاطئة بمحرف الاستبدال في يونيكود ورمزه <code>U+FFFD</code> أو <code>;xFFFD#&</code>؛ بدلًا من أن تُعيد سلسلة نصية فارغة. | ||
|- | |- | ||
|ENT_DISALLOWED | |<code>ENT_DISALLOWED</code> | ||
|تَستَبدِل سلاسل التعليمات البرمجية الخاطئة بمحرف الاستبدال في يونيكود ورمزه | |تَستَبدِل سلاسل التعليمات البرمجية الخاطئة بمحرف الاستبدال في يونيكود ورمزه <code>U+FFFD</code> أو <code>;xFFFD#&</code>؛ بدلًا من تركها على حالها كما هي. تتجلى فائدة هذه الراية في ضمان حسن صياغة مستندات XML ذات المحتوى الخارجي. | ||
|- | |- | ||
|ENT_HTML401 | |<code>ENT_HTML401</code> | ||
|جدول لمعيار HTML 4.01. | |جدول لمعيار HTML 4.01. | ||
|- | |- | ||
|ENT_XML1 | |<code>ENT_XML1</code> | ||
|جدول لمعيار XML1. | |جدول لمعيار XML1. | ||
|- | |- | ||
|ENT_XHTM | |<code>ENT_XHTM</code> | ||
|جدول لمعيار XHTML. | |جدول لمعيار XHTML. | ||
|- | |- | ||
|ENT_HTML5 | |<code>ENT_HTML5</code> | ||
|جدول لمعيار HTML5. | |جدول لمعيار HTML5. | ||
|} | |} | ||
=== encoding === | |||
مُعامل إختياري يُحدد الترميز المُستعمل في تحويل المحارف. في حالة عدم إدراجه، فستختلف القيمة القياسية للمعامل encoding بإختلاف نسخة PHP. إذ تَستَعمل النسخة PHP 5.6 وما بعدها قيمة خيار الضبط default_charset وتستعمل النسخ PHP 5.4 و 5.5 PHP الترميز UTF-8 أما نسخ PHP الأقدم فتستخدم ترميز ISO-8859-1. | مُعامل إختياري يُحدد الترميز المُستعمل في تحويل المحارف. في حالة عدم إدراجه، فستختلف القيمة القياسية للمعامل <code>encoding</code> بإختلاف نسخة PHP. إذ تَستَعمل النسخة PHP 5.6 وما بعدها قيمة خيار الضبط <code>default_charset</code> وتستعمل النسخ PHP 5.4 و 5.5 PHP الترميز UTF-8 أما نسخ PHP الأقدم فتستخدم ترميز ISO-8859-1. | ||
على الرغم من أنَّ ضبط المعامل encoding في الدالة htmlspecialchars() من الناحية الفنية هو أمرٌ اختياري، إلا أنه من المستحسن ضبط قيمته في حال استعمال نسخة 5.5 PHP أو ما قبلها أو في حال ما كانت قيمة خيار الضبط default_charset غير موافقة للسلسلة النصية المُدخلة. من أجل الدالة htmlspecialchars() جُعلت الترميزات ISO-8859-1 و ISO-8859-15 و UTF-8 و cp866 و cp1251 و cp1252 و KOI8-R متكافئة مع بعضها البعض شرط أن تكون السلسلة النصية المُدخلة صالحة للترميز، حيث تَشغُل الأحرف المُحولة نفس المواضِع في كل الترميزات. | على الرغم من أنَّ ضبط المعامل <code>encoding</code> في الدالة <code>htmlspecialchars()</code> من الناحية الفنية هو أمرٌ اختياري، إلا أنه من المستحسن ضبط قيمته في حال استعمال نسخة 5.5 PHP أو ما قبلها أو في حال ما كانت قيمة خيار الضبط <code>default_charset</code> غير موافقة للسلسلة النصية المُدخلة. من أجل الدالة <code>htmlspecialchars()</code> جُعلت الترميزات ISO-8859-1 و ISO-8859-15 و UTF-8 و cp866 و cp1251 و cp1252 و KOI8-R متكافئة مع بعضها البعض شرط أن تكون السلسلة النصية المُدخلة صالحة للترميز، حيث تَشغُل الأحرف المُحولة نفس المواضِع في كل الترميزات. | ||
==== ترميزات المحارف المدعومة ==== | |||
{| class="wikitable" | {| class="wikitable" | ||
!ترميز المحارف | |||
!التسمية | |||
!الوصف | |||
|- | |- | ||
|ISO8859-1 | |<code>ISO8859-1</code> | ||
|ISO8859-1 | |ISO8859-1 | ||
|دول أوروبا الغربية، Latin-1. | |دول أوروبا الغربية، Latin-1. | ||
|- | |- | ||
|ISO8859-5 | |<code>ISO8859-5</code> | ||
|ISO8859-5 | |ISO8859-5 | ||
|المحارف السيريلية قليلة الاستخدام (اللاتينية أو السيريلية). | |المحارف السيريلية قليلة الاستخدام (اللاتينية أو السيريلية). | ||
|- | |- | ||
|ISO8859-15 | |<code>ISO8859-15</code> | ||
|ISO8859-15 | |ISO8859-15 | ||
|أوروبا الغربية، Latin-9. | |أوروبا الغربية، Latin-9. | ||
| سطر 105: | سطر 101: | ||
اُضيفت علامة اليورو، والحروف الفرنسية والفنلندية غير الموجودة في ترميز Latin-1 (أي ISO-8859-1). | اُضيفت علامة اليورو، والحروف الفرنسية والفنلندية غير الموجودة في ترميز Latin-1 (أي ISO-8859-1). | ||
|- | |- | ||
|UTF-8 | |<code>UTF-8</code> | ||
| | | | ||
|ترميز ASCII المتوافق مع يونيكود (multi-byte 8-bit Unicode). | |ترميز ASCII المتوافق مع يونيكود (multi-byte 8-bit Unicode). | ||
|- | |- | ||
|cp866 | |<code>cp866</code> | ||
|ibm866,866 | |ibm866,866 | ||
|المحارف السيريلية الخاصة بنظام التشغيل دوس (DOS). | |المحارف السيريلية الخاصة بنظام التشغيل دوس (DOS). | ||
|- | |- | ||
|cp1251 | |<code>cp1251</code> | ||
|Windows-1251,win-1251,1251 | |Windows-1251,win-1251,1251 | ||
|المحارف السيريلية الخاصة بـنظام التشغيل ويندوز. | |المحارف السيريلية الخاصة بـنظام التشغيل ويندوز. | ||
|- | |- | ||
|cp1252 | |<code>cp1252</code> | ||
|Windows-1252, 1252 | |Windows-1252, 1252 | ||
|المحارف الخاصة بـنظام التشغيل ويندوز لدول أوروبا الغربية. | |المحارف الخاصة بـنظام التشغيل ويندوز لدول أوروبا الغربية. | ||
|- | |- | ||
|KOI8-R | |<code>KOI8-R</code> | ||
|koi8-ru, koi8r | |koi8-ru, koi8r | ||
|الروسية. | |الروسية. | ||
|- | |- | ||
|BIG5 | |<code>BIG5</code> | ||
|950 | |950 | ||
|الصينية التقليدية، تستخدم أساسا في تايوان. | |الصينية التقليدية، تستخدم أساسا في تايوان. | ||
|- | |- | ||
|GB2312 | |<code>GB2312</code> | ||
|936 | |936 | ||
|الصينية المبسطة، مجموعة المحارف الوطنية القياسية. | |الصينية المبسطة، مجموعة المحارف الوطنية القياسية. | ||
|- | |- | ||
|BIG5-HKSCS | |<code>BIG5-HKSCS</code> | ||
|❡ | |❡ | ||
|مجموعة محارف Big5 مع إضافات هونغ كونغ، الصينية التقليدية. | |مجموعة محارف Big5 مع إضافات هونغ كونغ، الصينية التقليدية. | ||
|- | |- | ||
|SHIFT_JIS | |<code>SHIFT_JIS</code> | ||
|SJIS، SJIS-win، cp932، 932 | |SJIS، SJIS-win، cp932، 932 | ||
|اليابانية | |اليابانية | ||
|- | |- | ||
|EUC-JP | |<code>EUC-JP</code> | ||
|EUCJP, eucJP-win | |EUCJP, eucJP-win | ||
|اليابانية | |اليابانية | ||
|- | |- | ||
|MacRoman | |<code>MacRoman</code> | ||
| | | | ||
|مجموعة المحارف التي يستخدمها نظام التشغيل Mac OS. | |مجموعة المحارف التي يستخدمها نظام التشغيل Mac OS. | ||
|- | |- | ||
|<nowiki>''''</nowiki> | |<code><nowiki>''''</nowiki></code> | ||
| | | | ||
|سلسلة نصية فارغة تُشَغِل الكشف عن الترميز من ترميز المحارف المستعمل في ملف السكربت (وذلك عبر Zend multibyte)، أو من قيمة ،default_charset أو المحلية الحالية (راجع nl_langinfo() و setlocale()) بهذا الترتيب، لا يُنصح باستخدام هذه القيمة. | |سلسلة نصية فارغة تُشَغِل الكشف عن الترميز من ترميز المحارف المستعمل في ملف السكربت (وذلك عبر Zend multibyte)، أو من قيمة ،default_charset أو المحلية الحالية (راجع nl_langinfo() و setlocale()) بهذا الترتيب، لا يُنصح باستخدام هذه القيمة. | ||
|} | |} | ||
ملاحظة: لا تُعرَف أي ترميزات محارف أخرى من غير المذكورة أعلاه، يُستخدم الترميز الافتراضي في هذه الحالة مع إرسال تحذير. | |||
=== double_encode === | |||
لا تُرَّمز لغة PHP مدخلات html عند إعطاء القيمة FALSE للمعامل <code>double_encode</code>، الحالة الإفتراضية هي تحويل كل القيم المُدخلة. | |||
لا تُرَّمز لغة PHP مدخلات html عند إعطاء القيمة FALSE للمعامل | |||
== القيم المعادة == | |||
السلسلة النصية المُحولة. | السلسلة النصية المُحولة. | ||
تُعيد الدالة | تُعيد الدالة <code>htmlspecialchars()</code> سلسلة نصية فارغة إذا احتوت السلسلة النصية المُدخلة سلسلة تعليمات برمجية لا تتوافق | ||
مع الترميز الذي يحتويه المعامل encoding إلا إذا كانت قيمة المعامل flags مساوية للراية ENT_IGNORE أو ENT_SUBSTITUTE. | مع الترميز الذي يحتويه المعامل <code>encoding</code> إلا إذا كانت قيمة المعامل <code>flags</code> مساوية للراية <code>ENT_IGNORE</code> أو <code>ENT_SUBSTITUTE</code>. | ||
== سجل التغييرات == | |||
{| class="wikitable" | {| class="wikitable" | ||
!الإصدار | |||
!الوصف | |||
|- | |- | ||
|5.6.0 | |5.6.0 | ||
|أصبحت قيمة المعامل encoding الافتراضية هي قيمة الإعدادات القياسية للمحارف. | |أصبحت قيمة المعامل <code>encoding</code> الافتراضية هي قيمة الإعدادات القياسية للمحارف. | ||
|- | |- | ||
|5.4.0 | |5.4.0 | ||
|تحديد قيمة المعامل encoding الافتراضية بالقيمة UTF-8. | |تحديد قيمة المعامل <code>encoding</code> الافتراضية بالقيمة UTF-8. | ||
|- | |- | ||
|5.4.0 | |5.4.0 | ||
|اُضيفت الثوابت ENT_HTML401 و ENT_XML1 و ENT_XHTML و ENT_HTML5 | |اُضيفت الثوابت <code>ENT_HTML401</code> و <code>ENT_XML1</code> و <code>ENT_XHTML</code> و <code>ENT_HTML5</code> و <code>ENT_SUBSTITUTE</code> و <code>ENT_DISALLOWED</code>. | ||
ENT_SUBSTITUTE و | |||
|- | |- | ||
|5.3.0 | |5.3.0 | ||
|أُضيف الثابت ENT_IGNORE | |أُضيف الثابت <code>ENT_IGNORE</code>. | ||
|- | |- | ||
|5.2.3 | |5.2.3 | ||
|أُضيف المُعامل double_encode للدالة htmlspecialchars() | |أُضيف المُعامل <code>double_encode</code> للدالة <code>htmlspecialchars()</code>. | ||
|} | |} | ||
== أمثلة == | |||
المثال 1: مثال عن الدالة <code>htmlspecialchars()</code><syntaxhighlight lang="php"> | |||
<syntaxhighlight lang="php"> | |||
<?php | <?php | ||
$new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES); | $new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES); | ||
echo $new; // <a href='test'>Test</a> | echo $new; // <a href='test'>Test</a> | ||
?> | ?> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== ملاحظات == | |||
تُحول الدالة htmlspecialchars() المحارف المذكورة أعلاه فقط، لتحويل كل المحارف القابلة للتحويل انظر الدالة htmlentities(). | تُحول الدالة <code>htmlspecialchars()</code> المحارف المذكورة أعلاه فقط، لتحويل كل المحارف القابلة للتحويل انظر الدالة <code>[[PHP/htmlentities|htmlentities()]]</code>. | ||
تُطبق هذه القوانين في حال وقوع التباس في قيمة الرايات | تُطبق هذه القوانين في حال وقوع التباس في قيمة الرايات | ||
* في حال غياب أحد الرايات التالية ENT_COMPAT و ENT_QUOTES و | * في حال غياب أحد الرايات التالية <code>ENT_COMPAT</code> و <code>ENT_QUOTES</code> و <code>ENT_NOQUOTES</code>، تكون <code>ENT_COMPAT</code> هي قيمة الراية الافتراضية. | ||
* في حال تزامن وجود أكثر من من أحد الرايات التالية ENT_COMPAT و ENT_QUOTES | * في حال تزامن وجود أكثر من من أحد الرايات التالية <code>ENT_COMPAT</code> و <code>ENT_QUOTES</code> و <code>ENT_NOQUOTES</code> فتأخذ الراية <code>ENT_QUOTES</code> الأولوية، تتبعها <code>ENT_COMPAT</code>. | ||
* في حال غياب أحد الرايات التالية ENT_HTML401 أو ENT_HTML5 أو ENT_XHTML أو ENT_XML1 تكون الراية ENT_HTML401 هي القيمة الافتراضية. | * في حال غياب أحد الرايات التالية <code>ENT_HTML401</code> أو <code>ENT_HTML5</code> أو <code>ENT_XHTML</code> أو <code>ENT_XML1</code> تكون الراية <code>ENT_HTML401</code> هي القيمة الافتراضية. | ||
* في حال تزامن وجود أكثر من أحد الرايات التالية ENT_HTML401 و ENT_HTML5 و ENT_XHTML و ENT_XML1 تأخذ الراية ENT_HTML5 الأولوية تتبعها ENT_XHTML ثم ENT_HTML401. | * في حال تزامن وجود أكثر من أحد الرايات التالية <code>ENT_HTML401</code> و <code>ENT_HTML5</code> و <code>ENT_XHTML</code> و <code>ENT_XML1</code> تأخذ الراية <code>ENT_HTML5</code> الأولوية تتبعها <code>ENT_XHTML</code> ثم <code>ENT_HTML401</code>. | ||
في حال تزامن وجود أكثر من أحد الرايات التالية <code>ENT_DISALLOWED</code> و <code>ENT_IGNORE</code> و <code>ENT_SUBSTITUTE</code>، فتأخذ الراية <code>ENT_IGNORE</code> الأولوية تتبعها <code>ENT_SUBSTITUTE</code>. | |||
== انظر أيضًا == | |||
* get_html_translation_table(): إعادة الدالة جدول التحويل المستخدم بواسطة | * <code>[[PHP/get html translation table|get_html_translation_table()]]</code>: إعادة الدالة جدول التحويل المستخدم بواسطة الدالتين <code>htmlspecialchars()</code> و <code>[[PHP/htmlentities|htmlentities()]]</code>. | ||
* htmlspecialchars_decode(): إعادة تحويل مدخلات HTML إلى محارف. | * <code>[[PHP/htmlspecialchars decode|htmlspecialchars_decode()]]</code>: إعادة تحويل مدخلات HTML إلى محارف. | ||
* strip_tags(): حذف وسوم لغتي HTML و PHP من سلسلة نصية. | * <code>[[PHP/strip tags|strip_tags()]]</code>: حذف وسوم لغتي HTML و PHP من سلسلة نصية. | ||
* htmlentities(): تحويل المحارف إلى مدخلات HTML. | * <code>[[PHP/htmlentities|htmlentities()]]</code>: تحويل المحارف إلى مدخلات HTML. | ||
* nl2br(): إضافة العنصر <nowiki><br></nowiki> بلغة HTML قبل أي سطر جديد في السلسلة النصية. | * <code>[[PHP/nl2br|nl2br()]]</code>: إضافة العنصر <code>[[HTML/br|<nowiki><br></nowiki>]]</code> بلغة HTML قبل أي سطر جديد في السلسلة النصية. | ||
== مصادر == | |||
* صفحة الدالة htmlspecialchars في توثيق PHP الرسمي. | * [http://php.net/manual/en/function.htmlspecialchars.php صفحة الدالة htmlspecialchars في توثيق PHP الرسمي]. | ||
مراجعة 17:13، 5 أبريل 2018
((PHP 4, PHP 5, PHP 7
تُحول الدالة htmlspecialchars() المحارف الخاصة إلى مدخلات HTML (HTML entities).
الوصف
string htmlspecialchars ( string $string [, int $flags = ENT_COMPAT | ENT_HTML401 [, string $encoding = ini_get("default_charset") [, bool $double_encode = TRUE ]]] )
تحمل بعض المحارف معانٍ خاصة بلغة HTML، إذ يجب تحويلها إلى مدخلات HTM للمحافظة على معانيها ومدلولاتها. تُحول الدالة htmlspecialchars() هذه المحارف إلى مدخلات HTML وتعيدها في سلسلة نصية. استعمل الدالة htmlentities() إذا أردتَ تحويل كل السلاسل النصية القابلة للتحويل إلى مدخلات HTML.
إذا كان ترميز محارف السلسلة النصية المُمرَّرة إلى هذه الدالة وترميز محارف المستند النهائي متماثلين، فإنَّ هذه الدالة كافية لتحويل المحارف الخاصة إلى مدخلات HTML في أغلبية الحالات؛ أما لو لم تكن المحارف التي تريد ترميزها موجودةً في جدول المحارف الخاص بترميز المستند النهائي، وكنتَ تريد الحفاظ على قيم تلك المحارف، فلن تكفيك هذه الدالة ولا الدالة htmlentities()، وعليك حينئذٍ استخدام الدالة mb_encode_numericenity().
جدول التحويلات
| المُحرَّف | البديل |
|---|---|
| & (الواو اللاتينية) | &
|
| " (علامة الإقتباس المزدوجة) | ;quot& إذا كانت الخاصية ENT_NOQUOTES غير مُفَعلة.
|
| ' (علامة الإقتباس المُفرَدة) | ' (في حالة ENT_HTML401) أو ;apos& (في حالة ENT_XML1 أو ENT_XHTML أو ENT_HTML5).إذا كانت الخاصية ENT_NOQUOTES مُفَعلة.
|
| < (علامة أصغر من) | <
|
| > (علامة أكبر من) | >
|
المعاملات
string
السلسلة النصية المُدخَلة المُرَاد تحويلها.
flags
قناع bitmask يتكون من راية أو أكثر من الرايات المبينة في جدول ثوابت الرايات المُتاحة. تُحدد هذه الرايات كيفية التعامل مع علامات الاقتباس وسلاسل التعليمات البرمجية الخاطئة ونوع المُستند المُستعمل. قيمة القناع الإفتراضي هي ENT_COMPAT | ENT_HTML401.
ثوابت الرايات المُتاحة
| الثابت | الوصف |
|---|---|
ENT_COMPAT
|
يحتوي الجدول مدخلات لعلامات الاقتباس المزدوجة دون علامات الاقتباس المفردة |
ENT_QUOTES
|
يحتوي الجدول مدخلات لعلامات الاقتباس المزدوجة وعلامات الاقتباس المفردة |
ENT_NOQUOTES
|
لا يحتوي الجدول على علامات اقتباس، مزدوجةً كانت أو مفردة. |
ENT_IGNORE
|
تَتَجاهل بصمت سلسلة التعليمات البرمجية الخاطئة. لا ننصح باستعمال هذه الراية لما لها قد ينتج عنها من تداعيات أمنية. |
ENT_SUBSTITUTE
|
تَستَبدِل سلاسل التعليمات البرمجية الخاطئة بمحرف الاستبدال في يونيكود ورمزه U+FFFD أو ;xFFFD#&؛ بدلًا من أن تُعيد سلسلة نصية فارغة.
|
ENT_DISALLOWED
|
تَستَبدِل سلاسل التعليمات البرمجية الخاطئة بمحرف الاستبدال في يونيكود ورمزه U+FFFD أو ;xFFFD#&؛ بدلًا من تركها على حالها كما هي. تتجلى فائدة هذه الراية في ضمان حسن صياغة مستندات XML ذات المحتوى الخارجي.
|
ENT_HTML401
|
جدول لمعيار HTML 4.01. |
ENT_XML1
|
جدول لمعيار XML1. |
ENT_XHTM
|
جدول لمعيار XHTML. |
ENT_HTML5
|
جدول لمعيار HTML5. |
encoding
مُعامل إختياري يُحدد الترميز المُستعمل في تحويل المحارف. في حالة عدم إدراجه، فستختلف القيمة القياسية للمعامل encoding بإختلاف نسخة PHP. إذ تَستَعمل النسخة PHP 5.6 وما بعدها قيمة خيار الضبط default_charset وتستعمل النسخ PHP 5.4 و 5.5 PHP الترميز UTF-8 أما نسخ PHP الأقدم فتستخدم ترميز ISO-8859-1.
على الرغم من أنَّ ضبط المعامل encoding في الدالة htmlspecialchars() من الناحية الفنية هو أمرٌ اختياري، إلا أنه من المستحسن ضبط قيمته في حال استعمال نسخة 5.5 PHP أو ما قبلها أو في حال ما كانت قيمة خيار الضبط default_charset غير موافقة للسلسلة النصية المُدخلة. من أجل الدالة htmlspecialchars() جُعلت الترميزات ISO-8859-1 و ISO-8859-15 و UTF-8 و cp866 و cp1251 و cp1252 و KOI8-R متكافئة مع بعضها البعض شرط أن تكون السلسلة النصية المُدخلة صالحة للترميز، حيث تَشغُل الأحرف المُحولة نفس المواضِع في كل الترميزات.
ترميزات المحارف المدعومة
| ترميز المحارف | التسمية | الوصف |
|---|---|---|
ISO8859-1
|
ISO8859-1 | دول أوروبا الغربية، Latin-1. |
ISO8859-5
|
ISO8859-5 | المحارف السيريلية قليلة الاستخدام (اللاتينية أو السيريلية). |
ISO8859-15
|
ISO8859-15 | أوروبا الغربية، Latin-9.
اُضيفت علامة اليورو، والحروف الفرنسية والفنلندية غير الموجودة في ترميز Latin-1 (أي ISO-8859-1). |
UTF-8
|
ترميز ASCII المتوافق مع يونيكود (multi-byte 8-bit Unicode). | |
cp866
|
ibm866,866 | المحارف السيريلية الخاصة بنظام التشغيل دوس (DOS). |
cp1251
|
Windows-1251,win-1251,1251 | المحارف السيريلية الخاصة بـنظام التشغيل ويندوز. |
cp1252
|
Windows-1252, 1252 | المحارف الخاصة بـنظام التشغيل ويندوز لدول أوروبا الغربية. |
KOI8-R
|
koi8-ru, koi8r | الروسية. |
BIG5
|
950 | الصينية التقليدية، تستخدم أساسا في تايوان. |
GB2312
|
936 | الصينية المبسطة، مجموعة المحارف الوطنية القياسية. |
BIG5-HKSCS
|
❡ | مجموعة محارف Big5 مع إضافات هونغ كونغ، الصينية التقليدية. |
SHIFT_JIS
|
SJIS، SJIS-win، cp932، 932 | اليابانية |
EUC-JP
|
EUCJP, eucJP-win | اليابانية |
MacRoman
|
مجموعة المحارف التي يستخدمها نظام التشغيل Mac OS. | |
''''
|
سلسلة نصية فارغة تُشَغِل الكشف عن الترميز من ترميز المحارف المستعمل في ملف السكربت (وذلك عبر Zend multibyte)، أو من قيمة ،default_charset أو المحلية الحالية (راجع nl_langinfo() و setlocale()) بهذا الترتيب، لا يُنصح باستخدام هذه القيمة. |
ملاحظة: لا تُعرَف أي ترميزات محارف أخرى من غير المذكورة أعلاه، يُستخدم الترميز الافتراضي في هذه الحالة مع إرسال تحذير.
double_encode
لا تُرَّمز لغة PHP مدخلات html عند إعطاء القيمة FALSE للمعامل double_encode، الحالة الإفتراضية هي تحويل كل القيم المُدخلة.
القيم المعادة
السلسلة النصية المُحولة.
تُعيد الدالة htmlspecialchars() سلسلة نصية فارغة إذا احتوت السلسلة النصية المُدخلة سلسلة تعليمات برمجية لا تتوافق
مع الترميز الذي يحتويه المعامل encoding إلا إذا كانت قيمة المعامل flags مساوية للراية ENT_IGNORE أو ENT_SUBSTITUTE.
سجل التغييرات
| الإصدار | الوصف |
|---|---|
| 5.6.0 | أصبحت قيمة المعامل encoding الافتراضية هي قيمة الإعدادات القياسية للمحارف.
|
| 5.4.0 | تحديد قيمة المعامل encoding الافتراضية بالقيمة UTF-8.
|
| 5.4.0 | اُضيفت الثوابت ENT_HTML401 و ENT_XML1 و ENT_XHTML و ENT_HTML5 و ENT_SUBSTITUTE و ENT_DISALLOWED.
|
| 5.3.0 | أُضيف الثابت ENT_IGNORE.
|
| 5.2.3 | أُضيف المُعامل double_encode للدالة htmlspecialchars().
|
أمثلة
المثال 1: مثال عن الدالة htmlspecialchars()
<?php
$new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
echo $new; // <a href='test'>Test</a>
?>
ملاحظات
تُحول الدالة htmlspecialchars() المحارف المذكورة أعلاه فقط، لتحويل كل المحارف القابلة للتحويل انظر الدالة htmlentities().
تُطبق هذه القوانين في حال وقوع التباس في قيمة الرايات
- في حال غياب أحد الرايات التالية
ENT_COMPATوENT_QUOTESوENT_NOQUOTES، تكونENT_COMPATهي قيمة الراية الافتراضية. - في حال تزامن وجود أكثر من من أحد الرايات التالية
ENT_COMPATوENT_QUOTESوENT_NOQUOTESفتأخذ الرايةENT_QUOTESالأولوية، تتبعهاENT_COMPAT. - في حال غياب أحد الرايات التالية
ENT_HTML401أوENT_HTML5أوENT_XHTMLأوENT_XML1تكون الرايةENT_HTML401هي القيمة الافتراضية. - في حال تزامن وجود أكثر من أحد الرايات التالية
ENT_HTML401وENT_HTML5وENT_XHTMLوENT_XML1تأخذ الرايةENT_HTML5الأولوية تتبعهاENT_XHTMLثمENT_HTML401.
في حال تزامن وجود أكثر من أحد الرايات التالية ENT_DISALLOWED و ENT_IGNORE و ENT_SUBSTITUTE، فتأخذ الراية ENT_IGNORE الأولوية تتبعها ENT_SUBSTITUTE.
انظر أيضًا
get_html_translation_table(): إعادة الدالة جدول التحويل المستخدم بواسطة الدالتينhtmlspecialchars()وhtmlentities().htmlspecialchars_decode(): إعادة تحويل مدخلات HTML إلى محارف.strip_tags(): حذف وسوم لغتي HTML و PHP من سلسلة نصية.htmlentities(): تحويل المحارف إلى مدخلات HTML.nl2br(): إضافة العنصر<br>بلغة HTML قبل أي سطر جديد في السلسلة النصية.