Icons: Override WP_Icons_Registry singleton with Gutenberg icons registry by t-hamano · Pull Request #76455 · WordPress/gutenberg

t-hamano · 2026-03-12T15:56:33Z

Follow-up to: Icons API: Support searching in labels; extend classes post-7.0 work #75878
Related to: SVG Icon API: Iteration for WordPress 7.1 #75715

What?

This PR replaces the WP_Icons_Registry singleton with Gutenberg_Icons_Registry_7_1 so that all code using WP_Icons_Registry::get_instance() receives Gutenberg’s icon registry instead of the Core one.

Why?

WP_Icons_Registry was released in 7.0, but in order to continue expanding this class for future releases, we created Gutenberg_Icons_Registry_7_1, which inherits from the core WP_Icons_Registry. However, this Gutenberg class is only accessed via the REST API. This means that even if we add Gutenberg_Icons_Registry_7_1::{new_method}, it cannot be called as WP_Icons_Registry::{new_method}. This is problematic because the icon registry may be accessed directly in the future, without going through the REST API.

How?

This PR uses reflection to replace WP_Icons_Registry::$instance with the Gutenberg registry instance, ensuring that the WP_Icons_Registry class always has the latest methods.

Using reflection may feel a bit hacky, but as far as I know, it's the only way to override a singleton class.

Testing Instructions

This is one way to ensure that this PR works properly.

Insert an Icon block, set an icon, and save the post.
Open the frontend.
Make the following changes and reload your browser.

diff --git a/lib/class-wp-icons-registry-gutenberg.php b/lib/class-wp-icons-registry-gutenberg.php
index e361ab3372d..89dfe448474 100644
--- a/lib/class-wp-icons-registry-gutenberg.php
+++ b/lib/class-wp-icons-registry-gutenberg.php
@@ -50,6 +50,13 @@ class WP_Icons_Registry_Gutenberg extends WP_Icons_Registry {
                }
        }
 
+       public function get_registered_icon( $icon_name ) {
+               return array(
+                       'name'    => $icon_name,
+                       'content' => 'Rendered via Gutenberg_Icons_Registry class.',
+               );
+       }
+
        /**
         * Modified to also search in icon labels
         */

…stry

github-actions · 2026-03-12T16:20:22Z

Flaky tests detected in 60bafaa.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/24122294045
📝 Reported issues:

[Flaky Test] post title and content are editable and blocks can be inserted #76524 in /test/e2e/specs/editor/various/post-content-focus-mode.spec.js
[Flaky Test] should show correct homepage actions based on current homepage or posts page #68892 in /test/e2e/specs/site-editor/homepage-settings.spec.js

t-hamano · 2026-03-12T16:36:04Z

My understanding is that this class was only needed internally to reference the Gutenberg icon registry. Now that we use reflection, this class should no longer be necessary.

t-hamano · 2026-03-12T16:46:00Z

@mcsf @Mamaduka, I’d like to establish an approach that allows us to continue developing the Icon API in the Gutenberg plugin while fully maintaining backward compatibility with each WordPress major version. If anyone has better ideas or suggestions, I’d love to hear them 🙏

github-actions · 2026-03-12T16:46:10Z

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.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: mcsf <mcsf@git.wordpress.org>
Co-authored-by: im3dabasia <im3dabasia1@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>

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

mcsf · 2026-03-12T19:09:56Z

I’d like to establish an approach that allows us to continue developing the Icon API in the Gutenberg plugin while fully maintaining backward compatibility with each WordPress major version. If anyone has better ideas or suggestions, I’d love to hear them 🙏

This "feels wrong" but also makes sense. The only other way I could think of was something I described here:

[…] it's technically possible to define a derived class such that, in the end, both [base and extended] classes share a static $instance. In short, it looked a little bit like this:
class Gutenberg_Foo extends WP_Foo {
    public static hijack_instance() {
        self::$instance = new self();
    }
}
Gutenberg_Foo::hijack_instance();

echo WP_Foo::get_instance() === Gutenberg_Foo::get_instance(); // 1
… but this is very hacky. I don't know what unintended consequences it may have.

The other hacky way is using PHP reflection.

The other unknown is independent of using reflection or this technique: timing. That is, where do we hook this? In my mind, the earlier we do it, the smaller the chance that the icon registry has already been called by consumers. Meanwhile, we'd probably also want to check the original instance for any registrations and "replay" them onto the new instance, right?

for icon in original_registry:
    new_registry.register( icon.name, icon )

t-hamano · 2026-03-13T01:35:15Z

Thanks for the review!

The other unknown is independent of using reflection or this technique: timing. That is, where do we hook this? In my mind, the earlier we do it, the smaller the chance that the icon registry has already been called by consumers.

Unfortunately, when I use hooks such as plugins_loaded and after_setup_theme that run earlier, the following warning appears:

Notice: Function _load_textdomain_just_in_time was called incorrectly. Translation loading for the gutenberg domain was triggered too early.

Meanwhile, we'd probably also want to check the original instance for any registrations and "replay" them onto the new instance, right?

You're right, addressed in 491c9fb

Mamaduka · 2026-03-13T04:59:20Z

We could just keep copies of the registry and REST API controllers, and sync them as needed. We're already doing the same for the global styles and theme.json. It's not fancy, but it works 😄

t-hamano · 2026-03-13T10:12:31Z

We could just keep copies of the registry and REST API controllers, and sync them as needed.

This seems like the simplest approach👍

t-hamano · 2026-03-13T10:15:03Z

+class WP_REST_Icons_Controller_Gutenberg extends WP_REST_Icons_Controller {
+}


Currently, there is no need to expand the core controller, but it may be necessary in the future.

im3dabasia · 2026-03-13T10:22:46Z

@t-hamano , I ran into this while fetching the icons using the REST API. I think once this PR is shipped, it will solve the issue. Currently, the class with private access modifiers is being accessed by Gutenberg_REST_Icons_Controller_7_1, which is located inside the wp-includes/ folder.

Edit: I applied this PR's patch in my local, did not solve the issue 😢

t-hamano · 2026-03-31T10:50:31Z

The tests were failing because I accidentally deleted unrelated code. I have fixed everything and it is ready for re-review.

mcsf

LGTM, just note the Reflection deprecations. Thanks for working on this :)

mcsf · 2026-04-07T16:53:37Z

+function gutenberg_override_wp_icons_registry() {
+	$reflection = new ReflectionClass( WP_Icons_Registry::class );
+	$property   = $reflection->getProperty( 'instance' );
+	$property->setAccessible( true );


Considering the deprecation of setAccessible, should we do as we did here?

if ( PHP_VERSION_ID < 80100 ) { $instance_property->setAccessible( true ); }

Addressed in commit 60bafaa

mcsf · 2026-04-07T17:02:08Z

+	// If the original registry was already instantiated, replay any icons outside
+	// the `core/` namespace onto the Gutenberg registry so they are not lost.
+	if ( null !== $original_registry ) {
+		$register_method = new ReflectionMethod( WP_Icons_Registry_Gutenberg::class, 'register' );


Same here: different class, same deprecation.

Addressed in commit 60bafaa

…omment-type Reconcile emoji reactions with trunk's notes architecture refactor. Drop PR's old positioning API (reflowComments, boardOffsets, calculatedOffset, setHeights, setBlockRef) in favor of trunk's floating prop backed by useFloatingBoard. Preserve the reactions data flow (reactionsMap, onToggleReaction) on top of the new architecture. Drop require statements for icons registry files removed in trunk (#76455).

Icons: Override WP_Icons_Registry singleton with Gutenberg icons regi…

a44fafe

…stry

t-hamano added 3 commits March 13, 2026 01:21

Remove Gutenberg_REST_Icons_Controller_7_1

b610839

Remove require statement

55892ed

Remove temp code

78ec29f

t-hamano self-assigned this Mar 12, 2026

t-hamano commented Mar 12, 2026

View reviewed changes

t-hamano added [Type] Code Quality Issues or PRs that relate to code quality No Core Sync Required Indicates that any changes do not need to be synced to WordPress Core [Feature] Icons Related to Icon registration API and Icon REST API labels Mar 12, 2026

Update comment

d0daaf6

t-hamano marked this pull request as ready for review March 12, 2026 16:46

t-hamano requested a review from spacedmonkey as a code owner March 12, 2026 16:46

Replay pre-registered non-core icons

491c9fb

t-hamano added 2 commits March 13, 2026 18:59

Merge branch 'trunk' into icons/refrection-class

493d230

Create registry and REST API controller for Gutenberg

7d47012

WP_REST_Icons_Controller_Gutenberg: Remove unnecessary ABSPATH check

196e4b3

t-hamano commented Mar 13, 2026

View reviewed changes

Merge branch 'trunk' into icons/refrection-class

b3d1dae

t-hamano commented Mar 19, 2026

View reviewed changes

Comment thread lib/class-gutenberg-rest-view-config-controller-7-1.php

t-hamano added 3 commits March 19, 2026 18:45

Fix misplaced files

c56e31c

Merge branch 'trunk' into icons/refrection-class

6160049

Merge branch 'trunk' into icons/refrection-class

a75a322

t-hamano added 3 commits March 30, 2026 19:26

Merge branch 'trunk' into icons/refrection-class

7309547

Restore code that was accidentally deleted

b30292f

Merge branch 'trunk' into icons/refrection-class

bdd9972

t-hamano added 4 commits April 1, 2026 12:01

Merge branch 'trunk' into icons/refrection-class

8d80eae

Update unit test

55b6070

Fix PHPCS warning

14fe750

Fix PHPCS warning take 2

a3027c6

t-hamano requested a review from mcsf April 2, 2026 11:10

mcsf approved these changes Apr 7, 2026

View reviewed changes

t-hamano added 2 commits April 8, 2026 15:49

Merge branch 'trunk' into icons/refrection-class

fdd080f

Add PHP version check

60bafaa

t-hamano merged commit 1dc1a7f into trunk Apr 8, 2026
41 of 43 checks passed

t-hamano deleted the icons/refrection-class branch April 8, 2026 07:44

github-actions Bot added this to the Gutenberg 23.0 milestone Apr 8, 2026

		class WP_REST_Icons_Controller_Gutenberg extends WP_REST_Icons_Controller {
		}

Conversation

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

Uh oh!

What?

Why?

How?

Testing Instructions

Uh oh!

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

Uh oh!

Uh oh!

t-hamano Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

mcsf Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

t-hamano commented Mar 12, 2026

Uh oh!

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

Uh oh!

Uh oh!

mcsf commented Mar 12, 2026

Uh oh!

t-hamano commented Mar 13, 2026

Uh oh!

Mamaduka commented Mar 13, 2026

Uh oh!

t-hamano commented Mar 13, 2026

Uh oh!

t-hamano Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

im3dabasia commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

t-hamano commented Mar 31, 2026

Uh oh!

mcsf left a comment

Choose a reason for hiding this comment

Uh oh!

mcsf Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

t-hamano Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

mcsf Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

t-hamano Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

t-hamano commented Mar 12, 2026 •

edited

Loading

github-actions Bot commented Mar 12, 2026 •

edited

Loading

github-actions Bot commented Mar 12, 2026 •

edited

Loading

im3dabasia commented Mar 13, 2026 •

edited

Loading