Manage Custom Code for WordPress with Plugins

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

Contributors: Andy Fragen, Peter Suhm.

Discuss in our Forum Discuss in Slack

This section provides information on how to manage custom plugins and themes on your WordPress Pantheon site.

Extending WordPress with custom code is a common part of the development lifecycle. It's essential that extensions are maintained independently from your sites and projects to optimize workflows and to allow custom code to be reused easily. You should also separate function from design to allow changes to persist when you swap themes. This method allows you to avoid dropping code into the current theme's functions.php file and pasting snippets when you want to reuse code in another project.

You can manage custom code separate from your projects within site-specific plugins. This allows you to scope out an update strategy to distribute changes easily. GitHub Updater or WP Pusher are good options for this workflow.

 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.

Refer this blog post for more information on separating custom code.

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. GitHub Updater displays 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.

  2. Set the Dev environment's connection mode to SFTP within the Pantheon Dashboard or via Terminus:

    terminus connection:set <site>.<env> sftp
  3. Download the latest release of the GitHub Updater plugin (select the zip option).

  4. Unzip the archive and rename the folder to github-updater, then re-zip the file.

  5. Install the plugin by uploading the renamed zip file within the WordPress Dashboard on the Dev environment (/wp-admin/plugin-install.php?tab=upload).

  6. Activate GitHub Updater from the Plugin page (/wp-admin/plugins.php).

  7. Navigate to Settings, select GitHub Updater, and then select 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 to GitHub Updater 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. This means that modifications to existing custom extensions are not required.

  1. Download WP Pusher.

  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 and select Install Plugin/Install Theme to install your custom extensions.

  6. Enable the Push-to-Deploy option if you want to automatically install updates on Pantheon's Dev environment when pushes are made to the remote repository hosting your custom code. You can also update custom plugins and themes installed via WP Pusher this way: Navigate to WP Pusher, select Plugins/Themes, and then select 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. Deactivate and the re-activate the plugin on Test and Live to resolve this error.

More Resources