Icons: Add APIs for collection and icon registration by t-hamano · Pull Request #11559 · WordPress/wordpress-develop

t-hamano · 2026-04-13T10:24:41Z

Use of AI Tools

Claude Opus 4.6 (1M context)

github-actions · 2026-04-13T10:28:58Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

t-hamano · 2026-04-13T10:57:57Z

I am encountering the following error.

Fatal error: Access level to Gutenberg_Icons_Registry_7_1::register() must be public (as in class WP_Icons_Registry) in /var/www/src/wp-content/plugins/gutenberg/lib/compat/wordpress-7.1/class-gutenberg-icons-registry-7-1.php on line 68

This issue will likely be resolved once the Gutenberg ref is updated in wordpress-develop.

Gutenberg_Icons_Registry_7_1::register() no longer exists in the Gutenberg trunk. Instead, WP_Icons_Registry_Gutenberg::registerI() will be a public method once WordPress/gutenberg#77260 is merged, which should resolve the issue.

Align the icon registry's internal property with WordPress core's snake_case array-key convention by renaming the registered icon property from filePath to file_path. The conversion now happens only at the registration/mapping boundary in the constructor: the generated manifest keeps the upstream camelCase `filePath` key (as produced by Gutenberg), which is read and mapped to the internal `file_path` property when each icon is registered. This updates the registry validation, allowed property keys, `get_content()` lookup, and the related docblocks and error messages, while leaving the manifest and the copy:icon-library-manifest Grunt task untouched. Co-Authored-By: Claude <noreply@anthropic.com>

Add the public icon collection and icon registration APIs on top of the snake_case icon registry. Introduces WP_Icon_Collections_Registry, icons.php (wp_register_icon/wp_unregister_icon/wp_register_icon_collection and the default registration callbacks), the collection-scoped REST routes, and the related tests. Icon properties use the internal snake_case `file_path` key established in the icon registry; the Gutenberg manifest's upstream camelCase `filePath` key is read and mapped to `file_path` at the registration boundary. Co-Authored-By: Claude <noreply@anthropic.com>

The icon registries warn via _doing_it_wrong() when a collection or icon is already registered. Because tests such as the Customize widgets suite fire `do_action( 'init' )` again after bootstrap, the default icon registration runs twice and triggers those notices, failing unrelated tests. Match the existing pattern used for font and connector registration by unhooking `_wp_register_default_icon_collections` and `_wp_register_default_icons` from `init` after the first run. Co-Authored-By: Claude <noreply@anthropic.com>

The REST icons controller now registers a per-collection route, `/wp/v2/icons/(?P<namespace>[a-z][a-z-]*)`. Add it to the expected routes list so test_expected_routes_in_schema reflects the registered routes. Co-Authored-By: Claude <noreply@anthropic.com>

The icons controller now exposes a `namespace` argument on the collection endpoint and a new per-collection route. Regenerate the QUnit fixtures so `git diff --exit-code` passes in CI. Co-Authored-By: Claude <noreply@anthropic.com>

github-actions · 2026-06-11T10:40:45Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props wildworks, mcsf, tyxla, annezazu.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Custom icons can be registered with a `file_path`, but the path was never checked before `file_get_contents()`, so a missing, unreadable, non-SVG, or non-string path emitted a raw PHP warning and a misleading "invalid SVG markup" error. Guard `get_content()` by resolving the path via `realpath()`, then requiring an `.svg` extension, a regular file, and readability, returning null with a clear message otherwise. Add tests covering valid and invalid file paths. Co-Authored-By: Claude <noreply@anthropic.com>

The collection slug pattern required a leading lowercase letter and rejected digits, which excluded legitimate plugin slugs such as `a8c` or vendor names containing numbers. Relax the validation to accept any combination of lowercase alphanumeric characters and hyphens, and update the error message and tests to match. Co-Authored-By: Claude <noreply@anthropic.com>

@SInCE

…tag. Several @SInCE 7.0.0 tags were accidentally dropped from properties and internal methods while reworking the Icons API, leaving docblocks without a version per the inline documentation standards. Restore them. Also remove the stray blank line after the opening PHP tag to match the rest of the core class files. Co-Authored-By: Claude <noreply@anthropic.com>

Derive the collection from the icon name instead of passing it separately, so an icon is always identified by a single namespaced name. The collection prefix is now required; a non-namespaced name is rejected via _doing_it_wrong(). This drops the $collection parameter from wp_register_icon()/wp_unregister_icon() and the "collection" icon property, and simplifies the cascade unregister when a collection is removed. The "core" collection is reserved for WordPress core icons. Co-Authored-By: Claude <noreply@anthropic.com>

# Conflicts: # src/wp-includes/class-wp-icons-registry.php # tests/phpunit/tests/icons/wpIconsRegistry.php

t-hamano · 2026-06-27T02:14:14Z

Update: The Gutenberg PR has been approved. This PR includes all changes for Gutenberg, but please let me know if there are any other points that need to be fixed.

The REST controller tests depend on the default core icons, but those are registered only once on `init` and the registration is then unhooked, so once another suite resets the `WP_Icons_Registry` singleton in teardown the core icons are gone. The affected tests were therefore skipped. Re-register the default icons in `set_up()` when the registry is empty so the tests run deterministically regardless of execution order, and drop the `markTestSkipped()` guards. Co-Authored-By: Claude <noreply@anthropic.com>

Relax the icon slug validation so names can start with a lowercase letter or digit and contain lowercase letters, digits, hyphens, and underscores. Many real-world icon sets use digits (e.g. html5, 500px, w3c) and some consumers want underscores, which the previous regex rejected. Co-Authored-By: Claude <noreply@anthropic.com>

Port the equivalent of WordPress/gutenberg#79686 to core: - Add WP_REST_Icon_Collections_Controller exposing /wp/v2/icon-collections and /wp/v2/icon-collections/<slug> so the editor can group icons by collection in the icon picker. - Unify the naming rules for icon controllers and the collection registry on /^[a-z0-9]([a-z0-9_-]*[a-z0-9])?$/, allowing leading digits and underscores while still requiring alphanumeric boundaries. This fixes requests such as /wp/v2/icons/bootstrap-icons/0-circle-fill that previously 404'd. - Add unit tests for the new collection controller and extend the collection registry tests to cover the updated slug rules. Co-Authored-By: Claude <noreply@anthropic.com>

t-hamano · 2026-07-07T10:47:27Z

@tyxla @mcsf, I plan to commit this by the end of this week or early next week to make it in time for the beta 1 release. Please let me know if there is anything else I should address.

Replace the legacy false === strpos() idiom with str_contains(), which expresses the intent more clearly and avoids the loose/strict comparison pitfalls of the strpos()-against-false pattern. WordPress polyfills str_contains() in wp-includes/compat.php, so it is safe on PHP 7.4. Co-Authored-By: Claude <noreply@anthropic.com>

t-hamano · 2026-07-07T11:31:29Z

88f1834 is the improvements made in WordPress/gutenberg#79927. See https://github.com/WordPress/gutenberg/pull/79927/changes#r3534498017 for more details.

mcsf

Sorry for the delay in reviewing this, @t-hamano! I've left some questions.

mcsf · 2026-07-08T13:40:44Z

 add_action( 'init', '_wp_register_default_font_collections' );

+// Icons.
+add_action( 'init', '_wp_register_default_icon_collections', 0 );


Why priority 0? I see this commit message:

Default icon collection registration runs at init priority 0 so collections exist before the Gutenberg registry override replays registered icons.

If this is still the motivation, shouldn't it be made very clear here?

Apologies, that comment was not accurate. A priority 0 is intended to ensure the core collection is registered before all other icon collections. I believe a similar approach is being taken by create_initial_post_types and create_initial_taxonomies.

mcsf · 2026-07-08T13:50:58Z

-			);
-			$content = $this->sanitize_icon_content( $content );
+			$file_path  = $this->registered_icons[ $icon_name ]['file_path'] ?? '';
+			$is_stringy = is_string( $file_path ) || ( is_object( $file_path ) && method_exists( $file_path, '__toString' ) );


The commit message in the original dev branch doesn't explain it, so:

What was the motivation for also accepting Stringable objects? The possibility of lazy evaluation?

When I implemented the initial version in #77260, I based it on the block pattern registry implementation. The purpose was to prevent critical errors, as consumers can inject any type into the file_path parameter of wp_register_icon.

mcsf · 2026-07-08T14:08:36Z

+		$defaults = array(
+			'description' => '',
+		);


We're missing type validation for description, no?

Nice catch, fixed in 8667d72

tyxla · 2026-07-08T14:27:54Z

+			'/wp/v2/icons/(?P<namespace>[a-z][a-z-]*)',
 			'/wp/v2/icons/(?P<name>[a-z][a-z0-9-]*/[a-z][a-z0-9-]*)',


Looks like we'll need to update the regexes here?

Nice catch, added the missing routes in 60bb86a.

tyxla · 2026-07-08T14:29:18Z

+			'/' . $this->rest_base . '/(?P<slug>[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)',
+			array(
+				'args'   => array(
+					'slug' => array(


This concept is called "namespace" in the icons list route param, the icon field is called collection and here we call it slug. Should we be consistent with this?

I believe unifying it under "collection" would be the most precise approach. Fixed in 8034efa

I've already left a note in the other PR, but I'm cross-posting here so that we don't miss it:

As of WordPress/gutenberg#79681, we have a consumer using namespace:

https://github.com/WordPress/gutenberg/blob/9ca1496422ab16e5350542e0e775db4370c8adc4/packages/block-library/src/icon/components/custom-inserter/index.js#L49

@type

The collection label was already type-checked, but the optional description was merged into the collection unvalidated, allowing non-string values to violate the documented @type string contract. Reject a non-string description with _doing_it_wrong() for consistency. Co-Authored-By: Claude <noreply@anthropic.com>

The icon name/namespace regexes were tightened and an icon-collections controller was added, but the expected route list in the schema test was not updated to match, causing the full-set comparison to fail. Co-Authored-By: Claude <noreply@anthropic.com>

The collection-scoped icons route used a `namespace` URL param whose value is actually a collection slug, which both collided with the REST API namespace concept and diverged from the icon `collection` field that names the same relationship. Rename it to `collection` so the same concept reads consistently across the icons endpoints. Co-Authored-By: Claude <noreply@anthropic.com>

t-hamano · 2026-07-09T07:28:21Z

Please note that the CI check will fail in this PR because a critical error occurs when the Gutenberg plugin is enabled.

PHP Fatal error:  Access level to WP_Icons_Registry_Gutenberg::register() must be public (as in class WP_Icons_Registry) in /var/www/src/wp-content/plugins/gutenberg/lib/class-wp-icons-registry-gutenberg.php on line 68

PHP Fatal error:  Access level to WP_Icons_Registry_Gutenberg::register() must be public (as in class WP_Icons_Registry) in /var/www/src/wp-content/plugins/gutenberg/lib/class-wp-icons-registry-gutenberg.php on line 68

This is because, in Gutenberg 23.5, WP_Icons_Registry_Gutenberg::register() is still a protected method.

https://github.com/WordPress/gutenberg/blob/6b232da64420402e8368ec70068a596b6dad0466/lib/class-wp-icons-registry-gutenberg.php#L68

This CI error should be resolved if the Gutenberg ref is updated to version 23.6.

mcsf · 2026-07-09T09:11:06Z

Please note that the CI check will fail in this PR because a critical error occurs when the Gutenberg plugin is enabled.
PHP Fatal error:  Access level to WP_Icons_Registry_Gutenberg::register() must be public (as in class WP_Icons_Registry) in /var/www/src/wp-content/plugins/gutenberg/lib/class-wp-icons-registry-gutenberg.php on line 68

PHP Fatal error:  Access level to WP_Icons_Registry_Gutenberg::register() must be public (as in class WP_Icons_Registry) in /var/www/src/wp-content/plugins/gutenberg/lib/class-wp-icons-registry-gutenberg.php on line 68
This is because, in Gutenberg 23.5, WP_Icons_Registry_Gutenberg::register() is still a protected method.

https://github.com/WordPress/gutenberg/blob/6b232da64420402e8368ec70068a596b6dad0466/lib/class-wp-icons-registry-gutenberg.php#L68

This CI error should be resolved if the Gutenberg ref is updated to version 23.6.

What can we do to mitigate the problem? We wouldn't want to break WP trunk for Gutenberg users. It also means that users that for some reason are stuck on Gutenberg 23.5 (and several older versions) by the time that WP 7.1 comes are at risk of fatals, right?

t-hamano · 2026-07-09T10:02:57Z

What can we do to mitigate the problem? We wouldn't want to break WP trunk for Gutenberg users. It also means that users that for some reason are stuck on Gutenberg 23.5 (and several older versions) by the time that WP 7.1 comes are at risk of fatals, right?

Yes. I think this error occurs if Gutenberg version 23.5 or lower is enabled on the WP trunk that includes this PR.

~~One approach might be to ship this PR in Beta 2, not Beta 1.~~

~~1. July 14: Gutenberg 23.6 RC1 release~~
~~2. July 15: WordPress Beta1 release~~
~~3. July 22: Gutenberg 23.6 general release~~
4. July 22: Commit this PR
~~5. July 22: WordPress Beta2 release~~

~~This way, Gutenberg 23.6 should not cause any errors as it includes the public WP_Icons_Registry_Gutenberg::register() method at the WP Beta 2 stage.~~

~~This approach may not be acceptable because the release of the new feature, the Icon API, would be delayed by one week.~~

Another approach is to release a Gutenberg 23.5 minor version immediately, making the WP_Icons_Registry_Gutenberg::register() method public.

In any case, users need to use the latest Gutenberg to prevent critical errors. Do you have any other good ideas?

Update: We plan to release Gutenberg 23.5.2 on Monday, July 13th.

mcsf · 2026-07-10T13:47:20Z

I think a quick minor Gutenberg release could make sense here, but I'll defer to @tyxla and @annezazu, especially since I'll be out for a few weeks!

tyxla · 2026-07-10T13:57:23Z

I would be fine with a minor release for this.

FWIW I've been considering whether to have one for WordPress/gutenberg#79894 so let's add that to the minor, too, if possible.

Rejects registering an icon collection when a non-string `description` is provided, matching the WordPress core validation. Refs WordPress/wordpress-develop#11559. Co-Authored-By: Claude <noreply@anthropic.com>

Aligns the Gutenberg icons REST controller with the WordPress core rename of the collection-scoping route param from `namespace` to `collection`. Refs WordPress/wordpress-develop#11559. Co-Authored-By: Claude <noreply@anthropic.com>

Rejects registering an icon collection when a non-string `description` is provided, matching the WordPress core validation. Refs WordPress/wordpress-develop#11559. Co-Authored-By: Claude <noreply@anthropic.com>

…ate description (#80113) * Icons: Rename the collection-scoping route param to `collection` Aligns the Gutenberg icons REST controller with the WordPress core rename of the collection-scoping route param from `namespace` to `collection`. Refs WordPress/wordpress-develop#11559. Co-Authored-By: Claude <noreply@anthropic.com> * Icons: Validate that the collection description is a string Rejects registering an icon collection when a non-string `description` is provided, matching the WordPress core validation. Refs WordPress/wordpress-develop#11559. Co-Authored-By: Claude <noreply@anthropic.com> * Icons: Use `collection` query param in the icon picker Follows the route param rename so the icon picker keeps filtering by collection once the core rename lands. Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: t-hamano <wildworks@git.wordpress.org> Co-authored-by: mcsf <mcsf@git.wordpress.org>

…ate description (#80113) * Icons: Rename the collection-scoping route param to `collection` Aligns the Gutenberg icons REST controller with the WordPress core rename of the collection-scoping route param from `namespace` to `collection`. Refs WordPress/wordpress-develop#11559. Co-Authored-By: Claude <noreply@anthropic.com> * Icons: Validate that the collection description is a string Rejects registering an icon collection when a non-string `description` is provided, matching the WordPress core validation. Refs WordPress/wordpress-develop#11559. Co-Authored-By: Claude <noreply@anthropic.com> * Icons: Use `collection` query param in the icon picker Follows the route param rename so the icon picker keeps filtering by collection once the core rename lands. Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: t-hamano <wildworks@git.wordpress.org> Co-authored-by: mcsf <mcsf@git.wordpress.org> Source: WordPress/gutenberg@800096f

annezazu · 2026-07-10T22:07:22Z

Ditto—totally happy with a minor release.

The icon REST routes changed on this branch: the collection-scoping route param was renamed from `namespace` to `collection`, the slug pattern was relaxed, and the `/wp/v2/icon-collections` route was added. The generated fixture was left stale, so the PHPUnit job regenerated it and failed the "version-controlled files are not modified" check. Co-Authored-By: Claude <noreply@anthropic.com>

t-hamano and others added 2 commits June 11, 2026 17:04

t-hamano force-pushed the 64847-icon-api-extend branch from de545bf to d08cbfa Compare June 11, 2026 09:00

t-hamano and others added 2 commits June 11, 2026 18:35

t-hamano mentioned this pull request Jun 11, 2026

SVG Icon API: Iteration for WordPress 7.1 WordPress/gutenberg#75715

Open

17 tasks

Icons: Regenerate REST API client fixtures.

095efe2

The icons controller now exposes a `namespace` argument on the collection endpoint and a new per-collection route. Regenerate the QUnit fixtures so `git diff --exit-code` passes in CI. Co-Authored-By: Claude <noreply@anthropic.com>

t-hamano marked this pull request as ready for review June 11, 2026 10:40

t-hamano and others added 5 commits June 13, 2026 23:15

Merge branch 'trunk' into 64847-icon-api-extend

c88e154

# Conflicts: # src/wp-includes/class-wp-icons-registry.php # tests/phpunit/tests/icons/wpIconsRegistry.php

github-actions Bot mentioned this pull request Jun 27, 2026

PHP backports for WP 7.1 WordPress/gutenberg#79304

Open

t-hamano and others added 6 commits June 27, 2026 11:16

Merge branch 'trunk' into 64847-icon-api-extend

42e61b9

Merge branch 'trunk' into 64847-icon-api-extend

510ad27

Merge branch 'trunk' into 64847-icon-api-extend

7cb12a2

t-hamano mentioned this pull request Jun 30, 2026

Build/Test Tools: Bump bundled Gutenberg #12009

Closed

pento force-pushed the trunk branch from 3af2d27 to 64ede28 Compare July 6, 2026 03:10

t-hamano mentioned this pull request Jul 7, 2026

Use modern PHP string functions instead of strpos/substr WordPress/gutenberg#79927

Merged

mcsf reviewed Jul 8, 2026

View reviewed changes

tyxla reviewed Jul 8, 2026

View reviewed changes

t-hamano and others added 4 commits July 9, 2026 15:55

Merge branch 'trunk' into 64847-icon-api-extend

5f747b3

t-hamano mentioned this pull request Jul 10, 2026

Icons: Filter the icon library picker by collection WordPress/gutenberg#79681

Merged

t-hamano mentioned this pull request Jul 10, 2026

Icons: Unify collection-scoping route param on collection and validate description WordPress/gutenberg#80113

Merged

This was referenced Jul 11, 2026

[Gutenberg 23.5.2] Icons: Make WP_Icons_Registry::register() public WordPress/gutenberg#80139

Open

Icons: Add APIs for collection and icon registration: SHA update test t-hamano/wordpress-develop#2

Closed

t-hamano mentioned this pull request Jul 11, 2026

Icons: Add APIs for collection and icon registration: SHA update test #12483

Closed

		'/wp/v2/icons/(?P<namespace>[a-z][a-z-]*)',
		'/wp/v2/icons/(?P<name>[a-z][a-z0-9-]/[a-z][a-z0-9-])',

Uh oh!

Conversation

t-hamano commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Use of AI Tools

Uh oh!

github-actions Bot commented Apr 13, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

t-hamano commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

t-hamano commented Jun 27, 2026

Uh oh!

t-hamano commented Jul 7, 2026

Uh oh!

t-hamano commented Jul 7, 2026

Uh oh!

mcsf left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t-hamano commented Jul 9, 2026

Uh oh!

mcsf commented Jul 9, 2026

Uh oh!

t-hamano commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mcsf commented Jul 10, 2026

Uh oh!

tyxla commented Jul 10, 2026

Uh oh!

annezazu commented Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

t-hamano commented Apr 13, 2026 •

edited

Loading

t-hamano commented Apr 13, 2026 •

edited

Loading

github-actions Bot commented Jun 11, 2026 •

edited

Loading

t-hamano commented Jul 9, 2026 •

edited

Loading