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 WordPress.com 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.
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.
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.
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' ); }
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:
<?php require WPCOM_VIP_CLIENT_MU_PLUGIN_DIR . '/my-plugin/my-plugin.php';
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 theplugins_loaded
hook wpcom_vip_load_plugin( 'plugin-name' )
in your themefunctions.php
(supported, but code activation fromclient-mu-plugins
is preferred): before theafter_setup_theme
hookwpcom_vip_load_plugin( 'plugin-name' )
fromclient-mu-plugins
(recommended): on themuplugins_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
.
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.
Featured partner plugins
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.