Plugin Dependencies on Other Plugins in WordPress 6.5

Extensibility through plugins and API hooks is a core feature of WordPress. There are many plugins that serve as extensions for other plugins. The new functionality "Plugin Dependencies" aims to make the process of installing and activating add-ons (dependents) and the plugins they depend on (dependencies) clear, consistent, and simple.

New Plugin Header — Requires Plugins

A new header Requires Plugins has been introduced.

It should contain a comma-separated list of plugin slugs that the current plugin depends on (usually the name of the plugin folder). For example, my-plugin.

Example of Using the New Header

/**
 * Plugin Name: Express Payment Gateway Checkout for Shop
 * Requires Plugins: shop, payment-gateway
 */

Requirements

Dependent Plugins

The following requirements apply to dependent plugins:

• Cannot be installed until dependencies are installed.
• Cannot be activated until dependencies are activated.

Plugin Dependencies

The following requirements apply to dependencies:

• Cannot be deactivated while dependent plugins are active.
• Cannot be deleted while dependent plugins are installed.

What if a dependency no longer exists?

If a dependency plugin is manually removed, for example, via FTP, during deployment, or in any other way, a notification will be shown on the plugin management screens indicating that dependencies are missing. Additionally, each dependent whose dependencies are no longer met will have an error notification.

What if a plugin gains a new dependency during an update?

The update will be allowed at that moment, and the dependent plugin will remain active. A notification will be displayed on the plugin management screens informing the user that dependencies are missing for installation and/or activation.

What happens if there are circular dependencies?

A circular dependency occurs when a plugin depends on another plugin, which in turn depends on a third plugin, which depends back on the first plugin.

For example: Plugin A requires Plugin B, which requires Plugin C, which requires Plugin A.

"Plugin Dependencies" includes detection of circular dependencies and will display a notification about the plugins whose requirements are invalid. Plugins cannot be activated, and users must contact the plugin authors to break this circular link if necessary.

Is "protective code" still needed to check dependencies?

No. Plugin Dependencies simplifies the installation and activation of dependency plugins. This means that plugin authors can safely remove checks and notifications when their dependencies are not installed or activated.

However, at this time, Plugin Dependencies does not include support for minimum or maximum versions for dependencies, and does not consider the loading order of plugins. Therefore, plugin authors should continue to use (function|class|interface)_exists() and version checks if their plugin depends on specific functionality in a certain version.

WP-CLI and Plugin Dependencies Functionality

Plugin Dependencies does not prevent the installation of dependent plugins without their dependencies through WP-CLI, as it is assumed that those using WP-CLI are experienced users who are aware of the dependency stack.

However, to avoid unnoticed missing dependencies, dependent plugins cannot be activated via WP-CLI until their dependencies are activated.

This affects the command wp plugin activate --all, which may require multiple runs if a dependent plugin appears alphabetically before its dependencies.

Limitations

Plugins Hosted in the WordPress.org Directory

Dependent plugins hosted on WordPress.org can declare dependencies that are also hosted on WordPress.org. If your plugin hosted on WordPress.org requires plugins that are not hosted there, it is currently recommended not to use the Requires Plugins header in your plugin.

Plugins Not Hosted in the WordPress.org Directory

Dependent plugins not hosted on WordPress.org can declare dependencies, whether they are hosted on WordPress.org or elsewhere. However, the user interface will not provide a link to install third-party dependencies, and they will need to be found and installed manually.

Must-Use Plugins as Dependencies

Must-Use plugins as dependencies are currently not supported by the WordPress core. Discussion will continue in ticket #60504.

Themes Requiring Plugins

Themes requiring plugins are currently not supported by Plugin Dependencies, and theme authors should continue to use checks and messages in the code.

New Filter

A new hook filter wp_plugin_dependencies_slug has been introduced to modify the slugs of dependencies. For example, if a dependent plugin declares my-plugin as a dependency, and there is a premium version of my-plugin, the premium version can filter the slug and convert it to my-plugin-pro so that "Plugin Dependencies" can detect it.

Example of Using the Filter

add_filter( 'wp_plugin_dependencies_slug', 'convert_myplugin_to_myplugin_pro' );

function convert_myplugin_to_myplugin_pro( $slug ) {
	if ( 'my-plugin' === $slug ) {
		$slug = 'my-plugin-pro';
	}

	return $slug;
}

User Interface Changes

Plugins > Installed Plugins

The following changes have been made:

• The rows of dependent plugins now contain a list of their dependencies linked to the corresponding modal windows of the plugin for installing and activating the dependency.
• The rows of dependency plugins now contain a list of their dependent plugins.
• If a plugin has unresolved and inactive dependencies, the Activate link does not work.
• If a plugin has active dependent plugins, the Deactivate and Delete links do not work.
• Bulk actions are disabled for dependency plugins.

Plugins > Add New

The following changes have been made:

• If a plugin has unresolved dependencies, the Install Now and Activate buttons do not work, both on the plugin card and in the plugin information modal.

• The cards of dependent plugins now contain a notification with a list of their dependencies, with a Learn More link to a modal window with information about the dependency, which contains Install Now or Activate buttons (depending on the status).

• Plugin information modal windows now persist after button clicks, and the installation and activation of a plugin through the modal window is now performed via AJAX directly in the modal.

Deployment Process

Due to the unified AJAX approach now used on the Plugins > Add New screen, activating a plugin will no longer automatically redirect to the Plugins > Installed Plugins page or to deployment processes implemented by plugin authors. This allows users to install and activate multiple plugins without leaving the current context.

Plugins with deployment processes usually include checks so that, for example, if a plugin is installed and activated via WP-CLI, the deployment process will run when the user visits one of the plugin's settings pages. Such implementations will not be affected by Plugin Dependencies, nor will activation from the Plugins > Installed Plugins page through the Activate link.

New Class WP_Plugin_Dependencies

A new class WP_Plugin_Dependencies has been introduced.

The following public (API) methods are available:

::has_dependents( $plugin_file )

Determines if a plugin has plugins that depend on it.

• Parameter: $plugin_file string - The plugin file relative to the plugins directory.
• Returns: bool Whether the plugin has plugins that depend on it.

::has_dependencies( $plugin_file )

Determines if a plugin has dependencies on other plugins.

• Parameter: $plugin_file string - The plugin file relative to the plugins directory.
• Returns: bool Whether the plugin has dependencies on other plugins.

::has_active_dependents( $plugin_file )

Determines if a plugin has active dependent plugins.

• Parameter: $plugin_file string - The plugin file relative to the plugins directory.
• Returns: bool Whether the plugin has active dependent plugins.

::get_dependents( $slug )

Gets the file paths of plugins requiring the dependency.

• Parameter: $slug string - The slug of the dependency.
• Returns: array An array of file paths of dependent plugins relative to the plugins directory.

::get_dependencies( $plugin_file )

Gets the slugs of plugins that require the dependency.

• Parameter: $plugin_file string - The plugin file relative to the plugins directory.
• Returns: array An array of slugs of dependent plugins.

::get_dependent_filepath( $slug )

Gets the file path of the dependent plugin.

• Parameter: $slug string - The slug of the dependency.
• Returns: string|false The file path of the dependent plugin relative to the plugins directory, or false if the plugin has no dependencies.

::get_dependency_filepath( $slug )

Gets the file path of the dependency, relative to the plugin directory.

• Parameter: $slug string - The slug of the dependency.
• Returns: string|false If installed, the file path of the dependency relative to the plugins directory; otherwise, false.

::has_unmet_dependencies( $plugin_file )

Determines if a plugin has unmet dependencies.

• Parameter: $plugin_file string - The plugin file relative to the plugins directory.
• Returns: bool Whether the plugin has unmet dependencies.

::has_circular_dependency( $plugin_file )

Determines if a plugin has a circular dependency.

• Parameter: $plugin_file string - The plugin file relative to the plugins directory.
• Returns: bool Returns true if the plugin has a circular dependency.

::get_dependent_names( $plugin_file )

Gets the names of the plugins that require this plugin.

• Parameter: $plugin_file string - The plugin file, relative to the plugins directory.
• Returns: array An array of the names of dependent plugins.

::get_dependency_names( $plugin_file )

Gets the names of the plugins that are required for this plugin.

• Parameter: $plugin_file string - The plugin file, relative to the plugins directory.
• Returns: array An array of the names of required plugins.

::get_dependency_data( $slug )

Returns the API data for the dependency.

• Parameter: $slug string - The slug of the dependency.
• Returns: array|false The API data of the dependency on success, or false on failure.

--

Ticket: #22316 WordPress function Plugin Dependencies.

Source: https://make.wordpress.org/core/2024/03/05/introducing-plugin-dependencies-in-wordpress-6-5/