_wp_specialchars()
云策文档标注
概述
_wp_specialchars() 是 WordPress 核心函数，用于将特殊字符转换为 HTML 实体，主要处理 &、<、>、" 和 '。它支持多种引号编码模式，并允许控制字符编码和现有实体的双重编码。
关键要点
- 函数将 &、<、>、" 和 ' 等特殊字符转换为 HTML 实体，以防止 XSS 攻击和确保输出安全。
- 参数 $quote_style 控制引号编码：ENT_NOQUOTES（默认，不编码引号）、ENT_COMPAT（编码双引号）、ENT_QUOTES（编码单双引号）、ENT_XML1（编码引号并转换 HTML 命名实体），也兼容旧值 'single' 和 'double'。
- 参数 $charset 指定字符编码，默认使用博客设置；$double_encode 控制是否对现有 HTML 实体进行双重编码，默认 false。
- 函数内部优化：如果文本中无特殊字符，直接返回原文本以提高性能。
- 相关函数包括 esc_html()、esc_attr() 等，用于不同场景的转义；在 WordPress 5.5.0 中增加了对 ENT_XML1 的支持。
代码示例
function wpdocs_esc_json( $json, $html = false ) {
return _wp_specialchars(
$json,
$html ? ENT_NOQUOTES : ENT_QUOTES, // 仅在属性节点中转义引号
'UTF-8', // json_encode() 输出 UTF-8
true // 双重编码实体
);
}注意事项
- 使用前需确保字符编码设置正确，以避免乱码问题。
- 在需要输出到 HTML 或属性时，根据场景选择合适的 $quote_style 值。
- 函数已弃用 wp_specialchars()，建议使用更具体的转义函数如 esc_html()。
原文内容
Converts a number of special characters into their HTML entities.
Description
Specifically deals with: &, <, >, ", and '.
$quote_style can be set to ENT_COMPAT to encode " to ", or ENT_QUOTES to do both. Default is ENT_NOQUOTES where no quotes are encoded.
Parameters
$textstringrequired-
The text which is to be encoded.
$quote_styleint|stringoptional-
Converts double quotes if set to ENT_COMPAT, both single and double if set to ENT_QUOTES or none if set to ENT_NOQUOTES.
Converts single and double quotes, as well as converting HTML named entities (that are not also XML named entities) to their code points if set to ENT_XML1. Also compatible with old values; converting single quotes if set to'single', double if set to'double'or both if otherwise set.
Default is ENT_NOQUOTES.Default:
ENT_NOQUOTES $charsetfalse|stringoptional-
The character encoding of the string.
Default:
false $double_encodebooloptional-
Whether to encode existing HTML entities.
Default:
false
Source
function _wp_specialchars( $text, $quote_style = ENT_NOQUOTES, $charset = false, $double_encode = false ) {
$text = (string) $text;
if ( 0 === strlen( $text ) ) {
return '';
}
// Don't bother if there are no specialchars - saves some processing.
if ( ! preg_match( '/[&<>"']/', $text ) ) {
return $text;
}
// Account for the previous behavior of the function when the $quote_style is not an accepted value.
if ( empty( $quote_style ) ) {
$quote_style = ENT_NOQUOTES;
} elseif ( ENT_XML1 === $quote_style ) {
$quote_style = ENT_QUOTES | ENT_XML1;
} elseif ( ! in_array( $quote_style, array( ENT_NOQUOTES, ENT_COMPAT, ENT_QUOTES, 'single', 'double' ), true ) ) {
$quote_style = ENT_QUOTES;
}
$charset = _canonical_charset( $charset ? $charset : get_option( 'blog_charset' ) );
$_quote_style = $quote_style;
if ( 'double' === $quote_style ) {
$quote_style = ENT_COMPAT;
$_quote_style = ENT_COMPAT;
} elseif ( 'single' === $quote_style ) {
$quote_style = ENT_NOQUOTES;
}
if ( ! $double_encode ) {
/*
* Guarantee every &entity; is valid, convert &garbage; into &garbage;
* This is required for PHP < 5.4.0 because ENT_HTML401 flag is unavailable.
*/
$text = wp_kses_normalize_entities( $text, ( $quote_style & ENT_XML1 ) ? 'xml' : 'html' );
}
$text = htmlspecialchars( $text, $quote_style, $charset, $double_encode );
// Back-compat.
if ( 'single' === $_quote_style ) {
$text = str_replace( "'", ''', $text );
}
return $text;
}
Skip to note 2 content
Mahdi Yazdani
Escape JSON for use on HTML or attribute text nodes.
/** * Escape JSON for use on HTML or attribute text nodes. * * @param string $json JSON to escape. * @param bool $html True if escaping for HTML text node, false for attributes. Determines how quotes are handled. * @return string Escaped JSON. */ function wpdocs_esc_json( $json, $html = false ) { return _wp_specialchars( $json, $html ? ENT_NOQUOTES : ENT_QUOTES, // Escape quotes in attribute nodes only. 'UTF-8', // json_encode() outputs UTF-8 (really just ASCII), not the blog's charset. true // Double escape entities: `&` -> `&`. ); }