- What can I put in my VIP Go repository?
- How does the code get deployed?
- Plugins on VIP Go
- mu-plugins on VIP Go
- How do I access my code?
- How do I manage my plugins?
- About themes on VIP Go
- What versions of WordPress and Jetpack does VIP Go use?
- How do new versions of WordPress get released?
On the VIP Go platform, the codebase essentially consists of core WordPress. In fact, the only modifications made are via a handful of mu-plugins that are available via GitHub. All other custom code will be your own and committed to your Git repository. When developing your site, it is vital that you use the same mu-plugins in your test environment.
What can I put in my VIP Go repository? #
When we create you a new VIP Go site, we will provide a GitHub repository under the wpcomvip GitHub organization. The repository for each VIP Go site has the following directory structure:
- plugins — for your plugins
- themes — for your themes
- client-mu-plugins — for always active, global plugins (similar to mu-plugins)
- vip-config — for custom configuration changes, and additional
- languages – for your translations
- private – for any files which must not be web accessible
Note that all of these directories are required and should not be removed.
Any directories included in your client repository on GitHub which are not included in the above list will not be mounted into your site, and so will not be web accessible.
The plugins and themes directories are mapped to
wp-content/themes/ and should be treated like any other WordPress install.
vip-config directory contains a file named
vip-config.php. This is where you put things you’d usually find in
wp-config.php. Not all settings can be changed as we have optimized certain aspects of the WordPress install but it is handy if you need to define something like an API key or secret. Note that most of WordPress is not available when this file is loaded and code should be limited to pure PHP.
languages directory is mapped to
wp-content/languages, and should contain the
.mo files which specify the translated strings for your site.
private directory is mapped to
/private/, which is not web accessible; you might use this to store files you stream via PHP, e.g. a commercial plugin which you are charging for, and for which you need to check a purchase record before starting the download.
You can take a look at vip-skeleton to see an example of this structure.
You can read accessing your code to understand how to get access to your repository.
How does the code get deployed? #
Each VIP Go site or environment tracks a specific branch of your repository. For example, the production environment will track the
master branch; if you have requested other sites they will each have a specific branch they are tracking.
If you have a child environment, the branch will always auto-deploy. For the production environment, the
master branch will auto-deploy in the time leading up to and during the initial code review. Once the initial review has been completed, we will enable the GitHub Pull Request workflow, which is covered here.
Plugins on VIP Go #
Plugin locations #
On VIP Go, there is a dedicated plugin directory in the root of the theme’s Git repository. This directory works similarly to
WP_CONTENT_DIR . '/plugins/' in a WordPress.org installation.
Loading plugins #
The plugins in this directory can be activated and deactivated from the standard Plugins menu in
wp-admin, however we recommend loading your plugins from code. Loading plugins in code results in more control and a greater consistency across your production and non-production VIP Go environments, and your local development environments.
We recommend loading your plugins using a plugin loader file in
client-mu-plugins (example) using the
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' );
You can also call this from your theme in
When do these plugins run? #
Sometimes plugins may have dependencies on running before specific hooks. Depending on how the plugin is loaded, it can be run at three different times:
- From the
wp-adminPlugins screen – Before the
wpcom_vip_load_plugin( 'plugin-name' )– Depends on where the plugin is loaded. From `client-mu-plugins`, it will be loaded on or before the
muplugins_loadedhook. From the theme (`functions.php`), it will be loaded before the
Shared Plugins on VIP Go #
The Shared Plugins on WordPress.com VIP are not available to load the same way on VIP Go. Instead, these plugins should be added to the git repository as if it were a custom plugin. Public Git submodules are supported, so it’s possible to add these directly to your git repository (Example:
Presence of shared plugins in the VIP maintained
mu-plugins is a legacy feature which should not be relied upon for future development. Existing sites should take any opportunity to add plugins they are loading from the
shared-plugins directory to their
/plugins directory (we are happy to assist with this).
mu-plugins on VIP Go #
You can read more about mu-plugins (aka “Must Use plugins”), on the WordPress Codex.
All VIP Go sites run a set of mu-plugins which are maintained by VIP; these address integration with the VIP Go platform as well as providing access to various performance enhancements. A public repository of the current code is maintained at https://github.com/Automattic/vip-go-mu-plugins-built/. You do not need to commit this directory to your VIP Go repository, but you will need it in your local VIP Go development environment.
You can add your own mu-plugins in your
client-mu-plugins directory. For multisite installs, the plugins are loaded on all sites on the network, for a single site install they will be loaded automatically.
- loaded before the
- loaded in alphabetical order based on the filename.
- only top-level files are loaded (additional files inside folders can be
requiredby top-level files).
See the separate document
sunrise.php on VIP Go.
How do I access my code? #
See Accessing your code.
How do I manage my plugins? #
You no longer need to bundle your custom plugins with your theme and we would encourage keeping them separate as per the directory structure above. As the VIP Go workflow is Git based, you can also reference submodules in your repository which will make maintaining third party code easier. VIP Go currently only supports public submodules, e.g. you cannot submodule a private GitHub repository or a Git repository hosted elsewhere which requires authentication.
Each time we review a plugin (or a new version), we update this list of Reviewed Plugins. Choosing an already reviewed plugin will make it quicker for that plugin to be deployed and make it through our review queue. If you are wanting to add new functionality to a site, this list is a great place to start.
Plugins can either be activated via the WordPress admin interface or with code. It will be your responsibility to ensure plugins are up to date and compatible with your theme.
About themes on VIP Go #
Themes in the VIP Go environment live in
WP_CONTENT_DIR . '/themes/'. So if your organization is called Acme Kite Co., for example, your theme path might be
If you anticipate setting up multiple themes for your site or if you are a developer working on different themes for different sites, you might need a naming scheme that further distinguishes themes, e.g.
Child Themes #
Child theme-ing works the same in this case as child theming on self-hosted WordPress sites. Just add another theme to your Git repository at
/themes. Because the themes on WordPress.com aren’t available in the Git repository, they will need to be added before they can be used as parent themes.
No required code in functions.php and no vip-init.php #
Unlike WordPress.com VIP, there is no required code in the theme’s
functions.php file, nor do you need a
Use Underscores for a head start
The Underscores project will generate a starter theme that can be used to get a head start on your theme development. It includes lean, well-commented, modern, HTML5 templates, minimal CSS that’s ready for you to build on, and a variety of tools to help you work efficiently in customizing your theme
/private folder in your repo, if used, will provide access to files that are not web accessible, but can be accessed by your theme or plugins. For example, if you place a file at
/private/sites.json you can access that within your them with;
file_get_contents( '/private/sites.json' );
No visitor will be able to access that file at any URL, unless deliberately exposed via the theme or a plugin.
Like all code directories on VIP Go, the
/private directory is not writable by PHP so you cannot save uploaded files to it.
/private folder is mapped to
/private, in the root of the filesystem, on the VIP Go server.
What versions of WordPress and Jetpack does VIP Go use? #
Your website will be running the latest stable version of WordPress and Jetpack at all times.
In advance of a major version update for WordPress core or Jetpack (e.g. from 4.1 to 4.2) to VIP Go, as the beta testing period begins, WordPress.com VIP will post to the VIP Lobby. The deployment of minor versions will not receive a Lobby post. Security updates will be deployed as soon as practicable, and will not receive a Lobby post.
We provide the facility to test beta and release candidates of Jetpack of Jetpack on VIP Go.
During the run up to a new version of WordPress, we invite our clients to run their non-production sites against
trunk (here is the core WordPress project explanation of
trunk and other SVN terms. If you’d like one or all of your non-production sites to track
trunk, please get in touch. Sites tracking trunk will be updated to the latest
trunk revision at least once a day, but we cannot guarantee the timing of this update.
How do new versions of WordPress get released? #
As a new release is tagged on WordPress.org we will begin rolling it out to our customers. This is a rolling upgrade process and is normally completed within 48 hours of an official release. A small subset of sites are tested before the wider release to ensure stability. WordPress.com VIP continually monitors all VIP sites to ensure they are up and serving a reasonable response code, and this process continues as we roll out releases to our customers.
As a release approaches, you should test your site against WordPress core betas and release candidates as they are released, to ensure the upgrade process goes smoothly.