easy_svg_rename_icon()

Change the visible name of a stored icon without touching its slug or its SVG, and get back a status word. Safe for users without unfiltered_html.

Function · Easy SVG · Status: Stable

easy_svg_rename_icon() changes the name an icon shows in the library and in the Icon block's picker. It keeps the slug, so every template, shortcode and saved block that uses the icon keeps working, and it keeps the SVG intact, which a plain wp_update_post() would not.

Usage

easy_svg_rename_icon( int $id, string $label ): string

When to use it

An add-on or a custom admin screen lets people rename icons.
A migration script cleans up icon names in bulk (for example arrow_left_24px to Arrow left).
You translate or standardise the names editors see in the picker.

When not to use it:

To change the slug. The slug is the icon's address and is never changed on purpose: themes and saved Icon blocks carry it. To get a different slug, add the icon again under the new name and update the places that use it.
To change the name only in the editor's picker for one site. Change label in easy_svg_registrable_icons instead; the stored title stays.

Parameters

body

$idint

Required

The post ID of the icon (post type esw_icon). Cast to an integer; zero, negative values, missing posts and posts of any other type all answer not_found.

body

$labelstring

Required

The new name, already cleaned as plain text. The function stores it as given: it does not trim and does not sanitize. An empty string answers no_label; a string of spaces is not empty and is stored. Run sanitize_text_field() first, as the plugin's REST route does.

Return value

returnstring

One word. It never returns a WP_Error and never throws.

renamed: the title is stored and the cached icon list is dropped.
not_found: no esw_icon post with that ID.
no_label: $label is an empty string.
failed: wp_update_post() returned an error or 0.

Examples

Basic

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

Handling a form submission

function myplugin_handle_icon_rename() {
	check_admin_referer( 'myplugin_rename_icon' );

	if ( ! current_user_can( 'manage_options' ) ) {
		wp_die( esc_html__( 'You are not allowed to rename icons.', 'myplugin' ) );
	}

	$id    = isset( $_POST['icon_id'] ) ? absint( $_POST['icon_id'] ) : 0;
	$label = isset( $_POST['label'] ) ? sanitize_text_field( wp_unslash( $_POST['label'] ) ) : '';

	$state = easy_svg_rename_icon( $id, $label );

	wp_safe_redirect( add_query_arg( 'myplugin_rename', $state, wp_get_referer() ) );
	exit;
}
add_action( 'admin_post_myplugin_rename_icon', 'myplugin_handle_icon_rename' );

Bulk clean-up of names

foreach ( easy_svg_stored_icons() as $icon ) {
	$clean = ucfirst( trim( str_replace( array( '_', '-' ), ' ', preg_replace( '/_?\d+px$/', '', $icon['label'] ) ) ) );

	if ( '' !== $clean && $clean !== $icon['label'] ) {
		easy_svg_rename_icon( $icon['id'], sanitize_text_field( $clean ) );
	}
}

Each call drops the icon cache, so run this once (for example from WP-CLI with wp eval-file), not on every request. easy_svg_stored_icons() is an internal helper, not part of the promised API, so keep such scripts one-off.

Defensive: check the contract version

The function exists since EASY_SVG_ICONS_API 2 (Easy SVG 5.4.0).

if ( defined( 'EASY_SVG_ICONS_API' ) && EASY_SVG_ICONS_API >= 2 && function_exists( 'easy_svg_rename_icon' ) ) {
	$state = easy_svg_rename_icon( $icon_id, $label );
}

The function checks neither capabilities nor nonces, and stores the label as given. The label is later printed in the admin and in the editor's picker, so it must be plain text: run sanitize_text_field() on it and check a capability before you call it for a request. The plugin's own REST route requires manage_options; the esw_icon post type itself is guarded by edit_theme_options.

How it works

Why it exists rather than a plain wp_update_post():

kses. wp_update_post() saves the whole row again, so post_content passes content_save_pre too. WordPress's kses filter knows no SVG and empties the icon for every user without unfiltered_html (for example administrators on a multisite). The function turns kses off for exactly this one write, if it was on, and back on in a finally block.
Cache. The icon list is cached in the transient easy_svg_icons for a day. easy_svg_forget_icons() raises the option easy_svg_icons_version and deletes the transient, so the next request offers the new name in the Icon block. It is called directly because the save_post_esw_icon hook that would also do it is only registered while the icon library is switched on.
Slug. Only post_title is sent, so post_name cannot move.

Pitfalls

A title without letters or digits. The rename itself succeeds, but easy_svg_update_icon_markup() derives a name from the title and answers refused for a title like !!! or one in a non-Latin script. Keep titles that sanitize_title() turns into a valid slug if the icon may get new artwork later.
Whitespace-only labels. ' ' is stored. Trim before you call.
Unslashed input. Pass the value through wp_unslash() before sanitizing; the function slashes it for wp_update_post() itself, so do not slash it again.
Hooks fire. save_post, save_post_esw_icon and post_updated run like for any update.
Templates do not show the title. easy_svg_icon() prints the drawing; the title only appears as a fallback aria-label when you pass decorative false without a label.

Was this page helpful?