_wp_specialchars( string $text, int|string $quote_style = ENT_NOQUOTES, false|string $charset = false, bool $double_encode = false ): string

This function’s access is marked private. This means it is not intended for use by plugin or theme developers, only in other core functions. It is listed here for completeness.

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 &quot;, 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

Return

string The encoded text with HTML entities.

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 &amp;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( "'", '&#039;', $text );
	}

	return $text;
}

Changelog

VersionDescription
5.5.0$quote_style also accepts ENT_XML1.
1.2.2Introduced.

User Contributed Notes

  1. Skip to note 2 content

    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: `&` -> `&amp;`.
    	);
    }

You must log in before being able to contribute a note or feedback.