Escaping Data

目录

Escaping output is the process of securing output data by stripping out unwanted data, like malformed HTML or script tags. This process helps secure your data prior to rendering it for the end user. 

Escaping Functions

WordPress has many helper functions you can use for most common scenarios.

Pay close attention to what each function does, as some will remove HTML while others will permit it. You must use the most appropriate function to the content and context of what you’re echoing. You always want to escape when you echo, not before.

<h4><?php echo esc_html( $title ); ?></h4>

<div onclick='<?php echo esc_js( $value ); ?>' />

<img alt="" src="<?php echo esc_url( $media_url ); ?>" />

<ul class="<?php echo esc_attr( $stored_class ); ?>">

Custom Escaping Example

In the case that you need to escape your output in a specific way, the function wp_kses() (pronounced “kisses”) will come in handy.

This function makes sure that only the specified HTML elements, attributes, and attribute values will occur in your output, and normalizes HTML entities.

<?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(),
    )
); ?>

In this example, all tags other than <a>, <br>, <em>, and <strong> will be stripped out. Additionally, if an <a> tag is passed, the escaping ensures that only the href and the title are returned.

Always escape late

It is best to do the output escaping as late as possible, ideally as data is being outputted.

It is better to escape late for a few reasons:

// 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>';

… Except when you can’t

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.

Escaping with Localization

Rather than using echo to output data, it’s common to use the WordPress localization functions, such as _e() or __().

These functions simply wrap a localization function inside an escaping function:

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

These helper functions combine localization and escaping:

Examples

Escaping any numeric variable used anywhere

echo $int;

Depending on whether it is an integer or a float, (int), absint(), (float) are all correct and acceptable.
At times, number_format() or number_format_i18n() might be more appropriate.

intval(), floatval() are acceptable, but are outdated (PHP4) functions.

Escaping arbitrary variable within HTML attribute

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

This should be escaped with one call to esc_attr().
When a variable is used as part of an attribute or url, it is always better to escape the whole string as that way a potential escape character just before the variable will be correctly escaped.

Correct:

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

Incorrect:

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

Note: nonces created using wp_create_nonce() should also be escaped like this if used in an HTML attribute.

Escaping arbitrary URL within HTML attribute, but also in other contexts

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

This should be escaped with esc_url().

Correct:

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

Incorrect:

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

Passing an arbitrary variable to JavaScript via wp_localize_script()

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' ),
    )
);

No escaping needed, WordPress will escape this.

Escaping arbitrary variable within JavaScript block

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

$my_var should be escaped with esc_js().

Correct:

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

Escaping arbitrary variable within inline JavaScript

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

$var should be escaped with esc_js().

Correct:

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

Escaping arbitrary variable within HTML attribute for use by JavaScript

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

$var should be escaped with esc_js(), json_encode() or wp_json_encode().

Correct:

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

Escaping arbitrary string within HTML textarea

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

$data should be escaped with esc_textarea().

Correct:

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

Escaping arbitrary string within HTML tags

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

This depends on whether $phrase is expected to contain HTML or not.

Escaping arbitrary string within XML or XSL context

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

Escape with esc_xml() or ent2ncr().

Correct:

echo '<loc>', ent2ncr( $var ), '</loc>';
版本号 #2
由 壳壳虫 创建于 2026-10-31 18:07:55 UTC
由 壳壳虫 更新于 2026-10-31 18:07:56 UTC