Managing Custom Code for WordPress with Plugins

Learn how to manage custom plugins or themes for WordPress sites using GitHub Updater or WP Pusher.

Contributors: Andy Fragen, Peter Suhm


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.

Instead, manage custom code separate from your projects within site-specific plugins. Then scope out an update strategy to easily distribute changes, such as GitHub Updater or WP Pusher.

Note

Pantheon does not support Git submodules (placing a Git repository within a subdirectory of your site’s repository).

Before You Begin

  1. Separate custom code into site-specific plugins or themes stored within individual repositories outside of your project.
  2. Host your custom extensions remotely on GitHub, Bitbucket, or GitLab.

For more details on separating custom code, see this related blog post.

GitHub Updater

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.

  1. 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
  GitHub Plugin URI: https://github.com/afragen/github-updater
  GitHub Branch:     master
  */

Theme declarations are made similarly within the styles.css file.

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.

  1. Set the Dev environment's connection mode to SFTP within the Pantheon Dashboard or via Terminus: terminus connection:set <site>.<env> sftp
  2. Download the latest release of the GitHub Updater plugin (select the zip option).
  3. Unzip the archive and rename the folder to github-updater, then re-zip the file.
  4. Install the plugin by uploading the renamed zip file within the WordPress Dashboard on the Dev environment (/wp-admin/plugin-install.php?tab=upload).
  5. Activate GitHub Updater from the Plugin page (/wp-admin/plugins.php).
  6. 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

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.

  1. Download WP Pusher. WP Pusher is free for open source code hosted in public repositories.
  2. Set the Dev environment's connection mode to SFTP within the Pantheon Dashboard or via Terminus: terminus connection:set <site>.<env> sftp
  3. Install the plugin by uploading the archive within the WordPress Dashboard on the Dev environment (/wp-admin/plugin-install.php?tab=upload).
  4. Activate WP Pusher from the Plugin page (/wp-admin/plugins.php).
  5. Navigate to WP Pusher > Install Plugin/Install Theme to install your custom extensions.
  6. 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.

Troubleshooting

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.