Icons aus einem Theme oder Plugin ausliefern

Du kannst Icons als Dateien in deinem Theme oder Plugin mitliefern, statt sie im wp-admin hochzuladen. Easy SVG Pro liest die Dateien, bereinigt sie und bietet sie überall an, wo man Icons auswählt: im Block-Inserter, in den Icon-Feldern, in easy_svg_icon() und in Twig. Dieses Tutorial zeigt die drei Wege hinein, wie du Icons mit einer manifest.json beschreibst und wie du prüfst, dass alles angekommen ist.

Die drei Wege

Jedes Icon hat dann die Adresse sammlung/icon, zum Beispiel acme/phone.

Weg 1: der Theme-Ordner

Leg deine Icons in assets/icons deines Themes:

my-theme/
  assets/
    icons/
      phone.svg
      mail.svg
      manifest.json   (optional)

Eltern-Theme und aktives Child-Theme werden beide gelesen und zu einer Sammlung zusammengeführt:

• Ein Icon im Child-Theme ersetzt das gleichnamige Icon des Eltern-Themes. Die Oberfläche vermerkt, dass das Child-Theme das Eltern-Theme überschreibt.
• slug und label aus dem Manifest des Child-Themes gewinnen gegen die des Eltern-Themes.
• Ohne Slug im Manifest heißt die Sammlung theme und trägt das Label "Theme icons".

In einem Template:

<?php
if ( function_exists( 'easy_svg_icon' ) ) {
	echo easy_svg_icon( 'theme/phone', array( 'label' => __( 'Call us', 'acme' ) ) ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- bereinigtes SVG.
}

Willst du der Sammlung einen Markennamen geben, schreib entweder "slug": "acme" in assets/icons/manifest.json oder nimm den Filter:

function acme_theme_icon_slug( $slug ) {
	return 'acme';
}
add_filter( 'easy_svg_pro_theme_collection_slug', 'acme_theme_icon_slug' );

Weg 2: Drop-in-Ordner

Jeder Ordner direkt in wp-content/easy-svg-icons ist eine eigene Sammlung:

wp-content/
  easy-svg-icons/
    house-icons/
      front-door.svg
      manifest.json
    social/
      github.svg

Hier kannst du auch ein exportiertes Paket einfach entpacken. Der Ordnername ergibt den Slug, sofern das Manifest keinen nennt. Ein für einen Ordnernamen festgelegter Slug wird in der Option easy_svg_pro_dropin_collection_slugs gespeichert und bleibt so stabil.

Wollen zwei Sammlungen denselben Namen, weicht der Ordner von selbst aus: Er nimmt den Slug aus dem Manifest, wenn der frei ist, sonst den eigenen Ordner-Slug, sonst diesen Slug mit einer Zahl (house-icons-2). Das wird bei jedem Request neu entschieden. Verschwindet die andere Sammlung, bekommt der Ordner seinen Wunschnamen zurück.

Ordner an anderer Stelle fügst du per Filter hinzu, sie verhalten sich genau wie ein Drop-in:

/**
 * Einen gecachten Icon-Ordner aus einem Plugin ausliefern.
 */
function acme_plugin_icon_dir( $dirs ) {
	$dirs[] = plugin_dir_path( __FILE__ ) . 'icons/acme-social';

	return $dirs;
}
add_filter( 'easy_svg_pro_source_dirs', 'acme_plugin_icon_dir' );

Ordner werden über ihren Namen geführt. Gib also jedem Ordner einen eigenen Namen oder einen Slug im Manifest.

Weg 3: im Code 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' );

Was hier anders ist:

• Der Slug ist genau der, den du übergibst. Eine manifest.json im Ordner benennt die Icons, nie die Sammlung.
• Ruf die Funktion auf init mit Priorität 10 auf. Die Registry geht auf Priorität 11 an die Core-Icon-API. Ein späterer Aufruf funktioniert noch für easy_svg_icon(), verpasst aber den Icon-Block.
• Ein so registrierter Ordner wird nicht gecacht: Jeder Request liest und bereinigt alle Dateien. Für große Ordner nimm lieber einen Drop-in über easy_svg_pro_source_dirs.
• Ein zweiter Aufruf mit demselben Slug ergänzt die bestehende Sammlung um Icons und ersetzt ihr Label.

Icons mit manifest.json beschreiben

Ein Ordner funktioniert ohne Manifest. Ergänze eins, wenn du Labels, Suchbegriffe oder Lizenzangaben willst:

{
  "version": 1,
  "slug": "house-icons",
  "label": "House icons",
  "icons": {
    "front-door": {
      "file": "front-door.svg",
      "label": "Front door",
      "keywords": ["entrance", "door"]
    },
    "window": {
      "label": "Window"
    }
  },
  "license": "CC0-1.0",
  "author": "Your agency",
  "source": "https://example.com/packs/house-icons"
}

Die Regeln, so wie das Plugin sie anwendet:

• version ist die Schema-Version. Eine Version, die neuer ist, als dein Easy SVG Pro versteht, lehnt den ganzen Ordner ab, statt ihn halb verstanden zu lesen. Lass sie auf 1.
• slug und label benennen die Sammlung. Ein ungültiger Slug wird ignoriert, dann gilt der Slug des Ordners. Bei einer Code-Registrierung werden beide für den Sammlungsnamen ignoriert.
• icons ist Pflicht und darf nicht leer sein. Es kann ein Objekt mit dem Icon-Namen als Schlüssel sein, wie oben, oder eine Liste von Einträgen. Jeder Eintrag darf file, name (Alias slug), label und keywords (Alias tags) angeben.
• Ein Eintrag ohne file meint die Datei, die so heißt wie der Eintrag: window oben ist window.svg.
• Ein Icon-Name besteht aus Kleinbuchstaben, Ziffern, - und _. Ein ungültiger Name wird übersprungen, nie umgeschrieben.
• file muss ein einfacher Dateiname im selben Ordner sein. Unterordner, .. und Symlinks, die den Ordner verlassen, werden abgelehnt.
• Das Manifest beschreibt, es schränkt nicht ein. Ein SVG im Ordner ohne Eintrag lädt trotzdem, benannt nach seiner Datei. Eine Datei, die das Manifest umbenannt hat, erscheint einmal, unter dem Namen aus dem Manifest.
• license, author, source sind optionaler Freitext. Sie erscheinen unter der Sammlung in Icons → Pakete, und es passiert nichts weiter damit: source wird nie abgerufen und nie zum Link.
• Ein Manifest, das kein gültiges JSON ist, keine Icons hat oder eine JSON-Liste statt eines Objekts ist, registriert nichts aus diesem Ordner. Das ist Absicht: Ein Tippfehler darf nicht jede Datei im Ordner veröffentlichen.

Grenzen

Die Grenzen gelten für den Theme-Ordner, Drop-ins und Ordner, die du an die Registrierungsfunktion übergibst. Eine geänderte Grenze wirkt, sobald ein Ordner neu gescannt wird. Ändere also eine Datei oder warte, bis der gecachte Scan abläuft.

So wird aus einem Ordner eine Sammlung

Jede Datei läuft durch den Sanitizer und den Härter der Seite, bevor sie im Cache oder in der Registry landet. Der gecachte Scan verfällt, wenn sich ein SVG, das Manifest oder die Sanitizer-Datei des kostenlosen Plugins ändert.

Die übrigen Quellen-Hooks

Neben den beiden dokumentierten Filtern hat der Scanner drei weitere Hooks. Es gibt sie, und diese Referenz listet sie, aber die readme verspricht sie nicht. Verlass dich also nicht darauf, dass sie bleiben:

• easy_svg_pro_parse_manifest bekommt ein gültiges Manifest in seiner kanonischen Form und den Ordnerpfad, zum Beispiel um Suchbegriffe zu ergänzen. Das Ergebnis wird mit dem Scan gecacht.
• easy_svg_pro_collection_icons bekommt bei jedem Request die fertige Liste slug => markup jeder Quellen-Sammlung. Markup, das du hier ergänzt, wird nicht noch einmal bereinigt.
• easy_svg_pro_registered_collection wird pro Quellen-Sammlung mit mindestens einem Icon ausgelöst, mit Slug, Label, Anzahl und Ordner.

Icon-Sets, die im wp-admin entstehen, laufen durch keinen dieser Hooks. Der eine Hook, den jede Sammlung auf dem Weg zum Core-Icon-Block passiert, ist easy_svg_pro_registered_icon.

Prüfen, was angekommen ist

Auf der Kommandozeile (dafür muss zusätzlich WP-CLI unter Icons → Funktionen eingeschaltet sein):

wp easy-svg icons list

+-------------+--------------+-------+--------------------+----------+
| collection  | label        | count | origin             | problems |
+-------------+--------------+-------+--------------------+----------+
| acme        | ACME Icons   | 24    | theme my-theme     | 0        |
| house-icons | House icons  | 11    | dropin house-icons | 2        |
+-------------+--------------+-------+--------------------+----------+

Eine Sammlung mit Problemen bekommt eine Hinweiszeile. Dann:

wp easy-svg icons problems

Das listet eine Zeile pro Datei mit collection, source, file, icon und reason. Dieselben Gründe stehen unter der Sammlung in Icons → Pakete. Ein Ordner mit kaputtem Manifest erscheint dort trotzdem, mit null Icons und seinem Grund.

Häufige Fehler

• Es erscheint gar nichts. Prüf Icons → Funktionen: Theme- und Ordner-Quellen muss an sein und die Lizenz aktiv. Für den Core-Icon-Block brauchst du außerdem Mehrere Sammlungen und WordPress 7.1 oder neuer.
• Icons erscheinen in Templates, aber nicht im Icon-Block. Die Code-Registrierung lief nach init mit Priorität 10, oder Mehrere Sammlungen ist aus.
• Icons sehen im Icon-Block leer aus. Core behält nur Pfade und Polygone. Striche und Formen schreibt das kostenlose Plugin um, Verläufe, Masken, use und text lassen sich nicht übertragen. Über easy_svg_icon() erscheinen sie trotzdem.
• Ein Ordner hat den Slug name-2 bekommen. Eine andere Sammlung belegt den Namen. Benenn eine davon um oder gib dem Ordner einen freien slug im Manifest.
• Ein Unterordner wird ignoriert. Gelesen werden nur SVG-Dateien direkt im Ordner, und unter wp-content/easy-svg-icons nur eine Ebene von Ordnern.

Siehe auch

• easy_svg_register_icon_collection()
• easy_svg_pro_source_dirs
• easy_svg_pro_theme_collection_slug
• easy_svg_pro_registered_icon
• wp easy-svg icons problems
• wp easy-svg icons validate
• Tutorial: Mit WP-CLI automatisieren