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

من موسوعة حسوب
< PHP
→ التعديل السابق
مرئينص الويكي
لا ملخص تعديل
لا ملخص تعديل
 
(مراجعتان متوسطتان بواسطة مستخدمين اثنين آخرين غير معروضتين)
سطر 1: سطر 1:
<noinclude>{{DISPLAYTITLE:الدالة htmlspecialchars()‎ في PHP}}</noinclude>
<noinclude>{{DISPLAYTITLE:الدالة <code>htmlspecialchars()‎</code> في PHP}}</noinclude>
(‎(PHP 4, PHP 5, PHP 7
(‎(PHP 4, PHP 5, PHP 7


تُحول الدالة ‎htmlspecialchars()‎ المحارف الخاصة إلى مدخلات HTML‏ (HTML entities).
تُحول الدالة ‎<code>htmlspecialchars()</code>‎ المحارف الخاصة إلى مدخلات HTML‏ (HTML entities).


=== الوصف ===
== الوصف ==
<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
‎string htmlspecialchars ( string $string [, int $flags = ENT_COMPAT | ENT_HTML401 [, string  
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.


$encoding = ini_get("default_charset") [, bool $double_encode = TRUE ]]] )
إذا كان ترميز محارف السلسلة النصية المُمرَّرة إلى هذه الدالة وترميز محارف المستند النهائي متماثلين، فإنَّ هذه الدالة كافية لتحويل المحارف الخاصة إلى مدخلات HTML في أغلبية الحالات؛ أما لو لم تكن المحارف التي تريد ترميزها موجودةً في جدول المحارف الخاص بترميز المستند النهائي، وكنتَ تريد الحفاظ على قيم تلك المحارف، فلن تكفيك هذه الدالة ولا الدالة <code>[[PHP/htmlentities|htmlentities()‎]]</code>، وعليك حينئذٍ استخدام الدالة <code>[[PHP/mb encode numericenity|mb_encode_numericenity()‎]]</code>.


 
=== جدول التحويلات ===
</syntaxhighlight> تحمل بعض المحارف معانٍ خاصة بلغة HTML، إذ يجب تحويلها إلى مدخلات HTM للمحافظة على معانيها ومدلولاتها. تُحول الدالة ‎htmlspecialchars()‎ هذه المحارف إلى مدخلات HTML وتعيدها في سلسلة نصية. استعمل الدالة htmlentities()‎ إذا أردتَ تحويل كل السلاسل النصية القابلة للتحويل إلى مدخلات HTML.
 
إذا كان ترميز محارف السلسلة النصية المُمرَّرة إلى هذه الدالة وترميز محارف المستند النهائي متماثلين، فإنَّ هذه الدالة كافية لتحويل المحارف الخاصة إلى مدخلات HTML في أغلبية الحالات؛ أما لو لم تكن المحارف التي تريد ترميزها موجودةً في جدول المحارف الخاص بترميز المستند النهائي، وكنتَ تريد الحفاظ على قيم تلك المحارف، فلن تكفيك هذه الدالة ولا الدالة htmlentities()‎، وعليك حينئذٍ استخدام الدالة mb_encode_numericenity()‎.
 
==== جدول التحويلات ====
{| class="wikitable"
{| class="wikitable"
|المُحرَّف
!المُحرَّف
|البديل
!البديل
|-
|-
|& (الواو اللاتينية)
|& (الواو اللاتينية)
|&amp;amp;
|<code>‎&amp;amp;‎</code>
|-
|-
|" (علامة الإقتباس المزدوجة)
|" (علامة الإقتباس المزدوجة)
|;quot& إذا كانت الخاصية ENT_NOQUOTES غيرمُفَعلة.
|<code>;quot&</code> إذا كانت الخاصية <code>ENT_NOQUOTES</code> غير مُفَعلة.
|-
|-
|' (علامة الإقتباس المُفرَدة)
|' (علامة الإقتباس المُفرَدة)
|‎&amp;#039;‎ (في حالة ENT_HTML401) أو ;apos& (في حالة ENT_XML1 أو ENT_XHTML أو ENT_HTML5).إذا كانت الخاصية ENT_NOQUOTES مُفَعلة.
|‎<code>&amp;#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> مُفَعلة.
|-
|-
|‎< (علامة أصغر من)
|‎< (علامة أصغر من)
|&amp;lt;
|‎<code>&amp;lt;‎</code>
|-
|-
|> (علامة أكبر من)
|> (علامة أكبر من)
|&amp;gt;
|<code>‎&amp;gt;‎</code>
|}
|}


=== المعاملات ===
== المعاملات ==


==== string ====
=== <code>string</code> ===
السلسلة النصية المُدخَلة المُرَاد تحويلها.
السلسلة النصية المُدخَلة المُرَاد تحويلها.


==== flags ====
=== <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>
|تَتَجاهل بصمت سلسلة التعليمات البرمجية الخاطئة. لا ننصح بhستعمال هذه الراية لما لها قد ينتج عنها من تداعيات أمنية.
|تَتَجاهل بصمت سلسلة التعليمات البرمجية الخاطئة. لا ننصح باستعمال هذه الراية لما لها قد ينتج عنها من تداعيات أمنية.
|-
|-
|ENT_SUBSTITUTE
|<code>ENT_SUBSTITUTE</code>
|تَستَبدِل سلاسل التعليمات البرمجية الخاطئة بمحرف الاستبدال في يونيكود ورمزه  U+FFFD أو ;xFFFD#&؛ بدلًا من أن تُعيد سلسلة نصية فارغة.
|تَستَبدِل سلاسل التعليمات البرمجية الخاطئة بمحرف الاستبدال في يونيكود ورمزه  <code>U+FFFD</code> أو <code>;xFFFD#&</code>؛ بدلًا من أن تُعيد سلسلة نصية فارغة.
|-
|-
|ENT_DISALLOWED
|<code>ENT_DISALLOWED</code>
|تَستَبدِل سلاسل التعليمات البرمجية الخاطئة بمحرف الاستبدال في يونيكود ورمزه  U+FFFD أو ;xFFFD#&؛ بدلًا من تركها على حالها كما هي. تتجلى فائدة هذه الراية  في ضمان حسن صياغة مستندات XML ذات المحتوى الخارجي.
|تَستَبدِل سلاسل التعليمات البرمجية الخاطئة بمحرف الاستبدال في يونيكود ورمزه <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 ===
مُعامل إختياري يُحدد الترميز المُستعمل في تحويل المحارف. في حالة عدم إدراجه، فستختلف القيمة القياسية للمعامل 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>، الحالة الإفتراضية هي تحويل كل القيم المُدخلة.
==== double_encode ====
لا تُرَّمز لغة PHP مدخلات html عند إعطاء القيمة FALSE للمعامل double_encode، الحالة الإفتراضية هي تحويل كل القيم المُدخلة.


=== القيم المعادة ===
== القيم المعادة ==
السلسلة النصية المُحولة.
السلسلة النصية المُحولة.


تُعيد الدالة ‎htmlspecialchars()‎ سلسلة نصية فارغة إذا احتوت السلسلة النصية المُدخلة سلسلة تعليمات برمجية لا تتوافق
تُعيد الدالة ‎<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 و ENT_DISALLOWEDو
|-
|-
|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">
=== المثال 1: مثال عن الدالة htmlspecialchars()‎ ===
<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; // &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;
echo $new; // &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;
?>
?>
</syntaxhighlight>
</syntaxhighlight>


=== ملاحظات ===
== ملاحظات ==
تُحول الدالة htmlspecialchars() المحارف المذكورة أعلاه فقط، لتحويل كل المحارف القابلة للتحويل انظر الدالة htmlentities()‎.
تُحول الدالة <code>htmlspecialchars()‎</code> المحارف المذكورة أعلاه فقط، لتحويل كل المحارف القابلة للتحويل انظر الدالة <code>[[PHP/htmlentities|htmlentities()‎]]</code>.


تُطبق هذه القوانين في حال وقوع التباس في قيمة الرايات
تُطبق هذه القوانين في حال وقوع التباس في قيمة الرايات
* في حال غياب أحد الرايات التالية ENT_COMPAT و ENT_QUOTES و ENT_NOQUOTES، تكون ENT_COMPAT هي قيمة  الراية الافتراضية.
* في حال غياب أحد الرايات التالية <code>ENT_COMPAT</code> و <code>ENT_QUOTES</code> و <code>ENT_NOQUOTES</code>، تكون <code>ENT_COMPAT</code> هي قيمة  الراية الافتراضية.
* في حال تزامن وجود أكثر من من أحد الرايات التالية ENT_COMPAT و ENT_QUOTES ،ENT_NOQUOTES فتأخذ الراية ENT_QUOTES الأولوية، تتبعها ENT_COMPAT.
* في حال تزامن وجود أكثر من من أحد الرايات التالية <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>.
* في حال تزامن وجود أكثر من أحد الرايات التالية ENT_DISALLOWED و ENT_IGNORE وENT_SUBSTITUTE، فتأخذ الراية ENT_IGNORE الأولوية تتبعها ENT_SUBSTITUTE.
في حال تزامن وجود أكثر من أحد الرايات التالية <code>ENT_DISALLOWED</code> و <code>ENT_IGNORE</code> و <code>ENT_SUBSTITUTE</code>، فتأخذ الراية <code>ENT_IGNORE</code> الأولوية تتبعها <code>ENT_SUBSTITUTE</code>.


=== انظر أيضًا ===
== انظر أيضًا ==
* get_html_translation_table()‎: إعادة الدالة جدول التحويل المستخدم بواسطة الدالتينhtmlspecialchars‎()‎ و htmlentities‎()‎.
* <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 الرسمي].
[[تصنيف:PHP]]
[[تصنيف:PHP Function]]
[[تصنيف:PHP String]]

المراجعة الحالية بتاريخ 17:15، 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 تَتَجاهل بصمت سلسلة التعليمات البرمجية الخاطئة. لا ننصح باستعمال هذه الراية لما لها قد ينتج عنها من تداعيات أمنية.
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.

انظر أيضًا

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=PHP/htmlspecialchars&oldid=5780»