easy_svg_pro_source_dirs

Change which folders Easy SVG Pro scans as drop-in icon collections: add a folder outside wp-content/easy-svg-icons, or hide one you do not want.

Filter · Easy SVG Pro · Status: Stable

Every subfolder of wp-content/easy-svg-icons becomes an icon collection on its own: drop SVG files in, and they show up in the block inserter, the pickers and easy_svg_icon(). This filter hands you that list of folders before any of them is read. Add a folder that lives somewhere else, or take one out so it is not registered.

Usage

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

Applied in includes/sources/sources.php, inside boot_sources(), which runs on init at priority 9.

When to use it

Your icons live in a folder you deploy with your own code, for example wp-content/client-icons/brand, and you want them to behave exactly like a drop-in: cached, manifest aware, named by the folder.
A plugin or mu-plugin ships a large icon folder. A drop-in is cached between requests, a directory passed to easy_svg_register_icon_collection() is not, so for hundreds of files this filter is the cheaper road.
Someone left a test folder in wp-content/easy-svg-icons on a live site and you want it gone from the inserter without deleting files.

Do not use it when:

You want to choose the collection slug in code. A folder added here is named by its manifest.json or its folder name. Use easy_svg_register_icon_collection() when the slug has to be fixed in PHP.
You only want to rename the theme's own collection. That is easy_svg_pro_theme_collection_slug.

Parameters

body

$dirsstring[]

Required

Absolute paths of every directory directly inside wp-content/easy-svg-icons, as glob() with GLOB_ONLYDIR returns them. An empty array when the folder does not exist or WP_CONTENT_DIR is not defined.

Return value

returnstring[]

The folders to scan as drop-in collections. Each entry is cast to a string. Paths do not have to be inside wp-content, and trailing slashes are fine.

Default

Every directory matched by glob( WP_CONTENT_DIR . '/easy-svg-icons/*', GLOB_ONLYDIR ). Subfolders deeper than one level are not part of the list.

Examples

Add one folder outside the drop-in directory

/**
 * Register wp-content/client-icons/brand as an extra drop-in collection.
 */
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' );

The collection is named brand, or whatever slug the folder's manifest.json names.

An agency plugin that ships several icon folders

/**
 * Every subfolder of this plugin's icons/ directory becomes a collection.
 */
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' );

Give each folder a manifest.json with a slug that cannot clash, for example acme-social, so the collection name does not depend on the folder name.

Hide a folder on production only

/**
 * Keep the "sandbox" drop-in out of the inserter everywhere but locally.
 */
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' );

Only add a folder that really exists

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' );

How it works

boot_sources() runs on init at priority 9, before the free plugin's own collection (priority 10) and before the collections are handed to WordPress's Icon API (priority 11). It does nothing unless:

the licence is active and Theme & folder sources is switched on under Icons → Features, and
the free Easy SVG Support plugin provides both its sanitizer and easy_svg_harden_icon_markup(). Without either, no folder source registers anything.

Then, per request:

The theme collection is scanned first (assets/icons of parent and child theme).
The drop-in folders are globbed and passed through this filter.
Every returned path is keyed by its folder name (basename()). Two paths with the same folder name collapse into one, and the later one wins. Keying by name, not path, is what keeps the collections when a site moves to another document root.
A slug is decided for each folder name and recorded once in the option easy_svg_pro_dropin_collection_slugs, so a folder keeps its slug for good. Sites that ran before this record existed keep their old slugs, which can end in -x.
Each folder is scanned. With a manifest.json the manifest names the icons, labels and keywords; any other SVG beside it still loads under its file name. Without a manifest every *.svg directly in the folder loads (not recursive). Every file goes through the site's sanitizer and the hardener.
The slug used is the manifest's slug when nothing else holds it, else the recorded folder slug, else that slug with a number (brand-2). "Holding" means another registered collection or the free library's easy-svg.

Caching. A scan is stored in a transient named easy_svg_pro_src_ plus the md5 of the path, for a day. Its signature covers every SVG's modification time, the manifest.json and the free plugin's sanitizer file, so adding, editing or removing a file, or updating the free plugin, triggers a fresh scan on the next request. Changing this filter does not need a cache flush: a folder you add is simply scanned, one you remove is simply not read.

Limits. At most 1000 icons per folder and 2 MB per file, adjustable with easy_svg_pro_source_max_icons and easy_svg_pro_source_file_max_bytes. A symlink that points out of the folder is refused.

Pitfalls

A missing folder fails silently. A path that does not exist yields no icons and no problem row. Nothing tells you about a typo, so check wp easy-svg icons list.
Folder names must be unique. /a/icons and /b/icons are both keyed as icons, so only the last one is scanned. Give folders distinct names or a manifest slug.
The slug follows the folder, not the path. Renaming a folder gives it a new slug, and every block, field and template that named the old one renders nothing. Put a slug in manifest.json to pin the name.
A taken name moves aside on its own. If a folder's preferred slug already belongs to another collection, this one registers as slug-2 without a warning. Removing the other collection gives it its name back on the next request.
A broken manifest registers nothing. Invalid JSON, an empty icons list or a version newer than this plugin understands means the whole folder registers no icon. The reason shows in wp easy-svg icons problems and under the collection in Icons → Packs.
Without a manifest, failures are quiet. An SVG the sanitizer refuses is skipped without a problem row. Only files past the icon cap are reported. Use a manifest or wp easy-svg icons validate when you need to know.
Every folder costs a check per request. The transient avoids rereading files, but the signature still lists and stats each folder on every request. Keep the list short.

Each folder you return is read from disk and its icons are printed on your pages after sanitizing. Never return a folder that visitors or other users can write to, such as a subfolder of wp-content/uploads.

Was this page helpful?