Activate plugins through code

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

A plugin-loader.php file should be 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 /client-mu-plugins.

Activating plugins in /plugins

Third-party plugins should be loaded from the /plugins directory. They can be activated with the wpcom_vip_load_plugin() function.

The wpcom_vip_load_plugin() function only works for plugins that have been added to 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 Plugin dashboard of the site’s WordPress Admin dashboard. This replaces the action links that would have allowed users to Activate or Deactivate through the admin user interface.

Activating plugins in /client-mu-plugins

Plugins that are added to /client-mu-plugins, and are programmatically loaded, 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 added to /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 enabled via code and loaded as an MU plugin:

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

Plugin activation for multisite

Plugins loaded with wpcom_vip_load_plugin() on a WordPress multisite will be network-activated, unless logic is added to selectively load 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 load only for network site ID 2, while a plugin located in a directory named common-plugin will load for all sites on the network:

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

Determining a plugin’s name

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 added 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.

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 below to code-activate the plugin in plugin-loader.php.

Activating plugins through code in a theme or plugin

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.