Installing and activating plugins on VIP Go

VIP Go platform specific

This document is for sites running on VIP Go.

Learn more

Overview #

Before reading this, it will be useful to read our documentation on your VIP Go codebase.

This is the preferred approach for installing and activating plugins for VIP Go:

  • Add the plugins to your plugins directory
  • Activate the plugins via a plugin loader file in client-mu-plugins

Plugins can also be activated via the “Plugins” screen on your WordPress admin area.

If you are familiar with developing for hosted VIP sites, you no longer need to bundle your custom plugins with your theme and we would encourage installing to the plugins directory in your site’s repository.

↑ Top ↑

Installing plugins #

On VIP Go, all plugins must be installed by adding them to your Git version control repository, hosted on GitHub. Having the plugin code in git version control allows multiple developers in your own team, and of course in the VIP team, to work on your code together, maintain and improve the site, and debug issues. On VIP Go, we deploy the code from git, which also allows us to roll back to a previous “known good” state, if the site encounters issues. (Please note, adding plugins via the WordPress admin area is not supported.)

As the VIP Go workflow is Git-based, you can also reference subtrees (preferred) or submodules in your repository which will make maintaining third-party code easier.

Subtrees #

A subtree workflow for dependencies will pull a copy of the code into your repository. The VIP Go code analysis bot will run automatic code reviews on subtree code when subtree code is added or changed in a pull request.

↑ Top ↑

Submodules #

Using submodules for code dependencies uses a reference to the code to check it out and include it in your repository. This process is dependent on the submodule existing and being available, as it maintains a reference, but not a copy, of the code. The VIP Go code analysis bot will not run automatic code reviews on code from an added or updated submodule, as a submodule is only a reference to another repository.

If your organization controls the submodule source, a submodule structure can be an option for you to include dependencies. If you don’t control the submodule source, we don’t recommend using a submodule structure, especially on production. If the third party code changes upstream (becomes inaccessible, has its history changed, or otherwise becomes invalid), your submodule reference runs the risk of breaking functionality on your production site.

VIP Go currently only supports public submodules; i.e. you cannot submodule a private GitHub repository or a Git repository hosted elsewhere that requires authentication.

Note that some plugin repositories, such as that for AMP for WordPress, contain unbuilt versions whereby the command, composer install, needs to be run for the plugin to work properly. Repositories like this one cannot be referenced as submodules as we do not run these build commands on the server. In such cases, developers should use one of the other methods outlined on this page.

↑ Top ↑

Installing to the plugins directory #

On VIP Go, there is a dedicated plugins directory in the root of the site git repository; this directory works similarly to WP_CONTENT_DIR . '/plugins/' in a self-hosted WordPress installation. Installing plugins to this location is a matter of adding the plugin to a unique directory in plugins, e.g. plugins/my-plugin, commit, then push to GitHub (see our documentation on how code is deployed on VIP Go).

We recommend that third-party plugins always go in the plugins directory, to allow for better compatibility with systems (like security-related plugin updates) that expect plugins to be in a specific location. Custom plugins can go in either the plugins or client-mu-plugins directory, depending on the preferred loading behaviour.

Loading or activating plugins in the plugins directory

The plugins in the plugins directory can be activated and deactivated from the standard Plugins menu in the WordPress admin area, however, we recommend loading your plugins from code. Loading plugins in code results in more control and a greater consistency across your production, non-production environments, and local development environments.

If loading your plugins via code, you should use a plugin loader file in client-mu-plugins (example) using the wpcom_vip_load_plugin() function:

wpcom_vip_load_plugin( 'plugin-name' );
// Note this requires a specific naming structure: /plugin-name/plugin-name.php
// You can also specify a specific root file: wpcom_vip_load_plugin( 'plugin-name/plugin.php' );

On a multisite install, you can use get_current_blog_id() to load plugins on a per-site basis:

if ( get_current_site_id() === 2 ) {
    wpcom_vip_load_plugin( 'plugin-name' );

↑ Top ↑

Installing to the client-mu-plugins directory #

In addition to the directory of mu-plugins that loads by default into all VIP environments, there is a dedicated client-mu-plugins directory in the root of the site git repository; this directory works similarly to WP_CONTENT_DIR . '/mu-plugins/' in a self-hosted WordPress installation.

If you want your plugins to be installed as MU (“must use”) plugins then you can place them in the client-mu-plugins directory. We strongly recommend that only custom (and not third-party) plugins go in the client-mu-plugins directory, depending on the preferred loading behaviour. Specifically, client-mu-plugins should be for any code that should be auto-loaded or run earlier in the WordPress load process.

MU plugins behave differently than plugins installed in the plugins directory, so be sure to read up on the pros and cons and make a measured choice. If you have any questions, we’re happy to help.

Note that plugins contained within a directory in the client-mu-plugins directory will need a “loader” file in the root of this directory to require the main plugin file. The contents of the loader file can be as simple as:

require WPCOM_VIP_CLIENT_MU_PLUGIN_DIR . '/my-plugin/my-plugin.php';

↑ Top ↑

When do plugins run? #

Depending on how the plugin is loaded, it will hook into the WordPress load order at different points (from latest to earliest):

  • Manually activated from the wp-admin Plugins screen (supported, but code activation is preferred): before the plugins_loaded hook
  • wpcom_vip_load_plugin( 'plugin-name' ) in your theme functions.php (supported, but code activation from client-mu-plugins is preferred): before the after_setup_theme hook
  • wpcom_vip_load_plugin( 'plugin-name' ) from client-mu-plugins (recommended): on the muplugins_loaded hook

Sometimes plugins may have dependencies on running before specific hooks, in order to hook on very early actions or filters you will need to load from client-mu-plugins.

↑ Top ↑

Version updates and maintenance #

We recommend that you always run the latest version of each of the plugins on your site, however, this is not a requirement as we recognise that different development teams run different maintenance and patch cycles.

Automatically generated Pull Requests from our bot

The VIP team maintains a bot, wpcomvip-bot, to generate pull requests updating some plugins and themes. We do not currently have full coverage of all plugins used by all VIPs and the bot generated PRs are offered as a convenience; it remains the responsibility of individual VIP client developer teams to maintain the plugins used for their sites.

Remaining consistent with standard VIP practice, PRs will not be merged on your behalf unless they contain critical security fixes or resolve an existing or potential site outage. We recommend you merge the code into a development and/or non-production environments and test there before deploying to production.

Security fixes

Where the VIP team become aware of a security update, we will issue and merge PRs for affected production sites as soon as we can.

↑ Top ↑

On VIP Go, our Featured Partner plugins are installed and maintained the same as other plugins, read the documentation above and follow the directions. If you have any questions, please get in touch.

Ready to get started?

Drop us a note.

No matter where you are in the planning process, we’re happy to help, and we’re actual humans here on the other side of the form. 👋 We’re here to discuss your challenges and plans, evaluate your existing resources or a potential partner, or even make some initial recommendations. And, of course, we’re here to help any time you’re in the market for some robust WordPress awesomeness.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.