This is the third post in a series on managing site configuration in code. You can find part one here, which introduces the idea of managing site configuration in code, and part two here, discussing implementation with Drupal 8.
The WP-CFM plugin is designed to standardize the process of moving configuration between different environments of the same site—e.g. development, staging and production. It can also be used to migrate configuration from one site to another. We'll be covering the former in this article.
Configuration Deployment Workflow
Assuming you have three environments—development, test, and live—the live database is treated as the canonical source for data—both content and configuration. The development environment will have a mix of code changes, e.g. PHP files, and configuration changes, pushed to code with the WP-CFM plugin.
To export configuration to code with WP-CFM you must choose which items from the wp_options table to export by creating a bundle. You can then "push" the bundle, copying the options from the database to JSON files, which can then be committed to version control.
Both the code and configuration changes, which have been exported code, are deployed to the test environment. The database from the live environment is also copied to the test environment to ensure the latest content exists in the test environment. At this point the configuration changes are pulled from code into the database. You may also want to copy the latest media uploads (wp-content/uploads) from live to the test environment as well.
The test environment now has the latest code and configuration from the development environment, and the latest content and media from the live environment. It is a mirror of what the live environment would look like if you were to deploy the latest code and configuration changes.
After performing quality assurance, running tests on the test environment and receiving stakeholder approval, you can deploy the code and configuration files to live with confidence. After deploying to live, simply "pull" the configuration changes—in your bundle—from JSON to the live database with the WP-CFM plugin.
A Practical Example: Add a Sidebar
You have been tasked with adding a new sidebar to a WordPress site. This consists of registering a sidebar area, creating a custom widget to use in the sidebar, and add the widget to the new sidebar in the WordPress dashboard. The widgets you add to the sidebar likely have options associated with them as well. Registering the sidebar area and custom widget are standard code changes in PHP but deploying the sidebar without any configuration would leave the sidebar empty.
After adding the code for the sidebar and the custom widget to the development environment, use the WordPress administrative interface to add the custom widget, and any other desired widget, in the new sidebar. Once the widgets are configured in the sidebar, create a new bundle in WP-CFM. The options you want to look for are "sidebars_widgets", which tracks which widgets are in the sidebar, and "widget_*" options, which are configuration changes for the widgets themselves. Now you can export the configuration to code with the WP-CFM plugin by "pushing" the bundle from the database to JSON.
Now you have the code and configuration, exported as code, together. These can both be committed to version control and deployed together. Once deployed, the configuration can be "pulled" into the database of the new environment.
The pull can be done with WP-CLI using the "wp config pull [bundle_name]" command. Since WP-CLI is a command line tool, this can be scripted and automated with each deployment. If you would like to do this on Pantheon, check out our Quicksilver example for WP-CFM import.
As you can see, deploying your configuration with your code saves time as you no longer have to repeat the configuration in the WordPress dashboard on each environment. It can also be automated—removing room for error—and tracked in version control. I encourage you to start using the WP-CFM plugin when working with any WordPress project.