Understanding your VIP Go codebase

Overview #

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.

↑ Top ↑

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 sunrise.php code
  • 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/plugins/ and wp-content/themes/ and should be treated like any other WordPress install.

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

The languages directory is mapped to wp-content/languages, and should contain the .po and .mo files which specify the translated strings for your site.

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

↑ Top ↑

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.

↑ Top ↑

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.

↑ Top ↑

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() 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' );

You can also call this from your theme in functions.php.

↑ Top ↑

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-admin Plugins screen – Before the plugins_loaded hook
  • 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_loaded hook. From the theme (`functions.php`), it will be loaded before the after_setup_theme hook.

↑ Top ↑

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: Automattic/Co-Authors-Plus).

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

↑ Top ↑

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.

On VIP Go, your client-mu-plugins are loaded immediately after the platform-level vip-go-mu-plugins and follow similar behaviours to mu-plugins:

  • loaded before the muplugins_loaded hook.
  • loaded in alphabetical order based on the filename.
  • only top-level files are loaded (additional files inside folders can be required by top-level files).

↑ Top ↑

sunrise.php #

See the separate document sunrise.php on VIP Go.

↑ Top ↑

How do I access my code? #

See Accessing your code.

↑ Top ↑

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.

↑ Top ↑

About themes on VIP Go #

Theme Naming

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 /themes/acmekites/.

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. /themes/acmekites-main/ and /themes/acmekites-seasonal/.

↑ Top ↑

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.

↑ Top ↑

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 vip-init.php file.

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

↑ Top ↑

Using /private #

The /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.

The /private folder is mapped to /private, in the root of the filesystem, on the VIP Go server.

↑ Top ↑

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.

↑ Top ↑

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.

Ready to get started?

Tell us about your needs

Let us lead the way. We’ll help you select a top tier development partner. We’ll train your developers, operations, infrastructure, and editorial teams. We’ll coarchitect your deployment processes. We will provide live support for peak events. We’ll help your people avoid dark alleys and blind corners, and reduce wasted cycles.