easy_svg_update_icon_markup()

Funktion · Easy SVG · Status: Stabil

easy_svg_update_icon_markup() gibt einem vorhandenen Icon eine neue Zeichnung. Das neue SVG durchläuft dieselben Prüfungen wie ein Upload (Größengrenze, Komplexitätsprüfung, der Sanitizer der Website und der Icon-Härter) und ersetzt dann das gespeicherte Markup. Das Icon behält Slug und Namen, jedes Template, jeder Shortcode und jeder gespeicherte Icon-Block zeigt also die neue Zeichnung.

Verwendung

easy_svg_update_icon_markup( int $id, string $markup ): string

Wann du es brauchst

• Ein Add-on repariert oder optimiert Icons (zum Beispiel ohne fest eingetragene Farben) und schreibt sie zurück.
• Ein Import- oder Sync-Skript aktualisiert Icons aus einem Designsystem, ohne ihre Adressen zu ändern.
• Eine eigene Admin-Seite lässt eine Designerin die Grafik eines Icons tauschen.

Wann nicht:

• Um ein neues Icon anzulegen. Nimm dafür die Icons-Seite oder die REST-Route des Panels, diese Funktion ändert nur vorhandene.
• Um den Namen zu ändern. Dafür gibt es easy_svg_rename_icon().
• Um nur zu ändern, was der Icon-Block zeigt. Nimm easy_svg_registrable_icons, das lässt die gespeicherte Datei in Ruhe.

Parameter

Rückgabewert

Beispiele

Einfach

$state = easy_svg_update_icon_markup( $icon_id, $new_svg );

if ( 'updated' !== $state ) {
	error_log( sprintf( 'Icon %d not replaced: %s', $icon_id, $state ) );
}

Ein Icon per Slug aus einer Datei ersetzen

function myplugin_replace_icon_from_file( $slug, $file ) {
	if ( ! current_user_can( 'edit_theme_options' ) ) {
		return 'forbidden';
	}

	$post = get_page_by_path( $slug, OBJECT, 'esw_icon' );
	if ( ! $post || 'esw_icon' !== $post->post_type ) {
		return 'not_found';
	}

	if ( ! is_readable( $file ) ) {
		return 'no_markup';
	}

	return easy_svg_update_icon_markup( (int) $post->ID, (string) file_get_contents( $file ) );
}

Die Berechtigungsprüfung ist deine Sache. edit_theme_options ist die Berechtigung, die der Beitragstyp esw_icon verlangt (EASY_SVG_ICON_CAP). Die REST-Routen der Bibliothek im Plugin sind strenger und verlangen manage_options.

Aus dem Status eine Meldung machen

$messages = array(
	'updated'   => __( 'Icon replaced.', 'myplugin' ),
	'not_found' => __( 'That icon no longer exists.', 'myplugin' ),
	'no_markup' => __( 'The file was empty.', 'myplugin' ),
	'refused'   => __( 'That file is not an SVG this library can use.', 'myplugin' ),
	'failed'    => __( 'The icon could not be saved. Please try again.', 'myplugin' ),
);

$state = easy_svg_update_icon_markup( $icon_id, $markup );
add_settings_error( 'myplugin', 'icon-' . $state, $messages[ $state ] ?? $messages['failed'], 'updated' === $state ? 'success' : 'error' );

Defensiv: die Vertragsversion prüfen

Die Funktion gibt es seit EASY_SVG_ICONS_API 3 (Easy SVG 5.4.0).

if ( defined( 'EASY_SVG_ICONS_API' ) && EASY_SVG_ICONS_API >= 3 && function_exists( 'easy_svg_update_icon_markup' ) ) {
	$state = easy_svg_update_icon_markup( $icon_id, $markup );
} else {
	$state = 'unsupported';
}

So funktioniert es

1. Suche. get_post() mit der ID, der Beitragstyp muss esw_icon sein.
2. Prüfungen vor dem Parsen. easy_svg_accept_icon() lehnt eine Datei über der Bytegrenze ab (die Größe unter Icons, Einstellungen, filterbar mit easy_svg_max_bytes) und eine Datei, die die Komplexitätsprüfung markiert, bevor der Sanitizer sie überhaupt sieht.
3. Bereinigen. Der Sanitizer der Website (mit esw_svg_allowed_tags und esw_svg_allowed_attributes) bereinigt das Markup. Ein Ergebnis ohne svg-Wurzel wird abgelehnt. Danach entfernt easy_svg_harden_icon_markup() script, style, foreignObject, iframe, embed, object, die Animationselemente, jedes on-Attribut und jedes externe href.
4. Der Schreibvorgang. Der kses-Filter von WordPress kennt kein SVG und würde das Icon für Benutzer ohne unfiltered_html leeren. Die Funktion schaltet kses genau für diesen einen Schreibvorgang ab, falls es an war, und in einem finally-Block wieder an. Nur post_content ändert sich, post_name und post_title bleiben.
5. Cache. easy_svg_forget_icons() erhöht die Option easy_svg_icons_version und löscht den Transient easy_svg_icons, die nächste Anfrage registriert also die neue Zeichnung im Icon-Block. Die Funktion wird direkt aufgerufen, weil der Hook save_post_esw_icon, der das auch täte, nur registriert ist, solange die Icon-Bibliothek eingeschaltet ist.

Stolperfallen

• refused wegen des Titels. Die Prüfungen leiten aus dem aktuellen Titel des Icons einen Namen ab und lehnen ab, wenn daraus kein gültiger Slug wird. Ein Icon, das in einen Titel ohne Buchstaben oder Ziffern umbenannt wurde (etwa !!!) oder in einen Titel in einer Schrift wie Kyrillisch oder Japanisch, den sanitize_title() in Prozent-Kodierung verwandelt, kann keine neue Zeichnung mehr bekommen. Benenne es erst in einen lateinischen Titel um, dann aktualisiere.
• refused hat fünf Ursachen. Am Rückgabewert erkennst du nicht, ob die Datei zu groß oder kein SVG war. Brauchst du das, ruf easy_svg_max_bytes() und easy_svg_svg_too_complex() vorher selbst auf.
• Hooks laufen. Wie bei jedem wp_update_post() feuern save_post, save_post_esw_icon und verwandte Hooks. Code, der darauf reagiert, läuft mit.
• Templates sofort, der Block bei der nächsten Anfrage. easy_svg_icon() liest den Beitrag direkt, der Icon-Block liest die Registry, die beim nächsten init neu aufgebaut wird.
• Schreib post_content nicht selbst. Ein direktes wp_update_post() umgeht den Sanitizer, leert das Icon für Benutzer ohne unfiltered_html und lässt eine veraltete Liste bis zu einen Tag im Cache.

Siehe auch

• easy_svg_rename_icon()
• easy_svg_accept_icon()
• easy_svg_sanitizer()
• easy_svg_forget_icons()
• easy-svg/v1/library/replace
• EASY_SVG_ICONS_API