转义输出是通过去除不需要的数据（如格式错误的 HTML 或脚本标记）来保护输出数据的过程。此过程有助于在为最终用户呈现数据之前保护数据。

注意：大多数WordPress函数可以正确准备输出数据，并且不需要额外的转义。
 

转义函数

WordPress有许多帮助程序函数，可用于最常见的场景。

密切注意每个函数的作用，因为有些函数会删除 HTML，而另一些函数会允许它。您必须对要回显的内容和上下文使用最合适的函数。你总是想在回声时逃离，而不是在回声之前。

  • esc_html()– 每当 HTML 元素包含要显示的数据部分时，请使用。这将删除 HTML。
<h4><?php echo esc_html( $title ); ?></h4>
  • esc_js()- 用于内联Javascript。
<div onclick='<?php echo esc_js( $value ); ?>' />
  • esc_url()– 在所有 URL 上使用，包括 HTML 元素的 src 和 href 属性中的 URL。
<img alt="" src="<?php echo esc_url( $media_url ); ?>" />
  • esc_url_raw()– 在数据库中存储 URL 或需要非编码 URL 的其他情况下使用。
  • esc_xml()– 用于转义 XML 块。
  • esc_attr()– 用于打印到 HTML 元素属性中的所有其他内容。
<ul class="<?php echo esc_attr( $stored_class ); ?>">
  • esc_textarea()– 使用它来编码文本以在文本区域元素中使用。
  • wp_kses()– 用于安全转义所有不受信任的 HTML（帖子文本、评论文本等）。这将保留 HTML。
  • wp_kses_post()– 它的替代版本会自动允许帖子内容中允许的所有 HTML。wp_kses()
  • wp_kses_data()– 替代版本仅允许帖子评论中允许的 HTML。wp_kses()

 

自定义转义示例

如果您需要以特定方式转义输出，函数 wp_kses（）（发音为“kisses”）将派上用场。

此函数确保输出中仅出现指定的 HTML 元素、属性和属性值，并规范化 HTML 实体。

<?php
echo wp_kses_post( $partial_html );
echo wp_kses(
    $another_partial_html,
    array(
        'a'      => array(
            'href'  => array(),
            'title' => array(),
        ),
        'br'     => array(),
        'em'     => array(),
        'strong' => array(),
    )
); ?>

在此示例中，除<a><br><em><strong>以外的所有标记都将被删除。此外，如果传递了<a>，则转义可确保仅返回 href和title。

 

总是转义得晚

最好尽可能晚地进行输出转义，最好是在输出数据时。

最好晚点转义，原因如下：

  • 代码审查和部署可以更快地进行，因为它可以一目了然地认为可以安全地输出，而不是在很多行代码中搜寻以查看它是否已在何处以及是否已被转义。
  • 某些内容可能会无意中更改变量的首次强制转换和输出时间之间的变量，从而引入潜在的漏洞。
  • 延迟转义使自动代码扫描变得更加容易，从而节省时间并减少审查和部署时间。
  • 尽可能延迟转义使代码更加健壮和面向未来。
  • 在输出上转义/强制转换消除了任何歧义并增加了清晰度（始终为维护者开发）。
// Okay, but not great.
$url = esc_url( $url );
$text = esc_html( $text );
echo '<a href="'. $url . '">' . $text . '</a>';

// Much better!
echo '<a href="'. esc_url( $url ) . '">' . esc_html( $text ) . '</a>';

 

除非你不能

It is sometimes not practical to escape late. In a few rare circumstances output cannot be passed to wp_kses(), since by definition it would strip the scripts that are being generated.

In situations like this, always escape while creating the string and store the value in a variable that is a postfixed with _escaped, _safe or _clean (e.g., $variable becomes $variable_escaped or $variable_safe).

If a function cannot output internally and escape late, then it must always return “safe” HTML. This allows echo my_custom_script_code(); to be done without needing the script tag to be passed through a version of wp_kses() that would allow such tags.

 

通过本地化进行转义

通常使用 WordPress 本地化功能（例如 或 ）。echo_e()__()

这些函数只是将本地化函数包装在转义函数中：

esc_html_e( 'Hello World', 'text_domain' );
// Same as
echo esc_html( __( 'Hello World', 'text_domain' ) );

这些帮助程序函数结合了本地化和转义：

 

例子

 

转义在任何地方使用的任何数值变量

echo $int;

根据它是整数还是a float, (int), absint(), (float)  都是正确且可接受的。
有时， number_format() or number_format_i18n()可能更合适。intval(), floatval()这些虽然可以，但这些是过时的PHP4的方法。

 

转义 HTML 属性中的任意变量

echo '<div id="', $prefix, '-box', $id, '">';

这应该通过一次调用 来转义。
当变量用作属性或 url 的一部分时，最好转义整个字符串，因为这样变量之前的潜在转义字符将被正确转义。esc_attr()

正确：

echo '<div id="', esc_attr( $prefix . '-box' . $id ), '">';

不對：

echo '<div id="', esc_attr( $prefix ), '-box', esc_attr( $id ), '">';

注意：如果在 HTML 属性中使用，则使用 创建的随机数也应该像这样进行转义。wp_create_nonce()

 

在 HTML 属性中转义任意 URL，但也在其他上下文中转义

echo '<a href="', $url, '">';

这应该使用 进行转义。esc_url()

正确：

echo '<a href="', esc_url( $url ), '">';

不對：

echo '<a href="', esc_attr( $url ), '">'; echo '<a href="', esc_attr( esc_url( $url ) ), '">';

 

通过 wp_localize_script（） 将任意变量传递给 JavaScript

wp_localize_script( 'handle', 'name',
	array(
		'prefix_nonce' => wp_create_nonce( 'plugin-name' ),
		'ajaxurl'      => admin_url( 'admin-ajax.php' ),
		'errorMsg'     => __( 'An error occurred', 'plugin-name' ),
	)
);

不需要转义，WordPress将转义这一点。

 

转义 JavaScript 块中的任意变量

<script type="text/javascript">    var myVar = <?php echo $my_var; ?> </script>

$my_var应使用 进行转义。esc_js()

正确：

<script type="text/javascript">
    var myVar = <?php echo esc_js( $my_var ); ?>
</script>

 

在内联 JavaScript 中转义任意变量

<a href="#" onclick="do_something(<?php echo $var; ?>); return false;">

$var应使用 进行转义。esc_js()

正确：

<a href="#" onclick="do_something(<?php echo esc_js( $var ); ?>); return false;">

 

转义 HTML 属性中的任意变量以供 JavaScript 使用

<a href="#" data-json="<?php echo $var; ?>">

$var应使用 、 或 进行转义。esc_js()json_encode()wp_json_encode()

正确：

<a href="#" data-json="<?php echo esc_js( $var ); ?>">

 

转义 HTML 文本区域中的任意字符串

echo '<textarea>', $data, '</textarea>';

$data应使用 进行转义。esc_textarea()

正确：

echo '<textarea>', esc_textarea( $data ), '</textarea>';

 

转义 HTML 标记中的任意字符串

echo '<div>', $phrase, '</div>';

这取决于是否应包含 HTML。$phrase

  • 如果没有，请使用或其任何变体。esc_html()
  • 如果需要 HTML，请使用 或与一组要允许的 HTML 标记一起使用。wp_kses_post()wp_kses_allowed_html()wp_kses()

 

转义 XML 或 XSL 上下文中的任意字符串

echo '<loc>', $var, '</loc>';

使用 或 进行转义。esc_xml()ent2ncr()

正确：

echo '<loc>', ent2ncr( $var ), '</loc>';