Icons: Add APIs for collection and icon registration#77260
Merged
Conversation
t-hamano
commented
Apr 13, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds a collection-based registration layer to the Icons API, enabling plugins/themes to register their own SVG icon collections and icons, and extends the REST API to query icons by collection.
Changes:
- Introduces an icon collections registry and public wrapper functions for registering/unregistering icon collections and icons.
- Refactors
WP_Icons_Registry_Gutenbergto require acollectionfor icon registration and to qualify stored icon names as{collection}/{icon}. - Extends the icons REST controller with a collection-scoped listing route and updates the Icon block to request all icons when opening the inserter.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| phpunit/experimental/class-wp-icons-registry-gutenberg-test.php | Updates/extends registry tests for collection-aware registration behavior. |
| packages/block-library/src/icon/edit.js | Changes icon list fetching parameters when inserter is open. |
| lib/load.php | Loads new 7.1 compat files for collections + icons API wrappers. |
| lib/compat/wordpress-7.1/icons.php | Adds public wrapper functions and default collection/icon registration hooks. |
| lib/compat/wordpress-7.1/class-wp-icon-collections-registry.php | New singleton registry for icon collections with basic CRUD. |
| lib/class-wp-rest-icons-controller-gutenberg.php | Adds collection-scoped icons route and includes collection in REST schema/response. |
| lib/class-wp-icons-registry-gutenberg.php | Refactors registration to be collection-based and adds unregister(). |
Comments suppressed due to low confidence (1)
phpunit/experimental/class-wp-icons-registry-gutenberg-test.php:57
- The helper comment says it invokes
register"despite it being private", butWP_Icons_Registry_Gutenberg::register()is now public. Either update the comment (and consider calling the method directly instead of using reflection) to keep the test intent clear.
/**
* Invokes WP_Icons_Registry_Gutenberg::register despite it being private
*
* @param string $icon_name Icon name (without namespace prefix).
* @param array $icon_properties Icon properties (label, content, filePath, collection).
* @return bool True if the icon was registered successfully.
*/
private function register( $icon_name, $icon_properties ) {
$method = new ReflectionMethod( $this->registry, 'register' );
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+40
to
+57
| * Registers a new icon. | ||
| * | ||
| * @param string $icon_name Icon name including namespace. | ||
| * @param array $args { | ||
| * List of properties for the icon. | ||
| * | ||
| * @type string $label Required. A human-readable label for the icon. | ||
| * @type string $collection Required. The slug of a registered icon collection that this icon belongs to. | ||
| * @type string $content Optional. SVG markup for the icon. | ||
| * If not provided, the content will be retrieved from the `filePath` if set. | ||
| * If both `content` and `filePath` are not set, the icon will not be registered. | ||
| * @type string $filePath Optional. The full path to the file containing the icon content. | ||
| * } | ||
| * @return bool True if the icon was registered successfully, else false. | ||
| */ | ||
| function wp_register_icon( $icon_name, $args ) { | ||
| return WP_Icons_Registry::get_instance()->register( $icon_name, $args ); | ||
| } |
There was a problem hiding this comment.
The wp_register_icon() docblock says $icon_name includes a namespace, but the exposed API and the registry implementation now expect an unqualified icon slug (with the collection provided in $args['collection']). Update the param docs to match the actual accepted format to avoid consumers passing collection/icon and getting _doing_it_wrong failures.
Member
There was a problem hiding this comment.
Why not keep registration the same and just require collection from $args? The wp_unregister_icon can remain the same as it is now.
Contributor
Author
There was a problem hiding this comment.
Fixed in 69a5551
Furthermore, based on #77260 (comment), I have made the parameter optional.
Member
There was a problem hiding this comment.
Furthermore, based on #77260 (comment), I have made the parameter optional.
So it would default to core if collection is omitted?
Contributor
Author
There was a problem hiding this comment.
Yes. I don't have a strong opinion on whether the collection should be a required parameter. What do you think?
Member
There was a problem hiding this comment.
As long as intent and results are documented, I also don't have a strong opinion here.
What happens if I re-register the star icon with the default collection? Will the core icon be replaced, or do I get a "doing it wrong" warning?
Contributor
Author
There was a problem hiding this comment.
We get a "doing it wrong" warning.
register_block_type outputs "doing it wrong", but register_block_pattern has its pattern replaced. I'm a little unsure about which pattern to follow for the icon registration.
|
Size Change: +9 B (0%) Total Size: 7.82 MB 📦 View Changed
ℹ️ View Unchanged
|
t-hamano
commented
Apr 13, 2026
| * Arguments for registering an icon collection. | ||
| * | ||
| * @type string $label Required. A human-readable label for the icon collection. | ||
| * @type string $description Optional. A human-readable description for the icon collection. |
Contributor
Author
There was a problem hiding this comment.
I haven't decided yet whether to visually display the collection description, but it probably won't cause any problems if it's included.
t-hamano
added a commit
to t-hamano/wordpress-develop
that referenced
this pull request
Apr 13, 2026
Expose public APIs for registering third-party SVG icons by grouping them
into collections. Every icon is associated with a single collection
(defaulting to `core`), and icons are uniquely identified by
`{collection-slug}/{icon-slug}`. Unregistering a collection cascades to
all icons within it, and the same icon slug may coexist across different
collections.
New `WP_Icon_Collections_Registry` singleton stores collections.
`WP_Icons_Registry::register()` becomes public, requires a `collection`
property, and gains a matching `unregister()` method. Wrapper functions
`wp_register_icon_collection()`, `wp_unregister_icon_collection()`,
`wp_register_icon()`, and `wp_unregister_icon()` are introduced, and the
default `core` collection plus bundled icons are registered on `init`.
The REST controller gains a `/wp/v2/icons/<namespace>` route for
collection-scoped listings and exposes a `collection` field in responses.
Ports the equivalent functionality from the Gutenberg plugin
(WordPress/gutenberg#77260) to Core, along with covering unit tests.
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
|
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 If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
|
Flaky tests detected in 306ac80. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/28235261307
|
Introduce a singleton registry class that lets plugins register icon collections with a label, description, and categories. This provides the foundation for a `wp_register_icon_collection()` wrapper and for grouping icons in the editor UI. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Expose wp_register_icon_collection() / wp_unregister_icon_collection() as the public API for plugins, and register a default 'wordpress' collection on init so the registry is populated out of the box. Wire the new files into lib/load.php so they run under the WP 7.1 compat layer. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Ensures every icon belongs to a registered collection so the collections registry can be relied on as the source of truth. Default icon collection registration runs at init priority 0 so collections exist before the Gutenberg registry override replays registered icons. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
…hooks Moves core icon registration out of the registry constructor into a `gutenberg_register_icons` action and registers default collections via `gutenberg_register_icon_collections`. Both hooks remove the matching core actions (`_wp_register_default_icons` / `_wp_register_default_icon_collections`) when present, so the Gutenberg plugin owns registration end-to-end and stays in sync with future core registration hooks without double-registering. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Exposes a public registration API on top of the icons registry by widening `register` visibility and adding a matching `unregister` method on `WP_Icons_Registry_Gutenberg`. This lets plugins register icons without reaching into reflection and lets the Gutenberg registration paths call the public API directly. `gutenberg_register_icons` runs at the default priority so the registry override at priority 1 has already replaced the core singleton, allowing the wrapper to resolve the Gutenberg instance through `WP_Icons_Registry::get_instance()`. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Removes the 'categories' property from the collection registration API and its validation. Category support adds a second axis of grouping on top of collections and is best introduced as a follow-up once the base collection/icon registration API has settled, rather than landing both at once. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Allow clients to request icons limited to a specific registered collection via /wp/v2/icons?collection=<slug>. Without this, fetching icons for a given collection would require downloading all registered icons and filtering on the client, which scales poorly once large third-party collections are registered. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
# Conflicts: # lib/class-wp-icons-registry-gutenberg.php # lib/compat/wordpress-7.0/class-wp-icons-registry.php # phpunit/experimental/class-wp-icons-registry-gutenberg-test.php
The trunk merge pulled in file_path registration tests that used an unregistered 'test-plugin' collection and a non-.svg temp file. After the icons API refactor, register() rejects unregistered collections and get_content() requires a .svg extension, so these tests failed. Use the registered 'test-collection' and the create_temp_icon_file helper. Co-Authored-By: Claude <[email protected]>
Member
|
What is missing / necessary to move this one forward? |
Contributor
Author
|
I believe this PR has been approved and is ready for release, but I have one concern. If custom icons are registered through this new API, they will all become selectable in the Icon block. What if consumers want to centrally manage their own icon sets through this API but do not want to expose them in the icon block? If we ship this PR, I believe we need to consider this point simultaneously. I am thinking that we may need to implement some kind of parameters, for example, as follows. // Only icons with "show_in_rest" set to true will be available in the Icon block.
wp_register_icon( 'my-icons/star', array(
'label' => 'Star',
'content' => '<svg/></svg>',
'show_in_rest' _> true,
) );
// Icons other than these are not exposed to the REST API, but can be retrieved using `wp_get_icon()`.
wp_register_icon( 'my-icons/cog', array(
'label' => 'Cog',
'content' => '<svg/></svg>',
) );I believe this option would be beneficial for us as well. The |
Member
|
If we want to hide an icon from the Icon block, then We could add a very specific |
Member
I feel like these specific declarations could be done in an iteration. I don't see why they would block the first version of icon registration API. On the contrary - if we open the icon registration API we would get feedback from developers about what additional registration flags they're missing. |
Contributor
Author
|
Thanks for the feedback! So, shall I smoke test this PR again and if there are no issues, we can ship it? |
Member
|
Yes, I'm personally fine with iterating separately with these flags. @mcsf WDYT? |
Contributor
Fine with me too! I'd like us to have a good look at flags well before 7.1, but — yes — it's fine to iterate. :) |
The trunk merge left two require statements for the WordPress 7.1 icons.php compat file: one inside the WP_REST_Controller block and one at the top level. Because gutenberg_register_default_icon_collections() is not guarded by function_exists(), loading the file twice triggered a fatal "Cannot redeclare" error. Keep the unconditional top-level require (matching trunk) and drop the duplicate inside the REST block. Co-Authored-By: Claude <[email protected]>
This was referenced Jun 29, 2026
Contributor
Author
I'm considering what name would be best, but icons aren't just used in the Icon block. The icon picker might be introduced in the future to change icons in the Navigation block, Details block, and so on. With that in mind, Some of my ideas:
|
Contributor
|
It's tricky...
|
Member
There should be the |
SainathPoojary
pushed a commit
to SainathPoojary/gutenberg
that referenced
this pull request
Jun 29, 2026
* Icons: Add WP_Icon_Collections_Registry for icon collection registration Introduce a singleton registry class that lets plugins register icon collections with a label, description, and categories. This provides the foundation for a `wp_register_icon_collection()` wrapper and for grouping icons in the editor UI. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Add wrapper functions and default icon collection registration Expose wp_register_icon_collection() / wp_unregister_icon_collection() as the public API for plugins, and register a default 'wordpress' collection on init so the registry is populated out of the box. Wire the new files into lib/load.php so they run under the WP 7.1 compat layer. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Require collection when registering icons in Gutenberg registry Ensures every icon belongs to a registered collection so the collections registry can be relied on as the source of truth. Default icon collection registration runs at init priority 0 so collections exist before the Gutenberg registry override replays registered icons. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Register default icons and collections via Gutenberg-specific hooks Moves core icon registration out of the registry constructor into a `gutenberg_register_icons` action and registers default collections via `gutenberg_register_icon_collections`. Both hooks remove the matching core actions (`_wp_register_default_icons` / `_wp_register_default_icon_collections`) when present, so the Gutenberg plugin owns registration end-to-end and stays in sync with future core registration hooks without double-registering. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Add wp_register_icon / wp_unregister_icon public API Exposes a public registration API on top of the icons registry by widening `register` visibility and adding a matching `unregister` method on `WP_Icons_Registry_Gutenberg`. This lets plugins register icons without reaching into reflection and lets the Gutenberg registration paths call the public API directly. `gutenberg_register_icons` runs at the default priority so the registry override at priority 1 has already replaced the core singleton, allowing the wrapper to resolve the Gutenberg instance through `WP_Icons_Registry::get_instance()`. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Drop category support from icon collections Removes the 'categories' property from the collection registration API and its validation. Category support adds a second axis of grouping on top of collections and is best introduced as a follow-up once the base collection/icon registration API has settled, rather than landing both at once. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Filter REST icons endpoint by collection slug Allow clients to request icons limited to a specific registered collection via /wp/v2/icons?collection=<slug>. Without this, fetching icons for a given collection would require downloading all registered icons and filtering on the client, which scales poorly once large third-party collections are registered. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Add collection-scoped REST route and unify default slug to "core" Exposes `/wp/v2/icons/<namespace>` alongside the existing list and single-item routes, mirroring the hierarchical URL style used by block-types. The same `get_items` handler serves both the global list and the collection-scoped listing via the URL-captured `namespace` parameter, which is also formally declared in `get_collection_params`. The default icon collection slug is renamed from `wordpress` to `core` so that it matches the namespace prefix (`core/`) used by bundled icons, removing the confusing split between namespace and collection identifiers. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Decouple icon name from collection slug at the public API layer Callers of `wp_register_icon` now pass an unqualified icon name (e.g. `arrow-left`) together with a `collection` slug, instead of encoding both into a single namespaced string (`core/arrow-left`). The registry continues to key storage by `<collection>/<name>` internally so that the existing single-item REST route, cross-collection name-collision protection, and `is_registered`/`get_registered_icon` lookups keep working without broader changes. The REST response is reshaped to match: icons now expose separate `collection` and `name` fields instead of a single namespaced `name`, which lines up with the hierarchical `/icons/<collection>` route added earlier and avoids clients having to parse the slash-delimited form. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Keep namespaced name in REST response and delegate to parent The previous commit reshaped the icon response to return an unqualified `name` plus a separate `collection` field, but that diverges from the namespaced identifier clients already use to address single items via `/icons/<collection>/<name>`. Restore the namespaced `name` so the response value can be used as-is for lookups, and keep `collection` as an additional field for convenience. Reimplement the override as a thin wrapper around the parent method to avoid duplicating the base field-filtering logic. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Update registry tests for unqualified-name registration Rework the existing tests to match the current registration contract: callers pass an unqualified icon name together with a `collection` slug, and the registry stores items under a `<collection>/<name>` key. Set up a test collection in `set_up`/`tear_down` so the registration path has a valid collection to target, and refresh the invalid-name fixtures to reflect that slashes are now rejected at input rather than required. Add coverage for the collection requirement itself (missing / non-string / unregistered collection) and for cross-collection name reuse, since the split between name and collection is the core behavior that differs from the previous namespaced-name design. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Rename gutenberg_register_icons to gutenberg_register_default_icons Makes the bootstrap function's intent explicit: it specifically seeds the default `core` collection from the bundled manifest, mirroring the naming of `gutenberg_register_icon_collections` which seeds the default collection itself. The prior generic name was easy to mistake for a public registration helper. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Rename gutenberg_register_icon_collections for naming parity Matches the earlier rename of the icon bootstrap function to `gutenberg_register_default_icons`, so both helpers that seed the bundled defaults share a `_default_` marker and read as clearly internal rather than part of the public registration API. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icon block: Request full icon list without pagination The inserter needs every registered icon to populate its picker, but the default `getEntityRecords` request paginates to the first page only, which silently truncates the list once more than a page's worth of icons are registered (e.g. once plugins contribute their own collections). Passing `per_page: -1` forces the resolver's chunked fetch path so the picker always reflects the full registry. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Align variable assignment formatting with WPCS Matches the WordPress coding standard's variable-alignment rule, so phpcbf no longer rewrites these lines on contributors' pre-commit runs. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Cascade icon removal when unregistering a collection Unregistering a collection previously left its icons in the icons registry, which produced orphaned entries still reachable through `/wp/v2/icons` and `/wp/v2/icons/<collection>/<name>` even though the collection-scoped route returned 404. Cascade the removal so the two registries stay consistent, and add a regression test covering both the cascade and the fact that icons in unrelated collections are left alone. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Take collection as a separate argument in register/unregister Lifts the collection slug out of the `$args` array and the qualified `<collection>/<name>` string into its own required parameter on both `wp_register_icon`/`wp_unregister_icon` and the underlying registry methods. The symmetric `( $icon_name, $collection, ... )` shape makes the dependency between an icon and its collection explicit at the call site, avoids callers having to manually concatenate the qualified name just to remove an icon, and keeps the public API in line with the internal storage convention where the two values are always tracked separately. The collection-cascade in `WP_Icon_Collections_Registry::unregister` is updated accordingly to pass the unqualified name and slug to the new signature. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Use __() for the default collection label `_x()` takes a context string as its second argument, but the call was passing the text domain, so the string was being registered with an unintended context and never picking up the translation. Switch to `__()` so the label is translatable via the `gutenberg` text domain the same way as the surrounding strings. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Fix word order in manifest validation error message The existing message read "valid a \"filePath\"" due to a transposed article. Correct it to "a valid \"filePath\"" so the error is readable and translatable in a natural form. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Use matching version in collection unregister _doing_it_wrong The `_doing_it_wrong` call in `WP_Icon_Collections_Registry::unregister` referenced a future `21.4.0` marker, but the rest of this class (and the surrounding icons API it ships with) consistently reports `7.1.0` as the introduction version. Align the version argument so all `_doing_it_wrong` notices from this file point at the same release. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Guard collection registration against non-array properties Without this check, passing anything other than an array as the second argument (e.g. null, a string, or a forgotten argument from a partial refactor) reached `array_keys` / `array_fill_keys` and produced a PHP type error or warning instead of a clean `_doing_it_wrong` notice. Fail early with the same pattern used for the other validation branches so misuse is surfaced as a developer warning and the registration simply returns false. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Validate the namespace query param shape at the REST boundary The URL-segment route already restricts the capture to the collection slug pattern, but the same parameter as a query string had only a `string` type check. Adding the matching `pattern` lets `rest_validate_request_arg` reject malformed input with a 400 before the handler runs, instead of funnelling everything through the 404-on-unregistered-collection path. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Exercise each invalid-name case individually in the data provider `test_register_invalid_name` was annotated with `@dataProvider` but ignored the argument and looped over the provider manually, so every run received an array (e.g. `[ 'Plus' ]`) as the name and only the non-string branch of the validator was actually hit. Accept `$name` from the provider and drop the manual loop so each case — slash, uppercase, leading underscore, non-string — is covered as a separate assertion in the failure output. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Target the Gutenberg icons registry directly in cascade removal The cascade fetched the icons registry via the base class singleton, which stays in sync with the Gutenberg subclass only after `gutenberg_override_wp_icons_registry()` has run. Anything that resets the subclass singleton on its own (notably the PHPUnit `tear_down` between tests) leaves the two pointers diverged, and the cascade then iterates a stale instance and silently no-ops -- which is exactly what made `test_unregister_collection_cascades_to_icons` fail intermittently. The collections registry is shipped only with Gutenberg and only Gutenberg-registered icons carry a `collection` field for the cascade to match on, so resolving to `WP_Icons_Registry_Gutenberg` directly is both accurate and removes the singleton-sync dependency. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Add backport changelog entry for 7.1 Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Add unregister tests and relocate cascade test Cover unregister() success and unknown-icon paths in the icons registry test, and move the collection-cascade test out to the collections suite where it belongs. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icons: Add unit tests for WP_Icon_Collections_Registry Mirror the coverage in core's tests/phpunit/tests/icons/wpIconCollectionsRegistry.php so the Gutenberg copy of the collections registry is exercised the same way, including the cascade-to-icons behavior via the Gutenberg icons registry. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Icon block: Drop unused per_page query arg The icons REST controller does not paginate, so passing { per_page: -1 } has no effect and only adds a redundant query parameter. * Icon collections registry: Use a plain list for allowed property keys Replace the array_fill_keys/array_key_exists pair with a plain list checked via in_array, since only two keys are permitted and the indirection adds no value at this scale. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * Fix incorrect WP version Co-authored-by: Miguel Fonseca <[email protected]> * Icons: Keep collection inside $args on wp_register_icon Reverts the public registration wrapper to the original `wp_register_icon( $icon_name, $args )` shape and lets `collection` travel as a required key inside `$args`, alongside `label`, `content`, and `filePath`. The unqualified-name benefit of the previous change only applied to `wp_unregister_icon`, where callers no longer have to concatenate `<collection>/<name>` themselves; on the registration side the qualified-name issue never existed, so splitting `collection` out as a positional parameter just for symmetry was unnecessary churn for callers. `wp_unregister_icon( $icon_name, $collection )` and the underlying registry methods are left as is. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * Icons: Default collection to "core" when omitted on register Treat the `collection` property of `WP_Icons_Registry::register()` as optional and fall back to the built-in `core` collection when callers do not specify one. The validation that previously rejected a missing collection now only fires when a non-string value is passed; an unregistered collection slug still triggers `_doing_it_wrong`. Plugin authors registering a small number of icons no longer need to know about the collection concept at all — they can register icons directly into `core` by omitting the field. Authors that want their own namespace can still pass `collection` explicitly after registering a collection through `wp_register_icon_collection()`. The internal docblock and the `wp_register_icon` wrapper docblock are updated to mark `collection` as optional with the new default. The `test_register_requires_collection` test is replaced with `test_register_defaults_collection_to_core`, which asserts that an omitted collection lands the icon under `core/<name>`. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * Icon collections registry: Use strict comparison in in_array Adds the `true` strict-mode argument to the allowed-keys check so that property names are compared by both type and value, satisfying WPCS WordPress.PHP.StrictInArray and matching the rest of the file's strict-typed validation. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * Icons: Clarify default collection description as "Core" Aligns the wording with the slug ("core") so the description reflects the collection identity rather than its default-registration status. * Icons: Use snake_case `file_path` key in PHP icon manifest and registry The generated `manifest.php` and the PHP icon registry exposed the icon path under a camelCase `filePath` key, which is inconsistent with PHP/WP array-key conventions. Rename it to `file_path` across the manifest PHP generator, both registry classes, and the test docblock. The `manifest.json` source intentionally keeps `filePath` (JS convention). Because the Gutenberg override inherits `get_content()` from the base class, also override `get_content()` in `WP_Icons_Registry_Gutenberg` so content is read from the `file_path` property even when the base class comes from WordPress core (which may still use `filePath`), preventing a key mismatch that would silently break icon content retrieval. Co-Authored-By: Claude <[email protected]> * Add backport changelog * Icons: Keep camelCase filePath in manifest, convert to file_path only in registry The previous commit renamed the icon path key to snake_case file_path across both the generated manifest.php and its generator. The manifest mirrors the JS manifest.json, which uses camelCase filePath, so the generated PHP manifest should keep filePath for consistency with its source. Revert the generator and manifest.php back to filePath. The PHP registry still exposes the path as file_path (PHP/WP array-key convention), so register_collection now reads the camelCase filePath from the manifest and converts it to file_path when registering. This confines the filePath-to-file_path conversion to the registry boundary. Co-Authored-By: Claude <[email protected]> * Icons: Rename icon registration property from filePath to file_path Align the icon registration API property with WordPress snake_case conventions following the base branch change. The manifest JSON key (`$icon_data['filePath']`) stays camelCase since it mirrors the JS manifest format. Co-Authored-By: Claude <[email protected]> * Icons: Register icons by namespaced "collection/name" string Replace the separate icon name and collection arguments with a single namespaced name in the form "collection/icon-name" (e.g. "core/arrow-left"), mirroring how block types are named. The collection is now derived from the name string instead of a `collection` property, and `wp_unregister_icon` takes the same namespaced name so the register/unregister pair stays symmetric. Names without a prefix still default to the "core" collection. Co-Authored-By: Claude <[email protected]> * Icons: Validate icon file path before reading content 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()` with the same validation core uses in `WP_Block_Patterns_Registry`: resolve via `realpath()`, then require an `.svg` extension, a regular file, and readability, returning null with a clear message otherwise. Override `get_content()` in `WP_Icons_Registry_Gutenberg` as well so the validation applies when the base `WP_Icons_Registry` is provided by core instead of the compat shim. Add tests covering valid and invalid file paths. Co-Authored-By: Claude <[email protected]> * Icons: Preserve original priority when removing core init actions has_action() returns the registered priority (or false), which is 0 for the priority-0 hooks. The previous truthy check skipped removal at priority 0, and remove_action() assumed the default priority 10. Capture the returned priority, compare with !== false, and pass it to remove_action() so the core actions are removed regardless of priority. Co-Authored-By: Claude <[email protected]> * Icons: Allow digits in icon collection slugs Mirror register_block_type's name validation by accepting lowercase alphanumeric characters and hyphens. The previous rule rejected digits, which blocked legitimate slugs such as "i18n" or icon variations that include numbers. Update the slug tests accordingly: digit-containing slugs are now valid, and underscores remain rejected. Co-Authored-By: Claude <[email protected]> * Icons: Add unit tests for the `file_path` icon property The registry rename to snake_case `file_path` only updated test docblocks without exercising the property. Cover registering via `file_path`, reading content from the referenced file, and rejecting icons that supply both or neither of `content`/`file_path`. Co-Authored-By: Claude <[email protected]> * Icons: Require namespaced "collection/name" for icon registration Previously, registering an icon without a collection prefix silently defaulted to the "core" collection, letting third-party code register icons under the reserved core namespace by omitting the prefix. Require an explicit "collection/icon-name" form and reject non-namespaced names. Co-Authored-By: Claude <[email protected]> * Icons: Drop redundant comments in icon name validation Co-Authored-By: Claude <[email protected]> * Tests: align merged icon file_path tests with collection requirement The trunk merge pulled in file_path registration tests that used an unregistered 'test-plugin' collection and a non-.svg temp file. After the icons API refactor, register() rejects unregistered collections and get_content() requires a .svg extension, so these tests failed. Use the registered 'test-collection' and the create_temp_icon_file helper. Co-Authored-By: Claude <[email protected]> * Fix duplicate icons.php require causing fatal redeclare error The trunk merge left two require statements for the WordPress 7.1 icons.php compat file: one inside the WP_REST_Controller block and one at the top level. Because gutenberg_register_default_icon_collections() is not guarded by function_exists(), loading the file twice triggered a fatal "Cannot redeclare" error. Keep the unconditional top-level require (matching trunk) and drop the duplicate inside the REST block. Co-Authored-By: Claude <[email protected]> --------- Co-authored-by: t-hamano <[email protected]> Co-authored-by: mcsf <[email protected]> Co-authored-by: Mamaduka <[email protected]> Co-authored-by: tyxla <[email protected]> Co-authored-by: jsnajdr <[email protected]>
This was referenced Jun 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
file_pathkey in icon registry #79100Note: I understand that this PR is large. However, I believe this is the minimum implementation required to correctly expose the API for registering icons.
What?
This PR exposes basic APIs for registering SVG icons.
The approach proposed by this PR is as follows. Please share your thoughts on this approach:
core(WordPress).{collection-slug}/{icon-slug}, as before.In the future, we might also support "categories," similar to font collections. That is, something like this:
Font Awesome > Symbol > Arrow LeftClasses
I added and extended classes to allow custom icon registration.
WP_Icon_Collections_RegistryNew. Singleton that stores icon collections. It supports basic methods such as registering, unregistering, and retrieving items from a collection.
WP_Icons_Registry_Gutenberggutenberg_register_default_iconsinstead.WP_REST_Icons_Controller_GutenbergAdd an endpoint to retrieve only the icons belonging to a specific collection.
/wp/v2/icons: Unchanged. Lists all registered icons./wp/v2/icons/<namespace>: New. Lists icons belonging to the given collection slug/wp/v2/icons/<namespace>/<name>: Unchanged. Single-item lookup.PHP functions
These are new wrapper functions for managing collections and icons.
wp_register_icon_collection( $slug, $args )wp_unregister_icon_collection( $slug )wp_register_icon( $icon_name, $args )wp_unregister_icon( $icon_name )Testing Instructions
Verify that the main APIs are functioning correctly. Below are code examples.
Register icons:
Confirm registered icons:
Unregister icons and collections
Screenshot
As you can see, the icon picker modal does not currently support filtering by collection. This will be addressed in a follow-up update.
Use of AI Tools
Parts of this PR (code refactoring, commit messages, PR description) were drafted with assistance from Claude Code. All generated changes were reviewed and adjusted manually before committing.