easy_svg_register_icon_collection()

Function · Easy SVG Pro · Status: Stable

This is the one call that turns your own icons into an Easy SVG collection. Give it a slug, a label and a folder of SVG files, and the icons appear in the block inserter, the icon pickers, easy_svg_icon() and WP-CLI under the address slug/icon. You choose the slug in code, so it never changes behind your back.

Usage

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

Defined in the global namespace in includes/sources/sources.php, only if no function of that name exists yet. Call it on init at the default priority 10.

When to use it

• A theme keeps its icons somewhere other than assets/icons, for example resources/svg.
• A plugin or mu-plugin ships icons and the address has to be fixed in code, because templates and blocks in the field already use it.
• A snippet needs a handful of icons that are generated in PHP and you control the markup completely.

Do not use it when:

• The icons sit in the theme's assets/icons. They are read automatically; rename them with easy_svg_pro_theme_collection_slug.
• The folder holds hundreds of files. A directory registered here is scanned on every request without a cache. Add it as a drop-in with easy_svg_pro_source_dirs instead, which is cached.
• Editors should change the icons in wp-admin. Use an icon set (Icons → Icon Sets) for that.

Parameters

Return value

Default

No collection is registered until you call it. There is no default slug or label.

Examples

A folder in your theme

/**
 * Register the theme's resources/svg folder as the "acme" collection.
 */
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 now call easy_svg_icon( 'acme/phone' ).

An agency plugin with one collection per brand

/**
 * One collection per brand folder, each with a fixed 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' );

Put a manifest.json in each folder to give the icons readable labels and search keywords. The manifest names the icons, never the collection.

A few icons from markup you control

/**
 * Two simple shapes built in code. This markup is registered as it stands.
 */
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' );

Defensive: register only when Pro will really use it

function acme_register_icons_safely() {
	if ( ! function_exists( 'easy_svg_register_icon_collection' ) ) {
		return; // Easy SVG Pro is not active.
	}

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

	if ( ! is_dir( $dir ) ) {
		return; // A typo here would register nothing without a word.
	}

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

How it works

1. Gate. The call does nothing unless the licence is active and Theme & folder sources is on under Icons → Features. There is no notice; it simply returns.
2. Array. An array is handed to the registry as it is. No sanitizer, no hardener, no check of the slugs. The collection is recorded as coming from code.
3. Folder. A folder needs the free plugin's sanitizer and easy_svg_harden_icon_markup(); without either it registers nothing. The folder is scanned like a drop-in: with a manifest.json the manifest decides each icon's name, label and keywords, and any SVG beside it still loads under its file name; without a manifest every *.svg directly in the folder loads. Limits: 1000 icons and 2 MB per file, adjustable with easy_svg_pro_source_max_icons and easy_svg_pro_source_file_max_bytes.
4. Filters. The icons pass easy_svg_pro_collection_icons. Files that could not be used are recorded as problems, visible in wp easy-svg icons problems and in Icons → Packs.
5. Register. If at least one icon is left, it is added to the registry and easy_svg_pro_registered_collection fires.
6. Render. easy_svg_icon( 'acme/phone' ) reads the registry when the page renders. On init priority 11 the registry is handed to WordPress's Icon API (WordPress 7.1 or newer, with Multiple collections switched on), which is where the core Icon block gets its icons.

No cache for folders. Unlike the theme folder and the drop-ins, a directory passed here is not stored in a transient. Every request reads and sanitizes every file again. That is fine for twenty icons and noticeable for five hundred.

Pitfalls

• Priority 10, not later. The registry is handed to the core Icon API on init priority 11. Register later and easy_svg_icon() still finds the icons, but the Icon block's inserter does not list them.
• Not at file level. Call it from an init callback. At file level of your plugin the function may not exist yet (plugins load in alphabetical order), and the free plugin's sanitizer and the licence check are only certain to be ready on init.
• The same slug merges. A second call with the same slug, or an icon set or folder that already uses it, does not replace the collection: icons are added by name and the last label wins. Pick slugs that only you use, such as a prefix.
• A manifest does not rename the collection. A "slug" in the folder's manifest.json is ignored here on purpose, so that templates calling your slug keep working.
• Silence on failure. A wrong path, a switched off feature or a missing licence all look the same: no collection. wp easy-svg icons list shows what really registered.
• Array keys are not checked. A key like My Icon is used as it stands and produces an address nothing can call. Use lowercase slugs.

Related

• 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: Ship icons from a theme or plugin