توابع PHP htmlspecialchars()

توابع String PHP

مثال

کاراکترهای پیش‌تعریف شده "<" (کوچکتر از) و ">" (بزرگتر از) به HTML entity تبدیل می‌شوند:

<?php
$str = "این یک متن <b>سبک</b> است.";
echo htmlspecialchars($str);
?>

خروجی HTML کد بالا به شرح زیر است (منبع کد را مشاهده کنید):

<!DOCTYPE html>
<html>
<body>
این یک متن <b>سبک</b> است.
</body>
</html>

خروجی مرورگر کد بالا به شرح زیر است:

این یک متن <b>سبک</b> است.

اجرای نمونه

تعریف و نحوه استفاده

تابع htmlspecialchars() کاراکترهای پیش‌تعریف شده را به HTML entity تبدیل می‌کند.

کاراکترهای پیش‌تعریف شده:

  • & (و) به & تبدیل می‌شود
  • " (نقل قول بزرگ) به " تبدیل می‌شود
  • ' (نقل قول کوچک) به ' تبدیل می‌شود
  • < (کوچکتر از) به < تبدیل می‌شود
  • > (بزرگتر از) به > تبدیل می‌شود

توضیحات:برای تبدیل HTML entity‌های خاص به کاراکترها از htmlspecialchars_decode() تابع.

نحوه استفاده

htmlspecialchars(string,flags,character-set,double_encode)
پارامترها توضیح
string ضروری. تعیین می‌کند رشته‌ای که باید تبدیل شود.
flags

اختیاری. تعیین می‌کند چگونه نقل قول‌ها، کدهای غیرمجاز و نوع مستند استفاده می‌شوند.

نوع‌های نقل قول موجود:

  • ENT_COMPAT - پیش‌فرض. تنها نقل قول‌های دوگانه کدگذاری می‌شوند.
  • ENT_QUOTES - نقل قول‌های دوگانه و یکگانه کدگذاری می‌شوند.
  • ENT_NOQUOTES - هیچ نقل قولی کدگذاری نمی‌شود.

کدهای غیرمجاز:

  • ENT_IGNORE - کدهای غیرمجاز نادیده گرفته می‌شوند، به جای بازگشت یک رشته خالی. باید از آن اجتناب کرد، زیرا ممکن است تأثیرات امنیتی داشته باشد.
  • ENT_SUBSTITUTE - کدهای غیرمجاز با یک کاراکتر مشخص شده با کاراکتر جایگزین Unicode U+FFFD (UTF-8) یا &#FFFD; جایگزین می‌شود، به جای بازگشت یک رشته خالی.
  • ENT_DISALLOWED - با جایگزینی نقطه‌های غیرمجاز در نوع مستند مشخص شده، کاراکتر جایگزین Unicode U+FFFD (UTF-8) یا &#FFFD; استفاده می‌شود.

flags اضافی برای تعیین نوع مستند استفاده شده:

  • ENT_HTML401 - پیش‌فرض. به عنوان HTML 4.01 پردازش می‌شود
  • ENT_HTML5 - به عنوان HTML 5 پردازش می‌شود
  • ENT_XML1 - به عنوان XML 1 پردازش می‌شود
  • ENT_XHTML - به عنوان XHTML پردازش می‌شود
character-set

اختیاری. یک توالی که یک مجموعه نمادهای مشخص شده برای استفاده را تعیین می‌کند

مقدار مجاز:

  • UTF-8 - پیش‌فرض. ASCII با سازگاری چندبیت 8 بیتی Unicode
  • ISO-8859-1 - اروپایی
  • ISO-8859-15 - اروپایی (با افزودن نمادهای اروپایی + الفبای فرانسوی و فنلاندی گم شده در ISO-8859-1)
  • cp866 - مجموعه نمادهای Cyrillic اختصاصی DOS
  • cp1251 - مجموعه نمادهای Cyrillic اختصاصی ویندوز
  • cp1252 - مجموعه نمادهای اروپایی اختصاصی ویندوز
  • KOI8-R - روسی
  • BIG5 - چینی پیچیده، اصلی در تایوان استفاده می‌شود
  • GB2312 - چینی ساده، مجموعه نمادهای ملی
  • BIG5-HKSCS - BIG5 با گسترش هنگ کنگ
  • Shift_JIS - ژاپنی
  • EUC-JP - ژاپنی
  • MacRoman - مجموعه نمادهای سیستم عامل Mac

نکته:در نسخه‌های PHP قبل از 5.4، مجموعه‌های نمادهای غیرقابل شناسایی نادیده گرفته می‌شوند و توسط ISO-8859-1 جایگزین می‌شوند. از PHP 5.4 به بعد، مجموعه‌های نمادهای غیرقابل شناسایی نادیده گرفته می‌شوند و توسط UTF-8 جایگزین می‌شوند
double_encode

اختیاری. یک مقدار بولین که مشخص می‌کند آیا HTML entity موجود کدگذاری شود یا خیر

  • TRUE - پیش‌فرض. برای هر entity تبدیل انجام می‌شود
  • FALSE - کدگذاری HTML entity موجود انجام نمی‌شود

جزئیات فنی

مقدار بازگشتی:

توالی تبدیل شده را بازمی‌گردانند

اگر string در صورت شامل بودن کدگذاری نامعتبر، یک توالی خالی بازمی‌گردانند، مگر اینکه ENT_IGNORE یا ENT_SUBSTITUTE قرار داده شوند
نسخه PHP: 4+
گزارش به‌روزرسانی:

در PHP 5،character-set مقدار پیش‌فرض پارامتر به UTF-8 تغییر یافت

در PHP 5.4، ENT_SUBSTITUTE، ENT_DISALLOWED، ENT_HTML401، ENT_HTML5، ENT_XML1 و ENT_XHTML اضافه شدند

در PHP 5.3، ENT_IGNORE اضافه شد

در PHP 5.2.3، بهبودهای جدید اضافه شدند double_encode پارامترها.

در PHP 4.1، بهبودهای جدید اضافه شد character-set پارامترها.

مثال‌های بیشتر

مثال 1

بعضی از کاراکترهای پیش‌تعریف شده را به نمادهای HTML تبدیل کنید:

<?php
$str = "Bill & 'Steve'";
echo htmlspecialchars($str, ENT_COMPAT); // فقط نقل قول‌های دوگانه تبدیل می‌شود
echo "<br>";
echo htmlspecialchars($str, ENT_QUOTES);// تبدیل نقل قول‌های دوگانه و یکگانه
echo "<br>";
echo htmlspecialchars($str, ENT_NOQUOTES); // هیچ نقل قولی تبدیل نمی‌شود
?>

خروجی HTML کد بالا به شرح زیر است (منبع کد را مشاهده کنید):

<!DOCTYPE html>
<html>
<body>
Bill & 'Steve'<br>
Bill & 'Steve'<br>
Bill & 'Steve'
</body>
</html>

خروجی مرورگر کد بالا به شرح زیر است:

Bill & 'Steve'
Bill & 'Steve'
Bill & 'Steve'

اجرای نمونه

مثال 2

نقل قول‌های دوگانه را به نمادهای HTML تبدیل کنید:

<?php
$str = 'I love "PHP".';
echo htmlspecialchars($str, ENT_QUOTES); // تبدیل نقل قول‌های دوگانه و یکگانه
?>

خروجی HTML کد بالا به شرح زیر است (منبع کد را مشاهده کنید):

<!DOCTYPE html>
<html>
<body>
من عاشق "PHP" هستم.
</body>
</html>

خروجی مرورگر کد بالا به شرح زیر است:

من عاشق "PHP" هستم.

اجرای نمونه

توابع String PHP