easy_svg_pro_source_dirs

Filter · Easy SVG Pro · Status: Stabil

Jeder Unterordner von wp-content/easy-svg-icons wird zu einer eigenen Icon-Sammlung: SVG-Dateien hineinlegen, und sie erscheinen im Block-Inserter, in den Icon-Auswahlen und in easy_svg_icon(). Dieser Filter gibt dir die Liste dieser Ordner, bevor einer davon gelesen wird. Du kannst einen Ordner von woanders hinzufügen oder einen herausnehmen, damit er nicht registriert wird.

Verwendung

apply_filters( 'easy_svg_pro_source_dirs', string[] $dirs )

Angewendet in includes/sources/sources.php, in boot_sources(), das auf init mit Priorität 9 läuft.

Wann du es brauchst

• Deine Icons liegen in einem Ordner, den du mit deinem eigenen Code auslieferst, zum Beispiel wp-content/client-icons/brand, und sie sollen sich genau wie ein Drop-in verhalten: zwischengespeichert, mit Manifest, benannt nach dem Ordner.
• Ein Plugin oder MU-Plugin bringt einen großen Icon-Ordner mit. Ein Drop-in wird zwischen Requests gecacht, ein Ordner, den du an easy_svg_register_icon_collection() übergibst, nicht. Bei Hunderten Dateien ist dieser Filter also der günstigere Weg.
• Auf einer Live-Seite liegt noch ein Testordner in wp-content/easy-svg-icons, und er soll aus dem Inserter verschwinden, ohne dass du Dateien löschst.

Nicht geeignet, wenn:

• Du den Slug der Sammlung im Code festlegen willst. Ein hier hinzugefügter Ordner wird über seine manifest.json oder seinen Ordnernamen benannt. Nimm easy_svg_register_icon_collection(), wenn der Slug in PHP feststehen muss.
• Du nur die eigene Sammlung des Themes umbenennen willst. Dafür gibt es easy_svg_pro_theme_collection_slug.

Parameter

Rückgabewert

Standardwert

Jeder Ordner, den glob( WP_CONTENT_DIR . '/easy-svg-icons/*', GLOB_ONLYDIR ) findet. Tiefere Unterordner gehören nicht zur Liste.

Beispiele

Einen Ordner außerhalb des Drop-in-Verzeichnisses hinzufügen

/**
 * wp-content/client-icons/brand als zusätzliche Drop-in-Sammlung registrieren.
 */
function acme_add_brand_icons( $dirs ) {
	$dirs[] = WP_CONTENT_DIR . '/client-icons/brand';

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

Die Sammlung heißt brand, oder so, wie der slug in der manifest.json des Ordners lautet.

Ein Agentur-Plugin mit mehreren Icon-Ordnern

/**
 * Jeder Unterordner von icons/ in diesem Plugin wird zu einer Sammlung.
 */
function acme_agency_icon_dirs( $dirs ) {
	$base  = plugin_dir_path( __FILE__ ) . 'icons';
	$found = glob( $base . '/*', GLOB_ONLYDIR );

	if ( is_array( $found ) ) {
		$dirs = array_merge( $dirs, $found );
	}

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

Gib jedem Ordner eine manifest.json mit einem slug, der nicht kollidieren kann, etwa acme-social. Dann hängt der Name der Sammlung nicht am Ordnernamen.

Einen Ordner nur auf der Live-Seite ausblenden

/**
 * Den Drop-in "sandbox" überall außer lokal aus dem Inserter heraushalten.
 */
function acme_hide_sandbox_icons( $dirs ) {
	if ( 'local' === wp_get_environment_type() ) {
		return $dirs;
	}

	return array_values(
		array_filter(
			$dirs,
			static function ( $dir ) {
				return 'sandbox' !== basename( untrailingslashit( (string) $dir ) );
			}
		)
	);
}
add_filter( 'easy_svg_pro_source_dirs', 'acme_hide_sandbox_icons' );

Nur einen Ordner hinzufügen, den es wirklich gibt

function acme_add_optional_icons( $dirs ) {
	$dir = WP_CONTENT_DIR . '/shared-icons';

	if ( is_dir( $dir ) && is_readable( $dir ) ) {
		$dirs[] = $dir;
	}

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

So funktioniert es

boot_sources() läuft auf init mit Priorität 9, also vor der eigenen Sammlung des kostenlosen Plugins (Priorität 10) und bevor die Sammlungen an die Icon-API von WordPress gehen (Priorität 11). Es passiert nichts, solange nicht

• die Lizenz aktiv ist und Theme- und Ordner-Quellen unter Icons → Funktionen eingeschaltet ist, und
• das kostenlose Easy SVG Support seinen Sanitizer und easy_svg_harden_icon_markup() mitbringt. Fehlt eins davon, registriert keine Ordnerquelle etwas.

Dann läuft bei jedem Request:

1. Zuerst wird die Theme-Sammlung gescannt (assets/icons von Eltern- und Child-Theme).
2. Die Drop-in-Ordner werden per glob() gesucht und durch diesen Filter geschickt.
3. Jeder zurückgegebene Pfad wird über seinen Ordnernamen (basename()) geführt. Zwei Pfade mit gleichem Ordnernamen werden zu einem, der spätere gewinnt. Weil der Name zählt und nicht der Pfad, bleiben die Sammlungen erhalten, wenn die Seite in ein anderes Document Root umzieht.
4. Für jeden Ordnernamen wird einmal ein Slug festgelegt und in der Option easy_svg_pro_dropin_collection_slugs gespeichert. So behält ein Ordner seinen Slug dauerhaft. Seiten, die schon vor dieser Aufzeichnung liefen, behalten ihre alten Slugs, die auf -x enden können.
5. Jeder Ordner wird gescannt. Mit manifest.json bestimmt das Manifest Namen, Labels und Schlagwörter der Icons, jedes andere SVG daneben lädt trotzdem unter seinem Dateinamen. Ohne Manifest lädt jede *.svg direkt im Ordner (nicht rekursiv). Jede Datei läuft durch den Sanitizer und den Härter der Seite.
6. Verwendet wird der slug aus dem Manifest, wenn ihn niemand sonst belegt, sonst der gespeicherte Ordner-Slug, sonst dieser Slug mit einer Zahl (brand-2). "Belegt" heißt: eine andere registrierte Sammlung oder easy-svg, die Bibliothek des kostenlosen Plugins.

Cache. Ein Scan liegt einen Tag lang in einem Transient namens easy_svg_pro_src_ plus md5 des Pfads. Seine Signatur umfasst die Änderungszeit jedes SVGs, die manifest.json und die Sanitizer-Datei des kostenlosen Plugins. Eine Datei hinzufügen, ändern oder löschen oder das kostenlose Plugin aktualisieren löst beim nächsten Request einen neuen Scan aus. Wenn du diesen Filter änderst, musst du keinen Cache leeren: Ein hinzugefügter Ordner wird einfach gescannt, ein entfernter einfach nicht gelesen.

Grenzen. Höchstens 1000 Icons pro Ordner und 2 MB pro Datei, einstellbar über easy_svg_pro_source_max_icons und easy_svg_pro_source_file_max_bytes. Ein Symlink, der aus dem Ordner hinauszeigt, wird abgelehnt.

Stolperfallen

• Ein fehlender Ordner scheitert lautlos. Ein Pfad, den es nicht gibt, liefert keine Icons und keine Problemzeile. Einen Tippfehler meldet dir niemand, prüfe also mit wp easy-svg icons list.
• Ordnernamen müssen eindeutig sein. /a/icons und /b/icons laufen beide als icons, gescannt wird nur der letzte. Gib den Ordnern unterschiedliche Namen oder einen slug im Manifest.
• Der Slug folgt dem Ordner, nicht dem Pfad. Benennst du einen Ordner um, bekommt er einen neuen Slug, und jeder Block, jedes Feld und jedes Template mit dem alten zeigt nichts mehr. Ein slug in der manifest.json hält den Namen fest.
• Ein belegter Name weicht von selbst aus. Gehört der gewünschte Slug schon einer anderen Sammlung, registriert sich dieser Ordner ohne Warnung als slug-2. Verschwindet die andere Sammlung, bekommt er beim nächsten Request seinen Namen zurück.
• Ein kaputtes Manifest registriert nichts. Ungültiges JSON, eine leere icons-Liste oder eine version, die neuer ist, als dieses Plugin versteht, und aus dem ganzen Ordner kommt kein Icon. Den Grund zeigen wp easy-svg icons problems und die Sammlung unter Icons → Pakete.
• Ohne Manifest scheitern Dateien leise. Ein SVG, das der Sanitizer ablehnt, wird ohne Problemzeile übersprungen. Gemeldet werden nur Dateien über der Icon-Grenze. Nimm ein Manifest oder wp easy-svg icons validate, wenn du es wissen musst.
• Jeder Ordner kostet eine Prüfung pro Request. Der Transient spart das erneute Lesen, aber die Signatur listet und prüft jeden Ordner bei jedem Request. Halte die Liste kurz.

Siehe auch

• easy_svg_pro_theme_collection_slug
• easy_svg_register_icon_collection()
• easy_svg_pro_parse_manifest
• easy_svg_pro_collection_icons
• wp easy-svg icons problems
• Tutorial: Icons aus einem Theme oder Plugin ausliefern