htmlspecialchars

(PHP 4, PHP 5, PHP 7, PHP 8)

htmlspecialchars — 將特殊字符轉(zhuǎn)換為 HTML 實(shí)體

說(shuō)明

htmlspecialchars(
    string $string,
    int $flags = ENT_COMPAT | ENT_HTML401,
    string $encoding = ini_get("default_charset"),
    bool $double_encode = true
): string

某類字符在 HTML 中有特殊用處，如需保持原意，需要用 HTML 實(shí)體來(lái)表達(dá)。 本函數(shù)會(huì)返回字符轉(zhuǎn)義后的表達(dá)。 如需轉(zhuǎn)換子字符串中所有關(guān)聯(lián)的名稱實(shí)體，使用 htmlentities() 代替本函數(shù)。

如果傳入字符的字符編碼和最終的文檔是一致的，則用函數(shù)處理的輸入適合絕大多數(shù) HTML 文檔環(huán)境。 然而，如果輸入的字符編碼和最終包含字符的文檔是不一樣的， 想要保留字符（以數(shù)字或名稱實(shí)體的形式），本函數(shù)以及 htmlentities() （僅編碼名稱實(shí)體對(duì)應(yīng)的子字符串）可能不夠用。 這種情況可以使用 mb_encode_numericentity() 代替。

執(zhí)行轉(zhuǎn)換
字符 替換后
& (& 符號(hào)) &
" (雙引號(hào)) "，除非設(shè)置了 ENT_NOQUOTES
' (單引號(hào)) 設(shè)置了 ENT_QUOTES 后， ' (如果是 ENT_HTML401) ，或者 ' (如果是 ENT_XML1、 ENT_XHTML 或 ENT_HTML5)。
< (小于) &lt;
> (大于) &gt;

參數(shù)

string

待轉(zhuǎn)換的 string。

flags

位掩碼，由以下某個(gè)或多個(gè)標(biāo)記組成，設(shè)置轉(zhuǎn)義處理細(xì)節(jié)、無(wú)效單元序列、文檔類型。 默認(rèn)是 ENT_COMPAT | ENT_HTML401。

有效的 flags 常量
常量名稱 描述
ENT_COMPAT 會(huì)轉(zhuǎn)換雙引號(hào)，不轉(zhuǎn)換單引號(hào)。
ENT_QUOTES 既轉(zhuǎn)換雙引號(hào)也轉(zhuǎn)換單引號(hào)。
ENT_NOQUOTES 單/雙引號(hào)都不轉(zhuǎn)換
ENT_IGNORE 靜默丟棄無(wú)效的代碼單元序列，而不是返回空字符串。 不建議使用此標(biāo)記， 因?yàn)樗?a class="link external" >? 可能有安全影響。
ENT_SUBSTITUTE 替換無(wú)效的代碼單元序列為 Unicode 代替符（Replacement Character）， U+FFFD (UTF-8) 或者 &#xFFFD; (其他)，而不是返回空字符串。
ENT_DISALLOWED 為文檔的無(wú)效代碼點(diǎn)替換為 Unicode 代替符（Replacement Character）： U+FFFD (UTF-8)，或 &#xFFFD;（其他），而不是把它們留在原處。 比如以下情況下就很有用：要保證 XML 文檔嵌入額外內(nèi)容時(shí)格式合法。
ENT_HTML401 以 HTML 4.01 處理代碼。
ENT_XML1 以 XML 1 處理代碼。
ENT_XHTML 以 XHTML 處理代碼。
ENT_HTML5 以 HTML 5 處理代碼。

encoding

An optional argument defining the encoding used when converting characters.

If omitted, encoding defaults to the value of the default_charset configuration option.

Although this argument is technically optional, you are highly encouraged to specify the correct value for your code if the default_charset configuration option may be set incorrectly for the given input.

本函數(shù)使用效果上，如果 string 對(duì)以下字符編碼是有效的， ISO-8859-1、 ISO-8859-15、 UTF-8、 cp866、 cp1251、 cp1252、 KOI8-R 將具有相同的效果。 也就是說(shuō)，在這些編碼里， 受 htmlspecialchars() 影響的字符會(huì)占據(jù)相同的位置。

支持以下字符集：

支持的字符集列表
字符集 別名 描述
ISO-8859-1 ISO8859-1 西歐，Latin-1
ISO-8859-5 ISO8859-5 Little used cyrillic charset (Latin/Cyrillic).
ISO-8859-15 ISO8859-15 西歐，Latin-9。增加歐元符號(hào)，法語(yǔ)和芬蘭語(yǔ)字母在 Latin-1(ISO-8859-1) 中缺失。
UTF-8   ASCII 兼容的多字節(jié) 8 位 Unicode。
cp866 ibm866, 866 DOS 特有的西里爾編碼。本字符集在 4.3.2 版本中得到支持。
cp1251 Windows-1251, win-1251, 1251 Windows 特有的西里爾編碼。本字符集在 4.3.2 版本中得到支持。
cp1252 Windows-1252, 1252 Windows 特有的西歐編碼。
KOI8-R koi8-ru, koi8r 俄語(yǔ)。本字符集在 4.3.2 版本中得到支持。
BIG5 950 繁體中文，主要用于中國(guó)臺(tái)灣省。
GB2312 936 簡(jiǎn)體中文，中國(guó)國(guó)家標(biāo)準(zhǔn)字符集。
BIG5-HKSCS   繁體中文，附帶香港擴(kuò)展的 Big5 字符集。
Shift_JIS SJIS, 932 日語(yǔ)
EUC-JP EUCJP 日語(yǔ)
MacRoman   Mac OS 使用的字符串。
''   An empty string activates detection from script encoding (Zend multibyte), default_charset and current locale (see nl_langinfo() and setlocale()), in this order. Not recommended.

注意: 其他字符集沒(méi)有認(rèn)可。將會(huì)使用默認(rèn)編碼并拋出異常。

double_encode

關(guān)閉 double_encode 時(shí)，PHP 不會(huì)轉(zhuǎn)換現(xiàn)有的 HTML 實(shí)體， 默認(rèn)是全部轉(zhuǎn)換。

返回值

轉(zhuǎn)換后的 string。

如果指定的編碼 encoding 里， string 包含了無(wú)效的代碼單元序列， 沒(méi)有設(shè)置 ENT_IGNORE 或者 ENT_SUBSTITUTE 標(biāo)記的情況下，會(huì)返回空字符串。

更新日志

版本 說(shuō)明
5.6.0 The default value for the encoding parameter was changed to be the value of the default_charset configuration option.
5.4.0 encoding 參數(shù)的默認(rèn)值改成 UTF-8。
5.4.0 增加常量 ENT_SUBSTITUTE、 ENT_DISALLOWED、 ENT_HTML401、 ENT_XML1、 ENT_XHTML、 ENT_HTML5。
5.3.0 增加常量 ENT_IGNORE。
5.2.3 增加參數(shù) double_encode。

范例

示例 #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;
?>

注釋

注意:

注意，本函數(shù)不會(huì)轉(zhuǎn)換以上列表以外的實(shí)體。 完整轉(zhuǎn)換請(qǐng)參見(jiàn) htmlentities()。

注意:

如果 flags 的設(shè)置模糊易混淆，將遵循以下規(guī)則：

  • 當(dāng) ENT_COMPAT、ENT_QUOTES、ENT_NOQUOTES 都沒(méi)設(shè)置， 默認(rèn)就是 ENT_NOQUOTES。
  • 如果設(shè)置不止一個(gè) ENT_COMPAT、 ENT_QUOTES、 ENT_NOQUOTES ，優(yōu)先級(jí)最高的是 ENT_QUOTES， 其次是 ENT_COMPAT。
  • 當(dāng) ENT_HTML401、 ENT_HTML5、 ENT_XHTML、 ENT_XML1 都沒(méi)設(shè)置，默認(rèn)是 ENT_HTML401。
  • 如果設(shè)置不止一個(gè) ENT_HTML401、 ENT_HTML5、 ENT_XHTML、 ENT_XML1， 優(yōu)先級(jí)最高的是 ENT_HTML5 其次是 ENT_XHTML、ENT_XML1 和 ENT_HTML401。
  • 如果設(shè)置不止一個(gè) ENT_DISALLOWED、 ENT_IGNORE、 ENT_SUBSTITUTE，優(yōu)先級(jí)最高的是 ENT_IGNORE， 其次是 ENT_SUBSTITUTE。

參見(jiàn)