ConstantsEASY_SVG_ICONS_API

EASY_SVG_ICONS_API

Version number of the icon contract in Easy SVG: easy_svg_registrable_icons, easy_svg_rename_icon() and easy_svg_update_icon_markup(). Check before use.

Constant · Easy SVG · Status: Stable

EASY_SVG_ICONS_API tells an add-on which icon tools Easy SVG offers: a filter that changes icons before they reach the Icon block, a function that renames an icon, and a function that replaces an icon's drawing. You cannot ask WordPress whether a filter exists, so this number is the reliable way to know. Since 5.4.0.

Usage

define( 'EASY_SVG_ICONS_API', 3 );

Defined in easy-svg.php when the plugin loads.

When to use it

  • Your add-on resizes or recolours icons for the Icon block through easy_svg_registrable_icons and should only do so where that filter is applied (1 or more).
  • Your add-on renames stored icons with easy_svg_rename_icon() (2 or more).
  • Your add-on repairs or replaces an icon's markup with easy_svg_update_icon_markup() (3).

Do not use it to find out whether the icon library is switched on: the constant exists either way (see Pitfalls).

Parameters

None: this is a constant, not a function.

Return value

EASY_SVG_ICONS_APIint

Today 3. What each level adds:

  • 1: the filter easy_svg_registrable_icons, which receives the whole library as a list of slug, label and content before it is registered with WordPress's icon registry.
  • 2: easy_svg_rename_icon( $id, $label ), answering renamed, not_found, no_label or failed.
  • 3: easy_svg_update_icon_markup( $id, $markup ), answering updated, not_found, no_markup, refused or failed.

All three shipped together in 5.4.0, so every released version that has the constant has the value 3.

Default

Not applicable: the constant is missing when Easy SVG is not active, or when an Easy SVG older than 5.4.0 is installed.

Examples

Replace an icon's drawing safely

function myaddon_repair_icon( $icon_id, $markup ) {
	if ( ! defined( 'EASY_SVG_ICONS_API' ) || EASY_SVG_ICONS_API < 3 ) {
		return 'unsupported';
	}

	// Runs through the site's sanitizer and the upload size and complexity bounds.
	return easy_svg_update_icon_markup( $icon_id, $markup );
}

Rename, with a fallback message on older versions

function myaddon_rename_icon( $icon_id, $label ) {
	if ( ! defined( 'EASY_SVG_ICONS_API' ) || EASY_SVG_ICONS_API < 2 ) {
		return new WP_Error( 'myaddon_old_easy_svg', __( 'Please update Easy SVG Support to rename icons.', 'myaddon' ) );
	}

	$state = easy_svg_rename_icon( $icon_id, sanitize_text_field( $label ) );

	return 'renamed' === $state ? true : new WP_Error( 'myaddon_rename_' . $state, $state );
}

Hook the registration filter only when it is applied

function myaddon_size_icons( $icons ) {
	foreach ( $icons as $index => $icon ) {
		if ( isset( $icon['content'] ) && is_string( $icon['content'] ) ) {
			$icons[ $index ]['content'] = str_replace( '<svg ', '<svg width="24" height="24" ', $icon['content'] );
		}
	}

	return $icons;
}

function myaddon_boot_icons() {
	if ( defined( 'EASY_SVG_ICONS_API' ) ) {
		add_filter( 'easy_svg_registrable_icons', 'myaddon_size_icons' );
	}
}
add_action( 'plugins_loaded', 'myaddon_boot_icons' );

How it works

  • define( 'EASY_SVG_ICONS_API', 3 ) runs unconditionally when easy-svg.php loads, on every request.
  • easy_svg_rename_icon() and easy_svg_update_icon_markup() live in includes/icon-writes.php, which is always loaded. Both turn kses off for their one write (kses does not know SVG and would empty the icon for users without unfiltered_html) and drop the cached icon list afterwards.
  • easy_svg_update_icon_markup() sends the new markup through the same decision an upload meets: the size limit from easy_svg_max_bytes, the structure bounds, the site's sanitizer, and the extra hardening for icons. Neither the slug nor the title changes.
  • easy_svg_registrable_icons is applied while the icons are registered with WordPress's icon registry. That only happens when the icon library is switched on under Icons → Settings and WordPress has the icon registry (7.1 and newer).

Pitfalls

  • Present does not mean switched on. The constant and both functions exist even when the icon library is off. Your filter on easy_svg_registrable_icons then simply never runs, and the write functions still change stored icon posts.
  • Checking too early. Like the other constants it only exists after easy-svg.php has loaded. Check on plugins_loaded or later.
  • Writing the icon post yourself. wp_update_post() on an icon passes kses and empties the SVG for most users, and the editor keeps showing the old icon list. Use the two functions.
  • Changing the slug. Neither function moves post_name. That is deliberate: saved Icon blocks and templates refer to the slug, and a missing icon renders as nothing.
easy_svg_registrable_icons runs after Easy SVG has sanitized and hardened the stored icons. Whatever you put into content there skips Easy SVG's sanitizer and only meets the short allow-list of WordPress's icon registry. Only change sizes, classes or colours, and never add markup that came from user input without cleaning it with easy_svg_sanitizer() first.
Was this page helpful?