wp easy-svg icons import

WP-CLI command · Easy SVG Pro · Status: Stable

This command takes a folder of SVG files from anywhere on the server and turns it into an icon collection. Every file is cleaned with the site's sanitizer and hardener and then written into wp-content/easy-svg-icons/<slug>/. On the next page load that folder registers as a collection and its icons appear in the block inserter, the pickers and easy_svg_icon().

Usage

wp easy-svg icons import <dir> --collection=<slug> [--label=<text>]

When to use it

• You received a folder of icons from a designer or a client and want it on the site as its own collection, without uploading files one by one.
• A deploy script should put a brand's icons on a server that does not get them from the theme repository.
• You want the icons as files on disk (a drop-in folder), not in the database as an icon set.

Do not use it when:

• You have a pack ZIP with a manifest.json. Use wp easy-svg pack import, which keeps the manifest's labels and stores an icon set.
• The icons belong to a theme you control. Put them into the theme's assets/icons folder and commit them, or register them with easy_svg_register_icon_collection().
• The server's file system is read only or rebuilt on each deploy. The files would be lost.

Parameters

Return value

Default

There is no default collection. --collection is required.

Examples

Import a client's icons

wp easy-svg icons import ~/Downloads/acme-icons --collection=acme

Warning: Skipped /home/me/Downloads/acme-icons/logo-old.svg: not-svg
Success: Copied 47 file(s) into /var/www/wp-content/easy-svg-icons/acme; they register as the "acme" collection on the next load.

Validate first, then import, in a deploy script

#!/usr/bin/env bash
set -euo pipefail

SRC="build/icons"
SLUG="acme"

wp easy-svg icons validate "$SRC" --strict
wp easy-svg icons import "$SRC" --collection="$SLUG"
wp easy-svg icons list

Replace a collection cleanly

The command never deletes files, so an icon removed from the source stays on the site. Clear the folder first when you want an exact copy:

DEST="$(wp eval 'echo WP_CONTENT_DIR;')/easy-svg-icons/acme"
rm -f "$DEST"/*.svg
wp easy-svg icons import ./icons --collection=acme

Defensive: refuse a path that does not exist

SRC="./icons"
if [ ! -d "$SRC" ] || [ -z "$(ls -A "$SRC"/*.svg 2>/dev/null)" ]; then
	echo "No SVG files in $SRC, nothing imported." >&2
	exit 1
fi
wp easy-svg icons import "$SRC" --collection=acme

How it works

1. The guard checks the licence and the WP-CLI feature.
2. --collection is turned into a slug and the target folder is created with wp_mkdir_p().
3. The command needs the sanitizer from Easy SVG Support and easy_svg_harden_icon_markup(). Nothing is ever written unsanitized.
4. An index.php stub is added so the folder cannot be listed in a browser.
5. Each *.svg from <dir> gets a slug from its file name, is read, sanitized and hardened, and is written as <slug>.svg. Skipped files are reported with the same reasons as wp easy-svg icons validate, plus unwritable when the file could not be written.
6. The folder's scan cache (a transient) is deleted, so the next request rescans it.
7. The success line names the slug the folder will really register under. That is usually the folder name, but a folder already on record keeps the slug it was first registered with, and a manifest.json in the folder can name another slug.

The collection only appears while Theme & folder sources is switched on under Icons → Features.

Pitfalls

• --label does nothing. Put a manifest.json with a label into the target folder if the collection needs a readable name.
• A wrong source path still creates the folder. The target folder and its index.php are created before the source is read. A typo in <dir> prints Copied 0 file(s) and exits 0, and leaves an empty collection folder behind.
• Nothing is ever deleted. Files with the same slug are overwritten, everything else in the target folder stays. Removing an icon from your source does not remove it from the site.
• Files are renamed. Odd Name.svg is stored as odd-name.svg. Templates use the slug, not the original file name.
• No size cap, no manifest. Files are not checked against the 2 MB source limit at import time and a manifest.json in the source folder is not copied. A file over the limit is copied and later reported as too-large.
• Turn on the feature before the first import. The slug a folder gets is recorded the first time Theme & folder sources scans the drop-in directory. On a site where that never happened, existing folders keep the old naming for compatibility and register with a -x suffix (acme-x). The success line says so. Switch on Theme & folder sources and load one page before you import, and read the slug from the success line, not from your command.
• Exit code 0 with warnings. Skipped files do not fail the command. Run validate --strict first if a partial import should stop your pipeline.

Related

• wp easy-svg icons validate
• wp easy-svg pack import
• easy_svg_pro_source_dirs