Skip to content

Backgrounds

How-to Guides

Technical References

Activate plugins through code

Plugins in the /plugins directory can be activated and deactivated through the standard WordPress method of using the Plugins menu in the WordPress admin area (wp-admin). However, on the VIP platform we strongly recommend activating plugins through code. Activating plugins through code results in more control and greater consistency across production, non-production, and local development environments.

Activating Plugins in the /plugins directory

On the VIP platform you can activate plugins using the wpcom_vip_load_plugin() function. The wpcom_vip_load_plugin() function only works for plugins in the /plugins directory, the preferred location for managing 3rd party plugins. We recommend using a plugin loader file in the /client-mu-plugins directory, for example the VIP skeleton repo uses our recommended filename /client-mu-plugins/plugin-loader.php (example). To use the wpcom_vip_load_plugin() function, pass the name of a plugin that is available in the /plugins directory. 

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

When a plugin is successfully activated through code on the VIP platform, it will display the text “Enabled via code” under the plugin’s name in the Plugin page within the wp-admin. This replaces the action links that would have allowed users to Activate or Deactivate through the admin user interface.

Activating plugins installed in the /client-mu-plugins directory

To activate plugins in the /client-mu-plugins directory you need to include the plugin’s main file. You may choose to combine the code for this with other plugin activation techniques in the /client-mu-plugins/plugin-loader.php file. The /client-mu-plugins directory is best for custom plugins, 3rd party plugins are best managed in the /plugins directory.

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

/**
 * Activate the plugin located in `/client-mu-plugins/my-plugin/my-plugin.php`.
 */
require WPCOM_VIP_CLIENT_MU_PLUGIN_DIR . '/my-plugin/my-plugin.php';

Files added to the /client-mu-plugins directory are considered Must Use files. Any PHP files in the root of a Must Use directory are automatically included early in the WordPress load order, unlike plugins and themes, which require activation in order to be loaded. For additional information on how this works and other best practices around Must Use directories on VIP, please reference the documentation for /client-mu-plugins directory and plugins load order.

Determining a plugin’s name

Plugin names come in a variety of formats, depending on how the plugin is structured. Most commonly the name matches the directory encapsulating the plugin, for example: my-plugin when the plugin’s code is installed in the path /plugins/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: my-plugin/plugin.php. In the least common case, if a plugin is a single file in the root of the /plugins directory, the plugin name may be the filename, for example: my-plugin.php.

One method to identify a plugin’s name is to see how the WP-CLI command wp list plugins identifies it. You can also inspect the &plugin= parameter in the link to activate (or deactivate) a plugin on the wp-admin Plugins page.

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.

Multisite plugin activation

On a multisite install, use the get_current_blog_id() function to activate plugins on a per-site basis.

/**
 * For site ID 2:
 * - Activate the plugin located in `/plugins/plugin-name/`.
 */
if ( get_current_site_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' );

Activating plugins through code in a theme or plugin

VIP does not recommend activating plugins through code from within a theme or plugin. For the best results, we recommend calling the wpcom_vip_load_plugin() function before the plugins_loaded hook is fired, by using the /client-mu-plugins directory methods described above. If a plugin’s functionality must be tied to a theme, you should aim to call the wpcom_vip_load_plugin() function before the after_setup_theme hook. While supported, doing so will trigger a “called incorrectly” PHP notice.

Last updated: April 09, 2021

Related Topics