الدالة htmlspecialchars() في PHP
((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 قبل أي سطر جديد في السلسلة النصية.