Extending WordPress with custom code is a common part of the development lifecycle. In order to optimize workflows, it's essential that extensions are maintained independently from your sites and projects so that custom code is easily reused. You'll also want to separate function from design, so that changes persist when swapping themes. This means no more dropping code into the current theme's
functions.php file and no more pasting snippets when you want to reuse code in another project.
Pantheon does not support Git submodules (placing a Git repository within a subdirectory of your site’s repository).
Before You Begin
- Separate custom code into site-specific plugins or themes stored within individual repositories outside of your project.
- Host your custom extensions remotely on GitHub, Bitbucket, or GitLab.
For more details on separating custom code, see this related blog post.
GitHub Updater is an open-source plugin developed by Andy Fragen that extends the existing notification and update mechanisms within WordPress to plugins and themes hosted outside of the official WordPress repository on GitHub, Bitbucket, or GitLab. This will display update notifications within the WordPress dashboard for public and private repositories.
Modify your plugin and/or theme to add support for the GitHub Updater by providing the required declarations. The following plugin example should be placed within the plugin's header:
/* Plugin Name: GitHub Updater Plugin URI: https://github.com/afragen/github-updater Description: A plugin to automatically update GitHub, Bitbucket or GitLab hosted plugins and themes. It also allows for remote installation of plugins or themes into WordPress. Version: 1.0.0 Author: Andy Fragen License: GNU General Public License v2 License URI: https://www.gnu.org/licenses/gpl-2.0.html Domain Path: /languages Text Domain: github-updater <b>GitHub Plugin URI: https://github.com/afragen/github-updater GitHub Branch: master</b> */
Theme declarations are made similarly within the
As an alternative to adding declarations within the headers of plugins and themes, you can use the GitHub Updater Additions plugin, which will add the appropriate data via hooks in GitHub Updater.
Set the Dev environment's connection mode to SFTP within the Pantheon Dashboard or via Terminus:
terminus connection:set <site>.<env> sftp
Download the latest release of the GitHub Updater plugin (select the zip option).
Unzip the archive and rename the folder to
github-updater, then re-zip the file.
Install the plugin by uploading the renamed zip file within the WordPress Dashboard on the Dev environment (
Activate GitHub Updater from the Plugin page (
Navigate to Settings > GitHub Updater > Install Plugin/Install Theme to install your custom extensions.
Alternatively, you can upload your plugin/theme using the same method described above for installing the GitHub Updater plugin.
Notifications within the WordPress dashboard will now include updates to your custom code. If expected updates are not found within
/wp-admin/update-core.php, click Check Again to clear transients, or wait for them to reset automatically.
WP Pusher provides a similar method for managing your custom code, but with some key differences. WP Pusher is free for open source code hosted in public repositories. Supporting private repositories requires you to purchase a license. Currently, update notifications are not displayed within the WordPress dashboard, but you can configure the plugin to automatically install updates on Pantheon following a push to the remote repository (e.g. GitHub, Bitbucket, or GitLab). There are no declarations required within your plugin or theme, so modifications to existing custom extensions are not required.
- Download WP Pusher. WP Pusher is free for open source code hosted in public repositories.
- Set the Dev environment's connection mode to SFTP within the Pantheon Dashboard or via Terminus:
terminus connection:set <site>.<env> sftp
- Install the plugin by uploading the archive within the WordPress Dashboard on the Dev environment (
- Activate WP Pusher from the Plugin page (
- Navigate to WP Pusher > Install Plugin/Install Theme to install your custom extensions.
- Enable the Push-to-Deploy option if you would like to automatically install updates on Pantheon's Dev environment upon push to the remote repository hosting your custom code. Otherwise, you can update custom plugins and themes installed via WP Pusher from WP Pusher > Plugins/Themes > Update Plugin/Update Theme.
You may encounter WordPress database errors referencing the
wp_wppusher_packages table within the
php-error.log on the Test and Live environments, similar to the following:
[28-Mar-2016 17:57:58 UTC] WordPress database error Table 'pantheon.wp_wppusher_packages' doesn't exist for query SELECT * FROM wp_wppusher_packages WHERE type = 1 made by require_once('wp-admin/admin.php'), do_action('admin_init'), call_user_func_array, Pusher\Pusher->registerPluginActionLinks, Pusher\Storage\PluginRepository->allPusherPlugins
These errors occur when the expected WP Pusher database table does not exist on the environment. Deactivating and re-activating the plugin on Test and Live should resolve this error.