Plugin Dependencies: Add filter to restore auto-redirect after plugin activation

[hellofromTonya]

To address the problems (see below) while minimizing risks in a minor, this ticket proposes adding a mechanism (i.e. a filter) for plugins to register their onboarding | set up | configure URL for Core to handle the auto-redirects after activation. This filter will be forward-compatible by design as the entry point into the onboarding framework (see #61040).

@costdev @jorbin are co-collaborators on this proposal, following discussions with and data gathering from @beaulebens @adrianduffell @nerrad @illuminea @smub to better understand the impacts and user insights.

Problem Statements:

Plugin companies and their users (which are also this project's users) are significantly impacted.

It's unknown if the majority of users want or do not want auto-redirect.

It's now known that impacted plugin's users do want this ability. The size of their user bases is data to suggest the significance of the impact.

A new onboarding framework needs the benefits of major release cycle to understand the impacts, form a scope, do experiments, and then move through the product | enhancement stages.

More Context:

As of WP 6.5.0, users are no longer able to quickly go from install to onboarding | set up | configure. Plugin companies are significantly impacted, reporting decreases of 18-30% in users moving to the next step (which helps users use the plugin). The 6.5.3 new "Refresh now" user action (an additional user action) appears to reduce the impacts, though are still significant.

An enhancement ticket is open for exploring an onboarding framework (see #61040).

The Plugins Dependencies (aka PD) feature made a technical and design decision for its workflow. In talking with @costdev, the feature did not set out to ban redirects after activation. @jorbin summarized the feature's problem statement as:

The problem PD aims to solve is that when a plugin has a dependency on another, users are left to their devices which leads to inconsistent user experiences and potential for site breakage by deactivating plugins that are relied upon

Notice, the problem statement does not mention or include redirects or onboarding. The hard removal of autoloading onboarding seems to be a byproduct of the decided workflow.

Please note, the decision was thoughtfully made. With no issue reports or feedback during the calls for testing and 6.5 alpha, beta, and RC cycles, there did not seem to be an issue.

Fast forward to today, feedback has been shared showing the decision is causing a significant impacts.

In hindsight with what is known today, the onboarding framework and PD feature should have shipped together.

Proposal

With this new understanding, this ticket proposes to:

• In a 6.5.x minor, give plugins a mechanism (filter) to register their URL for Core to handle the redirect. To minimize risks in a minor, the scope is essentially an "opt-out" by using a filter that will become part of the onboarding framework.

• In 6.6+ major, the mechanism becomes the entry point into the onboarding framework.

• Then deal with the scope and impacts of a possible new onboarding framework and/or workflow in a major release, i.e. to give time for discussion, consideration, experimentation, feedback, adoption, etc.

Proposal Technical Details

• In 6.5.4:
  • add a new filter plugin_configuration_data_{$slug} for the onboarding/configuration URL, with an initial parameter value of array( 'url' => '' ).
  • if filtered, it auto-redirects to that URL after activation.
• In 6.6+:
  • the filter is the entry point into the onboarding framework.
  • the filter's array is extended for the needs of the onboarding framework.
  • evaluate combining Install/Activate on the Plugins > Add New Plugin screen to mitigate the 3-click approach created by the new button.

Pros 🟢 and Cons 🔴 Summary

• 🟢 Temporarily restores a way to trigger auto-loading onboarding in a minor (without a revert).
• 🟢 AJAX is retained, thus does not impact users or plugins authors when activating plugins not using the filter.
• 🟢 Impacts the majority of users activating plugins who are early adopters of PD, given the majority of early adopters require flagship plugins with large user bases that require user setup for usage.
• ⚪️ Is forward-compatible by design, with a clear direction for the future.
• 🟢 Less risk in a minor, while shifting design decisions to a major.
• 🟢 Less opinionated in a minor, moving the design decisions to a major.
• 🔴 Gives plugins a way to prevent users from completing the users intended action

Why not revert?

Good question, one that was thoughtfully and seriously considered.

A full revert of the Plugins Dependencies (PD) feature will potentially cause a backwards compatible (BC) break. Why? It shipped public functions, classes, etc that are available for invoking and extending in plugins. If any plugins are currently invoking or extending, the user will experience a fatal error.

A partial revert of the AJAX will impact users using a plugin that adopted the feature.

Thus, a revert also impacts users.

In contrast, this ticket's proposal of adding a filter is a pragmatic, forward-compatible approach to benefit users (including extenders).

References

Follow-up to:

• #60992 [58081] [58083] (6.5.3)
• #22316 [57545] (6.5.0).

Related to #61040.

[afragen]

Well thought out and well reasoned. This proposal should require minimal updating to existing plugins to take advantage and return to their prior workflows.

Plugin devs will need to remember to conditionally activate this new filter when the onboarding process has not been completed.

• Adds a new plugin_configuration_data_{$slug} filter for plugins to register their URL.
• Adds redirect control. For 6.5.4, redirect will happen after plugin activation.

Props @costdev @aaronjorbin

Trac ticket: https://core.trac.wordpress.org/ticket/61269

[jorbin]

This is going to be important to communicate out, so making a note that there will be a dev note. I am starting to draft it.

[hellofromTonya]

Good thinking @jorbin. Thank you :)

Adding testing keywords. Tomorrow, I'll provide the testing instructions, start testing the patch with different plugins, and provide before/after test reports for each plugin test. Working with WooCommerce, Elementor, Awesome Motive, and other plugins for their testing and feedback.

# Test Report

Testing WooCommerce with this PR applied and sample code added to the plugin.

## Environment

• OS: macOS
• Web Server: nginx
• PHP: 8.3
• WordPress: 6.5.3 with this PR applied
• Browser: Firefox 126.0
• Theme: default
• Plugins: WooCommerce 8.9.1

## Instructions

Set Up:

1. Install but do not activate WooCommerce yet as code needs to be added to it.
2. Open plugins/woocommerce/woocommerce.php file.
3. Copy and paste the following the code after defined( 'ABSPATH' ) || exit;:

add_filter( 'plugin_configuration_data_woocommerce', static function() {
        return array(
                'url' => admin_url( 'admin.php?page=wc-admin' ),
        );
} );

### Test in the Add Plugins UI:

1. Navigate to Plugins > Add New Plugin.
2. In the plugins search box, type woocommerce. The plugin cards will appear including the WooCommerce plugin.
3. In the WooCommerce card, press the "Activate" button.

Expected Results:
After activation, the site should redirect to Woo's onboarding wizard.

### Test in the More Details modal:

1. Deactivate WooCommerce first.
2. Navigate to Plugins > Add New Plugin.
3. In the plugins search box, type woocommerce. The plugin cards will appear including the WooCommerce plugin.
4. In the WooCommerce card, click on the "More Details" link below the "Activation" button.
5. Press the "Activate" button (may need to scroll down to the button).

Expected Results:
After activation, the site should redirect to Woo's onboarding wizard.

## Actual Results

### Test in the Add Plugins UI:
After activated, the onboarding wizard auto-redirects ✅

The "Refresh now" admin notice and button are visible during the time between "plugin activated" until the redirect triggers. This could confuse users. Marking it as not expected ❌.

### Test in the More Details modal:
After activated, the onboarding wizard auto-redirects ✅

The modal footer's "Refresh now" admin notice and button are visible during the time between "plugin activated" until the redirect triggers. This could confuse users. Marking it as not expected ❌.

### Observations

"Refresh now" button and notice are visible ❌ (as noted in the tests results).

It's gone after navigating back (which is expected ✅ ).

# Test Report

Testing WooCommerce with this PR applied (including the fix to not show the "Refresh now" ​https://github.com/WordPress/wordpress-develop/pull/6606/commits/dc013d3e1abbf3a826c02794d7e0c6b006d268ab) and sample code added to the plugin.

## Environment

• OS: macOS
• Web Server: nginx
• PHP: 8.3
• WordPress: 6.5.3 with this PR applied
• Browser: Firefox 126.0
• Theme: default
• Plugins: WooCommerce 8.9.1

## Instructions

Set Up:

1. Install but do not activate WooCommerce yet as code needs to be added to it.
2. Open plugins/woocommerce/woocommerce.php file.
3. Copy and paste the following the code after defined( 'ABSPATH' ) || exit;:

add_filter( 'plugin_configuration_data_woocommerce', static function() {
        return array(
                'url' => admin_url( 'admin.php?page=wc-admin' ),
        );
} );

### Test in the Add Plugins UI:

1. Navigate to Plugins > Add New Plugin.
2. In the plugins search box, type woocommerce. The plugin cards will appear including the WooCommerce plugin.
3. In the WooCommerce card, press the "Activate" button.

Expected Results:
After activation:

• the "Refresh now" admin notice and button should not appear.
• the site should redirect to Woo's onboarding wizard.

### Test in the More Details modal:

1. Deactivate WooCommerce first.
2. Navigate to Plugins > Add New Plugin.
3. In the plugins search box, type woocommerce. The plugin cards will appear including the WooCommerce plugin.
4. In the WooCommerce card, click on the "More Details" link below the "Activation" button.
5. Press the "Activate" button (may need to scroll down to the button).

Expected Results:
After activation:

• at the bottom of the modal, the "Refresh now" admin notice and button should not appear.
• the site should redirect to Woo's onboarding wizard.

## Actual Results

### Test in the Add Plugins UI:
After activated:

• the "Refresh now" admin notice and button do not appear ✅
• the onboarding wizard auto-redirects ✅

### Test in the More Details modal:
After activated:

• the "Refresh now" footer area in the modal does not appear ✅
• the onboarding wizard auto-redirects ✅

### Observations
Works as expected ✅

[valani9099]

Hello @hellofromTonya,

To restore auto-redirect after plugin activation in WordPress, you can use a filter hook. WordPress provides the activate_plugin action hook, which can be utilized to add custom functionality immediately after a plugin is activated.

Here’s the complete code snippet that you would typically add to your plugin’s main file:

<?php
function my_plugin_redirect() {
    if (isset($_GET['activate']) && $_GET['activate'] == 'true') {
        // Redirect to a specific page after activation
        wp_redirect(admin_url('admin.php?page=my-plugin-settings'));
        exit;
    }
}
add_action('admin_init', 'my_plugin_redirect');

Make sure that the page you are redirecting to (admin.php?page=my-plugin-settings) exists and is registered correctly in your plugin.

By adding this code, you ensure that after the plugin is activated, the user will be automatically redirected to the specified settings page, enhancing the user experience by guiding them to the configuration area of your plugin.

[hellofromTonya]

Hello @valani9099,

I think you might have missed the context. Let me explain.

The ability to redirect after activation was hard removed in 6.5.0 via #22316 [57545].

Just tested your sample code in the Plugins > Add Plugins UI. Redirect does not happen after activation.

Reopening the ticket.

[hellofromTonya]

Testing Instructions

These steps define how to reproduce the issue, and indicate the expected behavior.

Patch: ​https://github.com/WordPress/wordpress-develop/pull/6606

Set up

Patch: ​https://github.com/WordPress/wordpress-develop/pull/6606
Note: After applying the patch, it needs to be built (i.e. to build the JS and its minified version) which is done by:

npm install
npm run build:dev

Plugin with onboarding | set up | configure experience that auto-redirected after activation before WP 6.5.0 (e.g. Elementary, WooCommerce, BuddyPress, bbPress, OptinMonster, WPForms, etc.):

1. Install the plugin, but do not activate it yet.
2. Open its main plugin PHP file.
3. After the plugin header DocBlock and after defined( 'ABSPATH' ) || exit; (if this exists), copy and paste the following code:

add_filter( 'plugin_configuration_data_{the-plugin-slug}', static function() {
        return array(
                'url' => admin_url( 'the-url-to-redirect-to' ),
        );
} );

For example, if testing WooCommerce:

• Open plugins/woocommerce/woocommerce.php file.
• Copy and paste the following the code after defined( 'ABSPATH' ) || exit;:

add_filter( 'plugin_configuration_data_woocommerce', static function() {
        return array(
                'url' => admin_url( 'admin.php?page=wc-admin' ),
        );
} );

Steps to Test in the Add Plugins UI:

1. Navigate to Plugins > Add New Plugin.
2. In the plugins search box, type the name of the plugin you're testing (e.g. woocommerce) and press enter. The UI should populate with that and associated plugins.
3. In the plugin's card, press the "Activate" button.

Expected Results:
After activation:

• the "Refresh now" admin notice and button should not appear.
• the site should redirect to plugin's onboarding wizard | set up or configure page.

Steps to Test in the More Details modal:

Note: Deactivate the plugin first.

1. Navigate to Plugins > Add New Plugin.
2. In the plugins search box, type the name of the plugin you're testing (e.g. woocommerce) and press enter. The UI should populate with that and associated plugins.
3. In the plugin's card, click on the "More Details" link below the "Activation" button.
4. Press the "Activate" button (may need to scroll down to the button).

Expected Results:
After activation:

• at the bottom of the modal, the "Refresh now" admin notice and button should not appear.
• the site should redirect to the onboarding wizard | set up or configure page.

Steps to Test another plugin that requires the plugin you're testing

Note: Deactivate the plugin first.

Example: When searching for WooCommerce plugins to add, notice there are several dependent upon WooCommerce, such as WooCommerce Stripe Payment Gateway.

The instructions will be for WooCommerce. But it's the same steps for others such as Elementor.

1. Navigate to Plugins > Add New Plugin.
2. In the plugins search box, type woocommerce and press enter. The UI should populate with that and associated plugins.
3. In the plugin's card, click on the "More Details" link below the "Activation" button.
4. For one of the plugins requiring WooCommerce (such as WooCommerce Stripe Payment Gateway): 4.1 Press the "Install Now" button. 4.2 After installed, notice unable to activate the plugin. This is by design as it requires WooCommerce. 4.3 In the "Additional plugins are required" section, click WooCommerce's "More Details" link. 4.4 In the modal, press the "Activate" button. Expected: WooCommerce's onboarding wizard should load. 4.5 In your browser, click the button to navigate back to the Add Plugins UI. Expected: WooCommerce Stripe Payment Gateway plugin can now be activated. 4.6 Activate the plugin.

Expected Results:
After activation of WooCommerce:

• at the bottom of the modal, the "Refresh now" admin notice and button should not appear.
• the site should redirect to the onboarding wizard | set up or configure page.

After navigating back to the Add Plugins UI, plugins requiring WooCommerce are now able to be activated.

[hellofromTonya]

Test Report for WooCommerce

Patch tested ​https://github.com/WordPress/wordpress-develop/pull/6606 as of ​this commit

Environment

• OS: macOS
• Web Server: nginx
• PHP: 8.3
• WordPress: 6.5.3 with this PR applied
• Browser: Firefox 126.0
• Theme: default
• Plugins: WooCommerce 8.9.1 with the sample code added.

Actual Results for Test in the Add Plugins UI:

After activation:

• ✅ the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirects to WooCommerce's onboarding wizard.

Actual Results for Test in the More Details modal:

After activation:

• ✅ at the bottom of the modal, the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirect to WooCommerce's onboarding wizard.

Actual Results for Test another plugin that requires the plugin you're testing

After activation of WooCommerce:

• ✅ at the bottom of the modal, the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirect to WooCommerce's onboarding wizard.

After navigating back to the Add Plugins UI:

• ✅ able to activate plugins requiring WooCommerce.

[hellofromTonya]

Test Report for Elementor

Patch tested ​https://github.com/WordPress/wordpress-develop/pull/6606 as of ​this commit

Environment

• OS: macOS
• Web Server: nginx
• PHP: 8.3
• WordPress: 6.5.3 with this PR applied
• Browser: Firefox 126.0
• Theme: default
• Plugins: Elementor 3.21.7 with the sample code added:

add_filter( 'plugin_configuration_data_elementor', static function() {
        return array(
                'url' => admin_url( 'admin.php?page=elementor-app#onboarding' ),
        );
} );

Actual Results for Test in the Add Plugins UI:

After activation:

• ✅ the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirects to Elementor's onboarding wizard.

Actual Results for Test in the More Details modal:

After activation:

• ✅ at the bottom of the modal, the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirect to Elementor's onboarding wizard.

Actual Results for Test another plugin that requires the plugin you're testing

After activation of Elementor:

• ✅ at the bottom of the modal, the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirect to Elementor's onboarding wizard.

After navigating back to the Add Plugins UI:

• ✅ able to activate plugins requiring Elementor.

This PR is ready for review and testing. Testing instructions are found in the description and ticket.

[hellofromTonya]

Test Report for OptinMonster

Patch tested ​https://github.com/WordPress/wordpress-develop/pull/6606 as of ​this commit

OptinMonster from plugins repo ​https://wordpress.org/plugins/optinmonster/.

Environment

• OS: macOS
• Web Server: nginx
• PHP: 8.3
• WordPress: 6.5.3 with this PR applied
• Browser: Firefox 126.0
• Theme: default
• Plugins: OptinMonster 2.16.2 with the sample code added:

add_filter( 'plugin_configuration_data_optinmonster', static function() {
        return array(
                'url' => admin_url( 'admin.php?page=optin-monster-onboarding-wizard' ),
        );
} );

Actual Results for Test in the Add Plugins UI:

After activation:

• ✅ the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirects to OptinMonster's onboarding wizard.

Actual Results for Test in the More Details modal:

After activation:

• ✅ at the bottom of the modal, the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirect to OptinMonster's onboarding wizard.

Actual Results for Test another plugin that requires the plugin you're testing

Did not test, as there are no plugins requiring it.

[hellofromTonya]

Test Report for BuddyPress

Patch tested ​https://github.com/WordPress/wordpress-develop/pull/6606 as of ​this commit

BuddyPress from plugins repo ​https://wordpress.org/plugins/buddypress/.

Environment

• OS: macOS
• Web Server: nginx
• PHP: 8.3
• WordPress: 6.5.3 with this PR applied
• Browser: Firefox 126.0
• Theme: default
• Plugins: BuddyPress 12.5.0 with the sample code added:

add_filter( 'plugin_configuration_data_buddypress', static function() {
        return array(
                'url' => admin_url( 'admin.php?hello=buddypress&is_new_install=1' ),
        );
} );

Actual Results for Test in the Add Plugins UI:

After activation:

• ✅ the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirects to the admin dashboard with the BuddyPress modal overlay.

Actual Results for Test in the More Details modal:

After activation:

• ✅ at the bottom of the modal, the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirect to admin dashboard with the BuddyPress modal overlay.

Actual Results for Test another plugin that requires BuddyPress

Did not test, as there are no plugins requiring it.

[hellofromTonya]

Test Report for Contact Form 7

Patch tested ​https://github.com/WordPress/wordpress-develop/pull/6606 as of ​this commit

Contact Form 7 from plugins repo ​https://wordpress.org/plugins/contact-form-7/.

How it behaved prior to WP 6.5:
After activation:

• redirected back to the Plugins table list
• added a "Contact" menu into the admin's main menu sidebar.

Environment

• OS: macOS
• Web Server: nginx
• PHP: 8.3
• WordPress: 6.5.3 with this PR applied
• Browser: Firefox 126.0
• Theme: default
• Plugins: Contact Form 7 v 5.9.5 with the sample code added:

add_filter( 'plugin_configuration_data_contact-form-7', static function() {
        return array(
                'url' => admin_url( 'plugins.php' ),
        );
} );

Actual Results for Test in the Add Plugins UI:

After activation:

• ✅ the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirects to the Plugins table list.
• ✅ the "Contact" menu is added into the main sidebar.

Actual Results for Test in the More Details modal:

After activation:

• ✅ at the bottom of the modal, the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirects to the Plugins table list.
• ✅ the "Contact" menu is added into the main sidebar.

Actual Results for Test another plugin that requires Contact Form 7

Plugin: Contact Form 7 – Dynamic Text Extension ​https://wordpress.org/plugins/contact-form-7-dynamic-text-extension/

After activation of Contact Form 7:
✅ at the bottom of the modal, the "Refresh now" admin notice and button do not appear.

• ✅ auto-redirects to the Plugins table list.
• ✅ the "Contact" menu is added into the main sidebar.

After navigating back to the Add Plugins UI:
✅ able to activate plugins requiring Contact Form 7 – Dynamic Text Extension plugin.

[kevinwhoffman]

• In a 6.5.x minor, give plugins a mechanism (filter) to register their URL for Core to handle the redirect. To minimize risks in a minor, the scope is essentially an "opt-out" by using a filter that will become part of the onboarding framework.
• In 6.6+ major, the mechanism becomes the entry point into the onboarding framework.

I understand this patch will restore post-activation redirects in 6.5.X.

If/when the filter becomes the entry point to an onboarding framework in 6.6+, would the ability to perform post-activation redirects be taken away in favor of the new workflow wherein the user decides to initiate onboarding? Or will plugins maintain the ability to force redirects beyond 6.6+?

If redirects are coming back to stay, we will have a hard time convincing plugin developers to abandon redirects in favor of the user-led workflow.

[hellofromTonya]

Replying to kevinwhoffman:

I understand this patch will restore post-activation redirects in 6.5.X.

Yes, but the difference is: the redirect is moved into Core and gives Core the control of when it triggers within the workflow.

While in the Add Plugins UI (including its "More Details" modal), plugins cannot directly redirect away; rather, they register their URL and Core controls the redirect at a certain point in the workflow.

If/when the filter becomes the entry point to an onboarding framework in 6.6+, would the ability to perform post-activation redirects be taken away in favor of the new workflow wherein the user decides to initiate onboarding? Or will plugins maintain the ability to force redirects beyond 6.6+?

These questions can be explored in the onboarding framework #61040.

[afragen]

Test Report for WooCommerce

Description

This report validates whether the indicated patch works as expected.

Patch tested: ​https://github.com/WordPress/wordpress-develop/pull/6606

Docker local environment used.
Patch applied.
Docker environment built and initiated.

Environment

• WordPress: 6.6-alpha-57778-src
• PHP: 8.2.19
• Server: nginx/1.25.5
• Database: mysqli (Server: 8.0.37 / Client: mysqlnd 8.2.19)
• Browser: Safari 17.5
• OS: macOS
• Theme: Twenty Twenty-Four 1.1
• MU Plugins: None activated
• Plugins:
  • Test Reports 1.1.0
  • WooCommerce 8.9.1

Actual Results for Test in Add Plugins UI

After activation:

✅ the "Refresh now" admin notice and button do not appear.
✅ auto-redirects to WooCommerce's onboarding wizard.

Actual Result for Test in Modal

After activation:

✅ at the bottom of the modal, the "Refresh now" admin notice and button do not appear.
✅ auto-redirect to WooCommerce's onboarding wizard.

[jorbin]

While the behavior in 6.5.4 would be to redirect, I think it would be beneficial if this filter documentation included a specific promise about backwards compatibility so it's clear to people using it about what could change (and what will not). I know there are people who believe that the change of behavior which prevented redirects is a backward compatibility break and I would like to prevent that disagreement when/if that behavior goes away again.

What are folks thoughts on the following language to be used in a devnote and in the inline documation:

This hook has a specific backward compatibility promise. The functionality that it causes is not guaranteed to remain consistent, however the behavior of specific parameters will not change. For instance, the redirect_url parameter will not be reused but can (and likely will) be deprecated as the plugin installation experience evolves.

This would also mean we would want to rename the parameter from url to redirect_url so that it is more specific. It has the benefit of reducing confusion and being forwards compatible but it comes at the cost of requiring plugin developers to stay on top of changes. I think that cost is reasonable since if you are releasing a plugin you should be expected to test it and update it for every major WordPress release.

[hellofromTonya]

For instance, the redirect_url parameter will not be reused but can (and likely will) be deprecated as the plugin installation experience evolves.

I'd recommend changing "will not be reused" to "may not be reused". Why? Decisions have not been finalized on what may or may not happen with the onboarding framework in relationship to the workflow of install > activate > configure.

Going into this ticket, the url is currently being considered to remain, but may change as the workflow experience evolves.

[hellofromTonya]

Replying to jorbin:

This would also mean we would want to rename the parameter from url to redirect_url so that it is more specific. It has the benefit of reducing confusion and being forwards compatible but it comes at the cost of requiring plugin developers to stay on top of changes. I think that cost is reasonable since if you are releasing a plugin you should be expected to test it and update it for every major WordPress release.

I don't think the parameter needs to be renamed.

Why?

The url parameter is in the "configuration data". It is the URL where a user will configure the plugin. Users go to that URL via redirect in 6.5.4 and possibly by some other means (e.g. by a new user action) in the future. Thus, it's not a redirect_url, but rather the plugin's configuration url.

In other words, what may change in the future is how the URL is triggered.

I advocate for leaving it as url, as it aligns well for the intent of today and into the future (with what is known today).

[kevinwhoffman]

I agree with @hellofromTonya that we should not conflate the behavior of how a user gets to the URL, which may change, with the purpose of the URL, which should not change.

However, for flexibility in the future, I do recommend naming this parameter something more specific such as onboarding_url to represent the location in which users should be immediately directed to upon activation.

In 6.5.X, onboarding may be accomplished through a redirect. In 6.6+, onboarding may be accessed through a new button in the plugin card. Either way, plugin developers have shown through their past use of redirects that they have a singular URL in mind where they want all of their users to begin experiencing their plugin. This parameter would address that need.

By naming the parameter onboarding_url rather than url, it also leaves the door open for other types of URLs that may be relevant and useful to the onboarding framework.

Potentially useful URLs to define via this filter

• onboarding_url - This is the URL being described in this ticket. It is where users are directed to upon plugin activation. This URL could represent an interactive onboarding wizard (e.g. the WooCommerce setup wizard) for initial configuration or a getting started guide that is more about education than configuration. Consider a plugin that may not have settings or a presence in the admin menu, but would still benefit from an onboarding experience. By using the term "onboarding," we clarify its purpose without prescribing how users get there (as determined by core) or what they do when they get there (as determined by the plugin).
• main_url - This could be used by the onboarding framework to determine where users land after onboarding is complete. It is also where users would generally think of as the "home page" for a particular plugin. It's where they go to start using a plugin that has already been configured (e.g. navigating to "WooCommerce" or "ACF" in the admin menu).
• configuration_url - This is where users go to generally configure a plugin over time (e.g. the WooCommerce settings page). Consider a user who has already completed onboarding. There may be places in WP Admin where it becomes more appropriate to show this general configuration URL as opposed to an onboarding experience that is catered to first-time use.

Using WooCommerce as an example

• onboarding_url - admin.php?page=wc-admin&path=%2Fsetup-wizard
• main_url - admin.php?page=wc-admin
• configuration_url - admin.php?page=wc-settings

To be clear, the concepts of a main_url or configuration_url are just ideas to be explored further in #61040. I'm sharing those possibilities here so that others might see the value of naming this parameter onboarding_url. I believe we know enough about its purpose to make that call today, even if we don't know all of the details about the onboarding framework to come.

I wonder if we should change url in the filter parameters into something more specific?

I could imagine this filter being extended in the future with additional parameters, and maybe we would end up with a settings_url and a onboarding_url for example:

• settings_url being used for URLs such as the "Settings" links plugin authors will often add to the plugin list table with the plugin_action_links_{$plugin_file} filter
• onboarding_url being a unique URL to start onboarding when the plugin is first activated, like Yoast SEO's wp-admin/admin.php?page=wpseo_installation_successful_free.

[costdev]

Note that the impact of removing the redirect in 6.5 was not just on onboarding experiences, but also on plugin menu items not being loaded. This ticket mentions "onboarding | set up | configure", not just onboarding. This filter in 6.5.4 could therefore be used to direct a user to the plugin's main URL, the settings URL, the onboarding URL, or any other URL. We just don't know what is the most appropriate URL for all plugins.

Also note that the plugin author may change the URL depending on what they want to provide at various points of tracking state. They may even have states that mean providing "onboarding", "settings", and "main" URL at different stages of setup, or on a subsequent activation where onboarding shouldn't be provided (such as on reactivation after debugging, or updating the plugin).

Therefore, to choose one of the suggested names for the parameter now would mean only communicating one use case or behaviour, and I think it's best that we allow plugin authors to make the decision about what the URL should be and when.

If it's strongly desired to change the parameter's name, keep the above in mind when brainstorming alternative names.

In terms of communication, I agree that we should make it clear that the array's contents may be extended as the experience evolves. We should however be confident that this URL parameter will remain in place, with the name at the time of commit, for the foreseeable future. If we don't have that confidence in the name now, then I agree we should rename it - again, with the above considerations in mind.

[kevinwhoffman]

The ticket description says:

As of WP 6.5.0, users are no longer able to quickly go from install to onboarding | set up | configure.

If the goal of onboarding is to ensure a smooth and efficient transition for users, reduce time to value, and increase user engagement and retention, then it's reasonable to say that setup/configuration are synonyms for onboarding when positioned immediately after activation. Thus an onboarding_url parameter can satisfy all of the above.

Therefore, to choose one of the suggested names for the parameter now would mean only communicating one use case or behaviour, and I think it's best that we allow plugin authors to make the decision about what the URL should be and when.

The parameter name should indicate the use case or purpose, but not the behavior. If we have an all-purpose url parameter and rely on the plugin to define the appropriate value from one use case to another, then we limit the potential for WordPress core, developers, users, and hosts to benefit from a standardized set of parameters that they can rely on for specific purposes.

For example:

• An onboarding framework in WordPress core may benefit from knowing where to direct a user when onboarding is complete (e.g. the plugin's main_url) without having to rely on plugin-specific logic to determine the appropriate value of url.
• A user or developer who installs WooCommerce on every site may want to skip the onboarding wizard by filtering the value of onboarding_url without affecting other use cases for a url. This is a scenario where the best onboarding experience for that user is to not have to click through a wizard at all.
• Similarly a multisite developer may want to disable the onboarding wizard (see ​real-world example).
• A host with an ecommerce offering may want to direct the user to a host-specific version of onboarding to ensure they get the most out of their ecommerce solution on that host.

The discussion around AJAX plugin activation (#60992), the discussion to date about the onboarding framework (#61040), and this entire ticket have been about facilitating an entry point to an onboarding experience in whatever form makes sense from one plugin to the next. The common thread across all conversations is that we're trying to improve the experience immediately after plugin activation, where an onboarding_url can be defined or modified to provide an onboarding experience that is appropriate for each user based on their needs, abilities, and context. These are known onboarding challenges with a long history of cowpath solutions, so let's name this parameter accordingly in a way that does not limit what's possible in the future.

[hellofromTonya]

Replying to kevinwhoffman:

• An onboarding framework in WordPress core may benefit from knowing where to direct a user when onboarding is complete (e.g. the plugin's main_url) without having to rely on plugin-specific logic to determine the appropriate value of url.

Kevin, are you envisioning the possibility of a 4th step in the plugin workflow?
Install > Activate > Onboard | Set Up | Configure > 4th step after onboard.

Disabling onboarding for one or all plugins

I'm not understanding how adding separate configuration URL params achieves this goal. It shifts complexity into Core while also making it harder and unreliable for plugins, users, and hosts. How so?

I'll walk through each of the scenarios for more context.

If the goal is to provide a mechanism for users, plugins, hosts, etc to disable onboard for any combination of or maybe all plugins, a different approach will be needed. For example, another filter may be added to disable or skip all.

• A user or developer who installs WooCommerce on every site may want to skip the onboarding wizard by filtering the value of onboarding_url without affecting other use cases for a url. This is a scenario where the best onboarding experience for that user is to not have to click through a wizard at all.

Noting the example from past comment:

onboarding_url - admin.php?page=wc-admin&path=%2Fsetup-wizard
main_url - admin.php?page=wc-admin
configuration_url - admin.php?page=wc-settings

Onboarding may be triggered for one or more of these specific URLs for some plugins, i.e. until the onboarding is completed or dismissed.

For example, WooCommerce's onboarding_url and main_url both launch the setup wizard.

Thus for these plugins, a user would need to filter each of the URL params in order to disable the wizard. Plus it's not guaranteed if another plugin's priority or place in the priority queue is higher / later in the call stack.

• Similarly a multisite developer may want to disable the onboarding wizard (see ​real-world example).

Same problems as noted above.

• They'll need to know which plugins' URL params trigger their onboarding (such as in the case of WooCommerce where both the onboarding_url and main_url trigger the wizard.
• It's not guaranteed a plugin's filtering to disable is called last in the hook queue to disable it, making it unreliable.

Hosts change URL to direct to their experience

• A host with an ecommerce offering may want to direct the user to a host-specific version of onboarding to ensure they get the most out of their ecommerce solution on that host.

Similarly a host can filter the configuration data's url for a specific plugin to change the url to point to where they want users to land.

[hellofromTonya]

While I appreciate the consideration and use cases, I thinking all of the scenarios presented (except for a maybe 4th step) are achievable with the current design of one entry url.

Then if later in the future, more use cases are discovered that require different consideration, such as the ability to disable all onboarding, how to achieve those can be explored, e.g. adding another filter.

For this phase, I agree with @costdev. The configuration data he proposes fits today and the future's intent and needs.

[hellofromTonya]

Replying to hellofromTonya:

While I appreciate the consideration and use cases, I thinking all of the scenarios presented (except for a maybe 4th step) are achievable with the current design of one entry url.

Then if later in the future, more use cases are discovered that require different consideration, such as the ability to disable all onboarding, how to achieve those can be explored, e.g. adding another filter.

For this phase, I agree with @costdev. The configuration data he proposes fits today and the future's intent and needs.

That said, if there's a real world case and strong possibility a 4th step is needed in the plugin install > activate > onboard workflow, then that use case might be a reason to rename it onboarding_url (i.e. where onboarding = onboard | set up | configure.

[hellofromTonya]

Test Report for Yoast SEO

Patch tested ​https://github.com/WordPress/wordpress-develop/pull/6606 as of ​this commit

Yost SEO from plugins repo ​https://wordpress.org/plugins/wordpress-seo/.

Environment

• OS: macOS
• Web Server: nginx
• PHP: 8.3
• WordPress: 6.5.3 with this PR applied
• Browser: Firefox 126.0
• Theme: default
• Plugins: Yoast SEO 22.7 with the sample code added:

add_filter( 'plugin_configuration_data_wordpress-seo', static function() {
        return array(
                'url' => admin_url( 'admin.php?page=wpseo_installation_successful_free' ),
        );
} );

Actual Results for Test in the Add Plugins UI

After activation:

• ✅ the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirects to Yoast SEO's onboarding wizard.

Actual Results for Test in the More Details modal

After activation:

• ✅ at the bottom of the modal, the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirect to Yoast SEO's onboarding wizard.

Actual Results for Test another plugin that requires Yoast SEO

Did not test, as there are no plugins requiring it.

[hellofromTonya]

Test Report - Relative URL

What happens if the configured url is relative instead of absolute URL?

Using the Yoast SEO Test Report, I modified the plugin code:

add_filter( 'plugin_configuration_data_wordpress-seo', static function() {
        return array(
                'url' => 'admin.php?page=wpseo_installation_successful_free',
        );
} );

Same results - all tests still pass ✅

[jorbin]

My goal with suggesting the specific backward compatibility language and switch from url to redirect_url is to lessen the surpise when the redirect is no longer automatic and instead is a button press or something else.

When that time comes, we can create a new _deprecated_paramater that will fire if someone passes in redirect_url after it is no longer used

If it is decided that there shouldn't be a specific backwards compatibility promise to not re-use parameters for anything other what they are first introduced for, I think url is a good name. In that case, I still think it would be good to make it clear in the filter documentation that user interface behavior is not guaranteed to stay the same. So I would suggest something along the lines of:

User interface behavior caused by the configuration of specific values in this hook is not guaranteed to stay consistent between versions of WordPress.

[hellofromTonya]

Replying to jorbin:

My goal with suggesting the specific backward compatibility language and switch from url to redirect_url is to lessen the surpise when the redirect is no longer automatic and instead is a button press or something else.

Recently you shared with me that UI and workflows are not part of the BC promise. The filter and its parameter(s) are in the BC promise. @costdev designed the filter and url parameter with these in mind.

The auto-redirect after plugin activation is part of the UI and workflow. Core's control of the "how" and "when" are part of the UI and workflow. Its usage of the data registered by plugins and the entry point for plugins to register with Core are public facing and part of the BC promise. The intent and effect of Core using that configurable data is the same and part of the BC promise.

It's not a promise to auto-direct after plugin activation nor is it a promise of the workflow or mechanism. The UI and workflow may change.

If it becomes a button press or something else, the effect is the same -> Core provides the mechanism for loading the registered onboarding | set up | configure URL to move the user to the next step.

Does that make sense, @jorbin?

What about the filter's documentation?
I agree with you - it can be made more clear. To help mitigate confusion and possible surprise later, care needs to be given to how this change is communicated in Make/Core, the release, this ticket, etc.

What do you think?

[hellofromTonya]

After talking with @costdev (who will follow-up shortly with his thoughts), thinking there's confusion between the filter and the workflow behavior.

This filter does not drive the behavior. It's a configuration entry-point that Core will use.

Thinking Core and user behavior should not be part of the filter's docblock. Instead the filter's doc should focus on its purpose and how to register plugin configuration data with it.

[costdev]

I agree that we should consider whether it's appropriate to document the filter's behaviour in the docblock.

This filter, like all others, can be used in a variety of places and ways in Core, but all usage will reference the same docblock. How it's used today may change, which is already true of all filters and should be expected.

While I understand the reasoning behind the suggestion, I would be careful about using backward compatibility language here, as UI and workflows aren't something I personally consider to be within the scope of the BC promise (otherwise markup, attributes, element tags, order of elements, etc could never change - which would be a nightmare for a11y I'm sure we'd all agree). The only backward compatibility promises that we make with filters are that their hook name and parameters will not be changed (unless deprecated), and that they will remain available for extender usage even if deprecated. What happens with the filtered data is another matter.

I'd suggest that we answer "What am I filtering?" in the docblock, and "What does filtering this do?" in the 6.5.4 communications (dev note, release post, etc), noting there that how it behaves is subject to change with further evolution of the user experience, and extenders are strongly encouraged to work with us on this. If this seems insufficient to prevent tutorials and the like from communicating the wrong message to extenders, I'd recommend that we reach out to MarComms, Outreach, and possibly project leadership, to see if they can help with that communication.

[kevinwhoffman]

@hellofromTonya @costdev @jorbin Thanks for considering the possibility of multiple URLs. I think I am onboard with the single url parameter, but I do want to raise a question related to functionality that has been discussed around an onboarding framework in #61040.

If we want to offer the ability for plugin developers to customize link text associated with the onboarding URL (e.g. "Open", "Start Onboarding"), do you envision that link text being defined as a separate parameter in this same filter?

I'm attaching the mockup I shared previously to demonstrate how link text could end up being related to the url defined in this filter.

[costdev]

@kevinwhoffman While it's still early days for us to predict, yes, I can envisage that extra parameters may be added to this filter and that's the primary reason why it was designed to accept an array parameter rather than just a single (string) $url parameter.

For example:

<?php

// DO NOT USE. THIS IS NOT IMPLEMENTED IN WORDPRESS CORE.

add_filter( 'plugin_configuration_woocommerce', 'woocommerce_add_config_data' );

function woocommerce_add_config_data( $config_data ) {
    if ( $something_saying_onboarding_is_not_completed ) {
        $config_data['url']        = admin_url( 'admin.php?page=wc-admin&path=%2Fsetup-wizard' );
        $config_data['label']      = __( 'Get Started', 'woocommerce' );
        $config_data['aria_label'] = sprintf(
            /* translators: %s: WooCommerce. */
            __( 'Get started with %s.' ),
            'WooCommerce'
        );
    } else {
        $config_data['url']        = admin_url( 'admin.php?page=wc-admin' );
        $config_data['label']      = __( 'Open', 'woocommerce' );
        $config_data['aria_label'] = sprintf(
            /* translators: %s: WooCommerce. */
            __( 'Open %s.' ),
            'WooCommerce'
        );
    }

    return $config_data;
}

[lopo]

Replying to hellofromTonya:

Test Report for Yoast SEO

Patch tested ​https://github.com/WordPress/wordpress-develop/pull/6606 as of ​this commit

Yost SEO from plugins repo ​https://wordpress.org/plugins/wordpress-seo/.

Hey @hellofromTonya, I can confirm your tests: the patch + the snippet definitely restore the intended behavior for our plugin's activation and ensure the proper onboarding of new sites.
I'm already preparing a PR for our repo, I really hope this can be included in 6.5.4.

[pooja1210]

Hi,

Test Report for WooCommerce

Patch tested: ​https://github.com/WordPress/wordpress-develop/pull/6606

Environment
OS: macOS
PHP: 8.1
WordPress: 6.6-alpha-20240527.1
Browser: Chrome 125
Theme: Default

Plugins: WooCommerce v8.9.1 with the sample code added:

add_filter( 'plugin_configuration_data_woocommerce', static function() {
        return array(
                'url' => admin_url( 'admin.php?page=wc-admin' ),
        );
} );

Expected Result:
## Test in the Add Plugins UI:
After activation, the site is redirected to the WooCommerce onboarding wizard page ☑️

## Test in the More Details modal:
At the bottom, the refresh button is not visible and the site is redirected to the WooCommerce onboarding wizard page ☑️

Thanks

Thanks for working on this, @hellofromtonya -- it is testing well for me in the WooCommerce plugin so far.

Should WordPress keep track of whether the each plugin has completed onboarding, or should this logic be offloaded to the individual plugins? 🤔

For WooCommerce, there is already logic in the admin.php?page=wc-admin URL to determine whether configuration is incomplete and the onboarding should be shown over the home screen. This is necessary to prevent the onboarding unnecessarily showing again on "re-activation" (i.e. if the user performs the sequence: install > activate > onboarding > de-activate > activate). However it might be worth having WordPress know the state of completion so this logic can be built into WordPress directly. If so, there could perhaps be an additional completed key on the array for plugins to declare whether configuration has been completed:

add_filter( 'plugin_configuration_data_woocommerce', static function() {
	return array(
		'url' => admin_url( 'admin.php?page=wc-admin' ),
		'completed' => some_function_returning_true_or_false(),
	);
} );

[louiswol94]

Hi from Elementor,

Thank you to everyone leading this initiative, we really appreciate it.

I’m happy to report that it is working as expected on our side as well.

Similar to @adrianduffel's comment, we will rather redirect to another internal URL instead of the direct onboarding URL, so that we won’t re-run the onboarding on re-activations.

Replying to hellofromTonya:

Test Report for Elementor

Patch tested ​https://github.com/WordPress/wordpress-develop/pull/6606 as of ​this commit

Environment

• OS: macOS
• Web Server: nginx
• PHP: 8.3
• WordPress: 6.5.3 with this PR applied
• Browser: Firefox 126.0
• Theme: default
• Plugins: Elementor 3.21.7 with the sample code added:

add_filter( 'plugin_configuration_data_elementor', static function() {
        return array(
                'url' => admin_url( 'admin.php?page=elementor-app#onboarding' ),
        );
} );

Actual Results for Test in the Add Plugins UI:

After activation:

• ✅ the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirects to Elementor's onboarding wizard.

Actual Results for Test in the More Details modal:

After activation:

• ✅ at the bottom of the modal, the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirect to Elementor's onboarding wizard.

Actual Results for Test another plugin that requires the plugin you're testing

After activation of Elementor:

• ✅ at the bottom of the modal, the "Refresh now" admin notice and button do not appear.
• ✅ auto-redirect to Elementor's onboarding wizard.

After navigating back to the Add Plugins UI:

• ✅ able to activate plugins requiring Elementor.

Thanks for testing @adrianduffell.

Should WordPress keep track of whether the each plugin has completed onboarding, or should this logic be offloaded to the individual plugins?

That's an interesting question. If/when onboarding is integrated into the workflow, that might well be a state Core will need to track, i.e. for bringing the experience back for the next plugin in the chain and/or altering users of the current state.

I'm thinking it's too early though to introduce it in this scope of work for the minor.

Why? It needs discussion and consideration for how it and onboarding in general fits into the user + plug chain workflow. IMO it's better served in the onboarding framework Trac ticket.

Would you mind sharing that idea in that that ticket please?

[hellofromTonya]

Thanks everyone for testing and providing feedback - rock stars 🌟

• Testing (including from impacted plugin authors) confirms it works and meets the scope of this ticket.

• Feedback shows consensus to move forward.

What's next?

• Adjust the filter's description (in its docblock) to more clearly describe "What am I filtering?", not the behavior Core will take. ​Join the discussion here.

• When done, should be ready for commit.

[hellofromTonya]

Patch: ​https://github.com/WordPress/wordpress-develop/pull/6606

Ready for commit to trunk.

[hellofromTonya]

Assigning ownership to @costdev who will handle the commit.

[peterwilsoncc]

For plugin developers tracking this ticket, please note that the filter has been renamed to include a WordPress prefix: wp_plugin_configuration_data_{$slug}.

This is to avoid the potential for naming conflicts with third party code.

[hellofromTonya]

Update:

What if the AJAX could be changed without needing a filter in a minor release? Could such a change be made cleanly without causing other unknown issues?

Something the "Why not revert?" section in this ticket did not mention: a partial revert was messy and caused concerns of potential issues. It seemed too risky in a minor.

@costdev and I took another look at the AJAX and asked ourselves: What part of this changed that caused the regression and impacts? Could only that part be changed to restore the pre-6.5 behavior? Yes, there is a way.

#61319 is an alternative to this ticket. Like this ticket, it has pros and cons. Unlike this ticket, it does not introduce a filter nor requires changes in plugins.

Though there's support and consensus to move forward with this ticket (the filter), IMO it's worth pausing to consider #61319. Which approach is better for the minor (to resolve the impacts and regression) and the future?

Action Item:

@costdev and I invite your feedback and testing of #61319 (please in that ticket for capturing context and history in one place).

[hellofromTonya]

Summary of feedback from today's Dev Chat, held in Making WordPress slack core channel:

Link to start of the thread: ​https://wordpress.slack.com/archives/C02RQBWTW/p1717013066479629

@afragen shared:

I believe the simplest approach is in #61319

@mikachan shared:

I don't have much background knowledge here, but after reading @hellofromtonya’s latest comment on #61319, I agree that this sounds like the best approach (less code, restores the previous native behavior of the Activate button) :+1:

@ironprogrammer shared:

I like that this [i.e. #61319] addresses the originally reported regression w/o adding anything new. Better adherence to the scope that is expected in a minor release.

@joemcgill asked:

Would it be good to get feedback from the folks who were critical of the initial approach?

Well, it sounded like you looked into the alternate approach after feedback from

@swissspidy and @azaozz, so it may be good to get their feedback on the new approach. Generally speaking, I think we need to be pretty confident in the approach before shipping it in a minor release so getting extra PR feedback and testing is good practice

for which I shared both were pinged requesting their feedback (​here and ​here).

[hellofromTonya]

I'm removing the commit keyword until there's consensus on whether to move forward with this ticket or #61319.

Both ticket's patches are ready for commit, but only one should be committed.

[hellofromTonya]

Hello all,

Thank you everyone for contributing to this ticket and effort. Power of open source!

The work done here fits better into a major release, i.e. into Trac #61040. Notice, there were back-and-forth discussions about what parameters should and shouldn't be in and what the naming of them should be in the configuration data registration. These kinds of discussions are important and need thoughtful consideration and experimentation.

But that's the point: the onboarding / configuration step into the add plugin workflow is still in the ideation stage. Time is needed for the idea to become a next step.

While there's a strong intent that the filter is and will be part of the next step / workflow, there's still a risk that maybe it or the url parameter might not fit what that idea becomes. Thus, it locks in the entry point or could cause a deprecation.

With the new approach in #61319, it directly addresses the scope of the regression. There's consensus to move forward with that approach for the minor.

This ticket is being closed in favor of #61319. But the work and discussions here are the part of the ideation stage and need to continue on into the next step, i.e. continue in #61040.

I invite you all to stay actively engaged and contributing to #61040 and the next step in refining and defining the add plugin workflow and how configuration / onboarding fits into it to improve the experience for the majority of the users.

Thank you again. Happy contributing :)

Trac note:
I'm marking this as a duplicate of #61319. Though the implementation is not a duplicate, the problem it seeks to solve, i.e. the regression, is the same.

Closing in favor Trac 61319 and its patch #6670.

Thank you everyone for contributing to this effort 🥇 This work can continue in https://core.trac.wordpress.org/ticket/61040 as part of a major release.