الفرق بين المراجعتين لصفحة: «PHP/htmlspecialchars»

من موسوعة حسوب
< PHP
→ التعديل السابقالتعديل اللاحق ←
مرئينص الويكي
لا ملخص تعديل
لا ملخص تعديل
سطر 80: سطر 80:
|}
|}


=== encoding ===
==== encoding ====
مُعامل إختياري يُحدد الترميز المُستعمل في تحويل المحارف. في حالة عدم إدراجه، فستختلف القيمة القياسية للمعامل encoding بإختلاف نسخة PHP. إذ تَستَعمل النسخة PHP 5.6 وما بعدها قيمة خيار الضبط default_charset وتستعمل النسخ PHP 5.4 و 5.5 PHP الترميز UTF-8 أما نسخ PHP الأقدم فتستخدم ترميز ISO-8859-1.
مُعامل إختياري يُحدد الترميز المُستعمل في تحويل المحارف. في حالة عدم إدراجه، فستختلف القيمة القياسية للمعامل encoding بإختلاف نسخة PHP. إذ تَستَعمل النسخة PHP 5.6 وما بعدها قيمة خيار الضبط default_charset وتستعمل النسخ PHP 5.4 و 5.5 PHP الترميز UTF-8 أما نسخ PHP الأقدم فتستخدم ترميز ISO-8859-1.


مراجعة 13:37، 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()‎.

جدول التحويلات

المُحرَّف البديل
& (الواو اللاتينية) &amp;
" (علامة الإقتباس المزدوجة) ;quot& إذا كانت الخاصية ENT_NOQUOTES غيرمُفَعلة.
' (علامة الإقتباس المُفرَدة) ‎&#039;‎ (في حالة ENT_HTML401) أو ;apos& (في حالة ENT_XML1 أو ENT_XHTML أو ENT_HTML5).إذا كانت الخاصية ENT_NOQUOTES مُفَعلة.
‎< (علامة أصغر من) &lt;
> (علامة أكبر من) &gt;

المعاملات

string

السلسلة النصية المُدخَلة المُرَاد تحويلها.

flags

قناع bitmask يتكون من راية أو أكثر من الرايات المبينة في جدول ثوابت الرايات المُتاحة. تُحدد هذه الرايات كيفية التعامل مع علامات الاقتباس وسلاسل التعليمات البرمجية الخاطئة ونوع المُستند المُستعمل. قيمة القناع الإفتراضي هي ENT_COMPAT | ENT_HTML401.

ثوابت الرايات المُتاحة
الثابت الوصف
ENT_COMPAT يحتوي الجدول مدخلات لعلامات الاقتباس المزدوجة دون علامات الاقتباس المفردة
ENT_QUOTES يحتوي الجدول مدخلات لعلامات الاقتباس المزدوجة وعلامات الاقتباس المفردة
ENT_NOQUOTES لا يحتوي الجدول على علامات اقتباس، مزدوجةً كانت أو مفردة.
ENT_IGNORE تَتَجاهل بصمت سلسلة التعليمات البرمجية الخاطئة. لا ننصح بhستعمال هذه الراية لما لها قد ينتج عنها من تداعيات أمنية.
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; // &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;

?>

ملاحظات

تُحول الدالة 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 قبل أي سطر جديد في السلسلة النصية.

مصادر

  • صفحة الدالة htmlspecialchars في توثيق PHP الرسمي.
مجلوبة من «https://wiki.hsoub.com/index.php?title=PHP/htmlspecialchars&oldid=5719»