Alert: 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.

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

Converts a number of special characters into their HTML entities.

Contents

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.

Top ↑

Parameters

$text string Required
The text which is to be encoded.
$quote_style int|string Optional
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

$charset false|string Optional
The character encoding of the string.

Default: false

$double_encode bool Optional
Whether to encode existing HTML entities.

Default: false

Top ↑

Return

string The encoded text with HTML entities.

Top ↑

Source

File: wp-includes/formatting.php. View all references 

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;
	}

	// Store the site charset as a static to avoid multiple calls to wp_load_alloptions().
	if ( ! $charset ) {
		static $_charset = null;
		if ( ! isset( $_charset ) ) {
			$alloptions = wp_load_alloptions();
			$_charset   = isset( $alloptions['blog_charset'] ) ? $alloptions['blog_charset'] : '';
		}
		$charset = $_charset;
	}

	if ( in_array( $charset, array( 'utf8', 'utf-8', 'UTF8' ), true ) ) {
		$charset = 'UTF-8';
	}

	$_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;
}

View on Trac View on GitHub

Top ↑

Top ↑

Used By

Used By
Used By Description
esc_xml() wp-includes/formatting.php

Escaping for XML blocks.
esc_js() wp-includes/formatting.php

Escapes single quotes, ", , &amp;, and fixes line endings.
esc_html() wp-includes/formatting.php

Escaping for HTML blocks.
esc_attr() wp-includes/formatting.php

Escaping for HTML attributes.
wp_specialchars() wp-includes/deprecated.php

Legacy escaping for HTML blocks.

Top ↑

Changelog

Changelog
Version Description
5.5.0 $quote_style also accepts ENT_XML1.
1.2.2 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by 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: `&` -> `&amp;`.
	);
}

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