Activate a plugin through code

Plugins must be installed by adding them to the /plugins directory of an application’s GitHub repository in order to be available for activation. Once installed, it is possible to activate the plugins in the WordPress Admin dashboard (WP Admin). However, it is recommend to code-activate plugins instead to gain greater control and consistency across all environments (e.g., production, non-production, and local development environments).

By default a plugin-loader.php file is located within the /client-mu-plugins directory. Use this file to selectively code-activate third-party plugins that are located in /plugins, and custom plugins that are located in subdirectories of /client-mu-plugins.

Determining a plugin’s name for code activation

A plugin’s “name” will most often be identical to the directory encapsulating the plugin. For example, a plugin directory named my-plugin will most often have a main file directly within it named my-plugin.php. Because the directory and the main file naming match, the plugin’s name is: my-plugin.

When a plugin’s main file is named differently than the directory, the name may include the path to the plugin’s main file. For example, a plugin directory named my-plugin that has a main file directly within it named plugin.php. Because the directory and the main file naming do not match, the plugin’s name is: my-plugin/plugin.php.

If a plugin consists of only a single PHP file, and it is installed to the root of /plugins (e.g. /plugins/my-plugin.php), the plugin name may be the file name, for example: my-plugin.php.

Output from the WP-CLI command wp plugin list can be used to retrieve a plugin’s name. The &plugin= parameter value visible in the link to activate (or deactivate) a plugin on a site’s WP Admin Plugins dashboard will also include a plugin’s name.

Code-activating plugins in /plugins

Third-party plugins should be installed by adding them to an application’s /plugins directory. The plugins can be code-activated with the wpcom_vip_load_plugin() function.

The wpcom_vip_load_plugin() function only works for plugins that have been installed in the /plugins directory of an application’s GitHub repository.

If the plugin name cannot be resolved to a plugin in the /plugins directory, the wpcom_vip_load_plugin() function will throw an E_USER_WARNING type error.

Activate a plugin by passing the plugin’s name in the wpcom_vip_load_plugin() function in /client-mu-plugins/plugin-loader.php.

// Activate the plugin located in `/plugins/plugin-name`.
wpcom_vip_load_plugin( 'plugin-name' );

// // Activate a specific plugin file: `/plugins/other-plugin-name/plugin-name.php`.
wpcom_vip_load_plugin( 'other-plugin-name/plugin-name.php' );

When a plugin is successfully activated through code, the text “Enabled via code” will be displayed under the plugin’s name in the list of plugins on the site’s WordPress Admin dashboard. The action links that usually allow users to Activate or Deactivate the plugin through the admin user interface will be removed and unavailable.

Code-activating plugins in /client-mu-plugins

Plugins that are installed in /client-mu-plugins, and are programmatically activated, are automatically included early in the WordPress load order as MU (“must use”) plugins. Only custom plugins with code that needs to be auto-loaded or run earlier in the WordPress load process should be installed in /client-mu-plugins. 

Use the WPCOM_VIP_CLIENT_MU_PLUGIN_DIR constant to point to an application’s /client-mu-plugins, followed by the path to the plugin’s main file.

In this code example, a plugin named /plugin-name/plugin-name.php located in /client-mu-plugins is activated via code and loaded as an MU plugin:

<?php
require WPCOM_VIP_CLIENT_MU_PLUGIN_DIR . '/plugin-name/plugin-name.php';

Code-activating plugins on a multisite

Plugins loaded with wpcom_vip_load_plugin() on a WordPress multisite will be network-activated, unless logic is added to selectively activate that plugin on a per-site basis by using the get_current_blog_id() function.

In this code example, a plugin located in a directory named plugin-name will be activated only for network site ID 2, while a plugin located in a directory named common-plugin will be activated for all sites on the network:

// Activate the plugin located in `/plugins/plugin-name/` for network site ID 2.
if ( get_current_blog_id() === 2 ) {
    wpcom_vip_load_plugin( 'plugin-name' );
}
// Activate the plugin located in `/plugins/common-plugin/`for all sites on the network.
wpcom_vip_load_plugin( 'common-plugin' );

Code-activating plugins in theme or plugin code

Activating plugins through code from within a theme or plugin is not recommended.

Whenever possible, use the /client-mu-plugins directory methods described above to call the wpcom_vip_load_plugin() function before the plugins_loaded hook is fired.

If a plugin’s functionality absolutely must be tied to a theme, the wpcom_vip_load_plugin() function should be called before the after_setup_theme hook. Though this method is supported, doing so will trigger a “called incorrectly” PHP notice.

Plugins that require an activation hook

Some plugin code expects that the plugin will be manually activated in the WordPress Admin dashboard. That plugin code often relies on register_activation_hook() to fire and run functions which establish conditions which the plugin relies on to work as expected.

The register_activation_hook() will not fire if a plugin is code-activated. For plugins that rely on register_activation_hook(), a couple extra steps can ensure that the new plugin gets set up correctly:

1. Install the plugin by committing it to the application’s GitHub repository.
2. Activate the plugin from the site’s WordPress Admin dashboard Plugins screen.
3. Follow instructions above to code-activate the plugin in plugin-loader.php.