Premium Analytics: fire an action when the widget type registry hydrates by retrofox · Pull Request #52568 · Automattic/jetpack

retrofox · 2026-09-21T17:30:30Z

Proposed changes

Step 1 of 4 of the widget-type extensibility stack (umbrella: #52637).

What?

A plugin can register widget types on the dashboard from a callback on jetpack_premium_analytics_register_widget_types, the way it registers sections since #52454.

Widget_Type_Registry hydrates on its first read after init and fires the action once, with the registry.
register_widget_types_from_manifest( $widgets, $args ) registers the manifest a plugin's wp-build generates. register_widget_type( $name, $args ) registers a single type.
The package registers its own manifest through the same action, at priority 10. bootstrap_widget_types() and its init hook go away.
WIDGET_API_VERSION names the contract a widget is built against. A consumer checks it before registering.

Why?

Widget types had a registry, two filters, a REST route and an import map, but no public registration and no moment a plugin could hook: hydration ran from the package's own manifest, on init or on the first read. The first real consumer, the Ads widgets, is #52635.

How?

The registry latches before the action fires, so a registrant that reads the registry does not re-enter it. A read before init is a _doing_it_wrong() that answers what was registered directly and does not latch, so later registrants still run. is_registered() never hydrates, so registering before the action works.

docs/dashboard-widgets.md walks through the path, with a diagram.

Related product discussion/links

Umbrella of this stack: Premium Analytics: let other plugins register dashboard widget types #52637
The section stack this mirrors: Premium Analytics: make dashboard sections extensible by other plugins #52448
Linear: WOOA7S-2183 (the stack), WOOA7S-2184 (this step)

Does this pull request change what data or activity we track or use?

No.

Testing instructions

cd projects/packages/premium-analytics && composer phpunit

Register a type from a plugin

Add this mu-plugin. It reuses the package's own Clicks modules under another name, so it needs no build:

I usually create a custom plugin in tools/docker/mu-plugins/00-retrofox.php

add_action( 'jetpack_premium_analytics_register_widget_types', function () {
	if ( version_compare( \Automattic\Jetpack\PremiumAnalytics\WIDGET_API_VERSION, '2', '>=' ) ) {
		return;
	}
	\Automattic\Jetpack\PremiumAnalytics\register_widget_types_from_manifest(
		array(
			array(
				'name'          => 'demo/clicks',
				'render_module' => 'jetpack-premium-analytics/widgets/clicks/render',
				'widget_module' => 'jetpack-premium-analytics/widgets/clicks/widget',
				'presentation'  => 'framed',
				'category'      => 'stats',
				'title'         => 'Demo clicks',
				'description'   => 'The Clicks widget, registered from a plugin under another name.',
				'help'          => array( 'content' => 'Read <em>this</em> <script>carefully</script>.' ),
			),
		),
		array( 'textdomain' => 'demo' )
	);
}, 20 );

GET /wp-json/wpcom/v2/widget-modules lists demo/clicks next to jpa/clicks, with the <script> stripped from help.content.

The widget picker offers "Demo clicks", and adding it to a section renders the Clicks widget.

You may need to enable the composition mode:

jp docker wp option update jetpack_pa_dev_composition 1

With define( 'WP_ENVIRONMENT_TYPE', 'production' ) and 'category' => 'developer' in the array, the type is gone from the list: the registry-time filter drops it, as it would a package widget.

The single-type form is register_widget_type( 'demo/clicks', array( … ) ) with the same arguments, minus the sanitizing.

A read before `init`.

From a plugin's main file, after a require_once of the package's src/widget-types.php, call \Automattic\Jetpack\PremiumAnalytics\get_registered_widget_types(). PHP logs a _doing_it_wrong(), and the dashboard still offers every widget afterward.

github-actions · 2026-09-21T17:31:45Z

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the update/pa-extensibility-widget-types-action branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack update/pa-extensibility-widget-types-action

bin/jetpack-downloader test jetpack-mu-wpcom-plugin update/pa-extensibility-widget-types-action

Interested in more tips and information?

In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
Read more about our development workflow here: PCYsg-eg0-p2
Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

github-actions · 2026-09-21T17:31:58Z

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

✅ Include a description of your PR changes.
✅ Add a "[Status]" label (In Progress, Needs Review, ...).
✅ Add testing instructions.
✅ Specify whether this PR includes any changes to data or privacy.
✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

Follow this PR Review Process:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

jp-launch-control · 2026-09-21T17:44:02Z

Code Coverage Summary

Coverage changed in 3 files.

File	Coverage	Δ%	Δ Uncovered
projects/packages/premium-analytics/src/widget-modules.php	35/50 (70.00%)	-0.59%	0 💚
projects/packages/premium-analytics/src/widget-types.php	124/129 (96.12%)	2.42%	-3 💚
projects/packages/premium-analytics/src/class-widget-type-registry.php	34/73 (46.58%)	41.81%	-21 💚

Full summary · PHP report · JS report

register_widget_type() for plugins; the manifest registers from it

hydration diagram, AGENTS.md and README pointers

register_widget_types_from_manifest(); the package's registrant is its first caller

widgets/ form example, versioning section, diagram

Nikschavan

Thank you, the changes look good. I left one question inline about the widget-availability.php header and a few small notes on the tests.

Nikschavan · 2026-09-23T10:20:20Z

+1. **Registry-time**, `jetpack_premium_analytics_registrable_widget_types`, over the manifest candidates in `register_widget_types()`. A dropped candidate never registers: gone from the REST list, the import map and every registry reader. For hard availability.
+2. **Runtime**, `jetpack_premium_analytics_widget_types`, over the registered map on every read of `get_available_widget_types()`. The type stays registered. For request-dependent or soft state, e.g. a type shown locked.
+
+The package's own policy hooks the first, in `src/widget-availability.php`: developer-only widgets off production, the store and bookings categories without WooCommerce or Bookings, the store report categories without the capability. A plugin's manifest goes through the same filter when it registers through `register_widget_types_from_manifest()`; a type registered one by one with `register_widget_type()` does not. Either way, a plugin decides in its callback whether to register at all, as the section owners do.


This line says a type registered with register_widget_type() skips the registry-time filter, but the header of widget-availability.php still says the hide applies "so every consumer of the registry sees the same set". Should that header now say it covers manifest candidates only?

Yes, the header was stale: the policy runs over manifest candidates, and a type registered one by one with register_widget_type() skips it. Reworded in #52634, the next step of the stack, to keep this one as approved.

Nikschavan · 2026-09-23T10:20:20Z

+use PHPUnit\Framework\Attributes\CoversFunction;
+use WorDBless\BaseTestCase;
+
+require_once __DIR__ . '/../../src/widget-modules.php';


Run on its own, this file errors in test_widget_type_registered_on_the_action_reaches_both_readers with Call to undefined function ...is_woocommerce_dashboard_section_available(). The REST read loads widget-availability.php, which calls that function from default-dashboard-sections.php, and nothing here requires that file. The suite passes only because another test loads it first. A require_once of default-dashboard-sections.php, as Widget_Availability_Test.php does, would remove the order dependence.

Confirmed: run by path, the file errors on that test. #52634 adds the require_once of default-dashboard-sections.php, as Widget_Availability_Test.php does.

Nikschavan · 2026-09-23T10:20:20Z

+	/**
+	 * The contract version a consumer compares against is a semantic version.
+	 */
+	public function test_widget_api_version_is_a_semantic_version() {


This test checks the shape of a constant that nothing in the package reads, so it can only fail when someone edits the literal itself. I think it could go without losing coverage of any behaviour.

Agreed, it only guards the literal. Dropped in #52634.

Nikschavan · 2026-09-23T10:22:31Z

+		register_widget_types();
+
+		$this->assertSame( array(), $this->doing_it_wrong );
+		$this->assertCount( 1, array_keys( get_registered_widget_types(), Widget_Type_Registry::get_instance()->get_registered( self::MANIFEST_WIDGET ), true ) );


The registry is keyed by name, so this count is always 1 once the widget is registered and cannot catch a second registration. The doing_it_wrong assertion above it is what fails when the duplicate skip is removed, so this line could go, or become an assertArrayHasKey if the registered check is the intent.

Right, the registry is keyed by name, so the count cannot move. #52634 replaces it with assertArrayHasKey( self::MANIFEST_WIDGET, get_registered_widget_types() ): the intent was that the type is still registered after the second call.

require default sections in the registry test, drop the version-shape test, fix the availability header

…52634) * add the catalog location to widget module records textdomain and i18n_manifest per type; the client loads a plugin's widget catalogs from them * apply the review follow-ups from #52568 require default sections in the registry test, drop the version-shape test, fix the availability header * mock the widget module resolver in the stage test

retrofox requested a review from a team as a code owner September 21, 2026 17:30

retrofox added Enhancement Changes to an existing feature — removing, adding, or changing parts of it [Status] Needs Review This PR is ready for review. labels Sep 21, 2026

retrofox self-assigned this Sep 21, 2026

github-actions Bot added [Package] Premium Analytics [Tests] Includes Tests Docs labels Sep 21, 2026

retrofox removed the request for review from a team September 21, 2026 17:39

retrofox marked this pull request as draft September 21, 2026 17:39

github-actions Bot added the [Status] In Progress label Sep 21, 2026

retrofox added 4 commits September 22, 2026 13:46

add the widget type registry hydration action

1873a00

register_widget_type() for plugins; the manifest registers from it

add the dashboard widget types doc

d883cae

hydration diagram, AGENTS.md and README pointers

add the manifest registrant and WIDGET_API_VERSION

c0c7aee

register_widget_types_from_manifest(); the package's registrant is its first caller

update widget types doc: manifests and version

52a9a99

widgets/ form example, versioning section, diagram

retrofox force-pushed the update/pa-extensibility-widget-types-action branch from 0187e38 to 52a9a99 Compare September 22, 2026 15:00

This was referenced Sep 22, 2026

Premium Analytics: say where each widget module's translations live #52634

Merged

Premium Analytics: move the Ads widgets to the jetpack-ads package #52635

Merged

Premium Analytics: let other plugins register dashboard widget types #52637

Closed

retrofox marked this pull request as ready for review September 23, 2026 08:44

retrofox removed the [Status] In Progress label Sep 23, 2026

github-actions Bot added the [Status] In Progress label Sep 23, 2026

retrofox requested review from a team, chihsuan and louwie17 September 23, 2026 08:46

retrofox removed the [Status] In Progress label Sep 23, 2026

retrofox added this pull request to stack #52692 September 23, 2026 08:53

Nikschavan approved these changes Sep 23, 2026

View reviewed changes

retrofox added a commit that referenced this pull request Sep 23, 2026

apply the review follow-ups from #52568

e773f41

require default sections in the registry test, drop the version-shape test, fix the availability header

retrofox merged commit c5142e0 into trunk Sep 23, 2026
95 of 96 checks passed

retrofox deleted the update/pa-extensibility-widget-types-action branch September 23, 2026 11:56

retrofox added a commit that referenced this pull request Sep 23, 2026

apply the review follow-ups from #52568

95fdf76

require default sections in the registry test, drop the version-shape test, fix the availability header

github-actions Bot added [Status] UI Changes Add this to PRs that change the UI so documentation can be updated. and removed [Status] Needs Review This PR is ready for review. labels Sep 23, 2026

retrofox added a commit that referenced this pull request Sep 23, 2026

apply the review follow-ups from #52568

cadc19e

require default sections in the registry test, drop the version-shape test, fix the availability header

retrofox mentioned this pull request Sep 28, 2026

Premium Analytics: document the widget catalog location and the Ads package #52636

Merged

Navigation Menu

Repository navigation

Premium Analytics: fire an action when the widget type registry hydrates - #52568

Premium Analytics: fire an action when the widget type registry hydrates#52568
retrofox merged 4 commits into
trunkfrom
update/pa-extensibility-widget-types-action

retrofox commented Sep 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

jp-launch-control Bot commented Sep 21, 2026 •

edited

Loading

Uh oh!

Nikschavan left a comment

Uh oh!

Nikschavan Sep 23, 2026

Uh oh!

retrofox Sep 23, 2026

Uh oh!

Nikschavan Sep 23, 2026

Uh oh!

retrofox Sep 23, 2026

Uh oh!

Nikschavan Sep 23, 2026

Uh oh!

retrofox Sep 23, 2026

Uh oh!

Nikschavan Sep 23, 2026

Uh oh!

retrofox Sep 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

retrofox commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

What?

Why?

How?

Related product discussion/links

Does this pull request change what data or activity we track or use?

Testing instructions

Register a type from a plugin

A read before init.

Uh oh!

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

Uh oh!

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

jp-launch-control Bot commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Summary

Uh oh!

Nikschavan 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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

retrofox commented Sep 21, 2026 •

edited

Loading

A read before `init`.

github-actions Bot commented Sep 21, 2026 •

edited

Loading

jp-launch-control Bot commented Sep 21, 2026 •

edited

Loading