easy_svg_register_icon_collection()

Funktion · Easy SVG Pro · Status: Stabil

Mit diesem einen Aufruf machst du deine eigenen Icons zu einer Easy-SVG-Sammlung. Gib einen Slug, ein Label und einen Ordner mit SVG-Dateien an, und die Icons erscheinen im Block-Inserter, in den Icon-Auswahlen, in easy_svg_icon() und in WP-CLI unter der Adresse slug/icon. Den Slug legst du im Code fest, er ändert sich also nie hinter deinem Rücken.

Verwendung

easy_svg_register_icon_collection( string $slug, string $label, string|array $dir_or_icons ): void

Im globalen Namensraum in includes/sources/sources.php definiert, nur wenn es noch keine Funktion mit diesem Namen gibt. Ruf sie auf init mit der Standardpriorität 10 auf.

Wann du es brauchst

• Ein Theme legt seine Icons nicht in assets/icons ab, sondern zum Beispiel in resources/svg.
• Ein Plugin oder MU-Plugin bringt Icons mit, und die Adresse muss im Code feststehen, weil Templates und Blöcke sie schon verwenden.
• Ein Snippet braucht eine Handvoll Icons, die in PHP entstehen und deren Markup du komplett kontrollierst.

Nicht geeignet, wenn:

• Die Icons in assets/icons des Themes liegen. Sie werden automatisch gelesen, umbenennen kannst du sie mit easy_svg_pro_theme_collection_slug.
• Der Ordner Hunderte Dateien enthält. Ein hier registrierter Ordner wird bei jedem Request ohne Cache gescannt. Häng ihn lieber per easy_svg_pro_source_dirs als Drop-in ein, der wird gecacht.
• Redakteure die Icons im wp-admin ändern sollen. Nimm dafür ein Icon-Set (Icons → Icon-Sets).

Parameter

Rückgabewert

Standardwert

Ohne Aufruf wird keine Sammlung registriert. Es gibt keinen Standard-Slug und kein Standard-Label.

Beispiele

Ein Ordner in deinem Theme

/**
 * Den Ordner resources/svg des Themes als Sammlung "acme" registrieren.
 */
function acme_register_icons() {
	if ( ! function_exists( 'easy_svg_register_icon_collection' ) ) {
		return;
	}

	easy_svg_register_icon_collection(
		'acme',
		__( 'ACME Icons', 'acme' ),
		get_stylesheet_directory() . '/resources/svg'
	);
}
add_action( 'init', 'acme_register_icons' );

Templates rufen jetzt easy_svg_icon( 'acme/phone' ) auf.

Ein Agentur-Plugin mit einer Sammlung pro Marke

/**
 * Eine Sammlung pro Marken-Ordner, jede mit festem Slug.
 */
function acme_register_brand_icons() {
	if ( ! function_exists( 'easy_svg_register_icon_collection' ) ) {
		return;
	}

	$brands = array(
		'acme-shop'  => __( 'ACME Shop', 'acme' ),
		'acme-house' => __( 'ACME House', 'acme' ),
	);

	foreach ( $brands as $slug => $label ) {
		$dir = plugin_dir_path( __FILE__ ) . 'icons/' . $slug;

		if ( is_dir( $dir ) ) {
			easy_svg_register_icon_collection( $slug, $label, $dir );
		}
	}
}
add_action( 'init', 'acme_register_brand_icons' );

Leg in jeden Ordner eine manifest.json, damit die Icons lesbare Labels und Suchbegriffe bekommen. Das Manifest benennt die Icons, nie die Sammlung.

Ein paar Icons aus Markup, das du kontrollierst

/**
 * Zwei einfache Formen aus dem Code. Dieses Markup wird so registriert, wie es ist.
 */
function acme_register_shape_icons() {
	if ( ! function_exists( 'easy_svg_register_icon_collection' ) ) {
		return;
	}

	easy_svg_register_icon_collection(
		'acme-shapes',
		__( 'ACME Shapes', 'acme' ),
		array(
			'dot'    => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="12" cy="12" r="6"/></svg>',
			'square' => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect x="6" y="6" width="12" height="12"/></svg>',
		)
	);
}
add_action( 'init', 'acme_register_shape_icons' );

Defensiv: nur registrieren, wenn Pro es wirklich nutzt

function acme_register_icons_safely() {
	if ( ! function_exists( 'easy_svg_register_icon_collection' ) ) {
		return; // Easy SVG Pro ist nicht aktiv.
	}

	$dir = get_stylesheet_directory() . '/resources/svg';

	if ( ! is_dir( $dir ) ) {
		return; // Ein Tippfehler hier würde wortlos nichts registrieren.
	}

	easy_svg_register_icon_collection( 'acme', __( 'ACME Icons', 'acme' ), $dir );
}
add_action( 'init', 'acme_register_icons_safely', 10 );

So funktioniert es

1. Sperre. Der Aufruf tut nichts, solange die Lizenz nicht aktiv ist oder Theme- und Ordner-Quellen unter Icons → Funktionen ausgeschaltet ist. Es gibt keinen Hinweis, er kehrt einfach zurück.
2. Array. Ein Array geht so, wie es ist, in die Registry. Kein Sanitizer, kein Härter, keine Prüfung der Slugs. Als Herkunft wird "Code" vermerkt.
3. Ordner. Ein Ordner braucht den Sanitizer des kostenlosen Plugins und easy_svg_harden_icon_markup(), fehlt eins davon, wird nichts registriert. Der Ordner wird wie ein Drop-in gescannt: Mit manifest.json bestimmt das Manifest Name, Label und Schlagwörter jedes Icons, und jedes SVG daneben lädt trotzdem unter seinem Dateinamen. Ohne Manifest lädt jede *.svg direkt im Ordner. Grenzen: 1000 Icons und 2 MB pro Datei, einstellbar über easy_svg_pro_source_max_icons und easy_svg_pro_source_file_max_bytes.
4. Filter. Die Icons laufen durch easy_svg_pro_collection_icons. Dateien, die nicht verwendet werden konnten, werden als Probleme vermerkt, zu sehen in wp easy-svg icons problems und unter Icons → Pakete.
5. Registrieren. Bleibt mindestens ein Icon übrig, kommt es in die Registry, und easy_svg_pro_registered_collection wird ausgelöst.
6. Ausgeben. easy_svg_icon( 'acme/phone' ) liest die Registry beim Rendern der Seite. Auf init mit Priorität 11 geht die Registry an die Icon-API von WordPress (ab WordPress 7.1, mit eingeschaltetem Mehrere Sammlungen). Von dort holt der Core-Icon-Block seine Icons.

Kein Cache für Ordner. Anders als der Theme-Ordner und die Drop-ins wird ein hier übergebener Ordner nicht in einem Transient gespeichert. Jeder Request liest und bereinigt alle Dateien neu. Bei zwanzig Icons ist das egal, bei fünfhundert merkst du es.

Stolperfallen

• Priorität 10, nicht später. Die Registry geht auf init mit Priorität 11 an die Core-Icon-API. Registrierst du später, findet easy_svg_icon() die Icons zwar noch, der Inserter des Icon-Blocks listet sie aber nicht.
• Nicht auf Dateiebene. Ruf die Funktion aus einem init-Callback auf. Auf Dateiebene deines Plugins gibt es sie vielleicht noch gar nicht (Plugins laden alphabetisch), und Sanitizer und Lizenzprüfung sind erst auf init sicher bereit.
• Gleicher Slug wird zusammengeführt. Ein zweiter Aufruf mit demselben Slug, oder ein Icon-Set oder Ordner mit diesem Slug, ersetzt die Sammlung nicht: Icons kommen nach Namen dazu, das letzte Label gewinnt. Nimm Slugs, die nur du verwendest, etwa mit Präfix.
• Ein Manifest benennt die Sammlung nicht um. Ein "slug" in der manifest.json des Ordners wird hier absichtlich ignoriert, damit Templates mit deinem Slug weiter funktionieren.
• Stille bei Fehlern. Ein falscher Pfad, eine ausgeschaltete Funktion oder eine fehlende Lizenz sehen gleich aus: keine Sammlung. wp easy-svg icons list zeigt, was wirklich registriert ist.
• Array-Schlüssel werden nicht geprüft. Ein Schlüssel wie My Icon wird so verwendet und ergibt eine Adresse, die nichts aufrufen kann. Nimm Slugs in Kleinbuchstaben.

Siehe auch

• easy_svg_pro_source_dirs
• easy_svg_pro_theme_collection_slug
• easy_svg_pro_parse_manifest
• easy_svg_pro_collection_icons
• easy_svg_pro_registered_collection
• easy_svg_pro_registered_icon
• wp easy-svg icons problems
• Tutorial: Icons aus einem Theme oder Plugin ausliefern