How To Manage WordPress Site Configuration in Code

We’ve all had that moment where we have content in our live environment and want to add a new plugin or feature to our site. However, we need to test this new feature in a development environment first before deploying it to our live site. You do all the work to configure the plugin and then realize all of this configuration is saved in the database and you are in no position to override the live database. What do you do?!

WP-CFM is a plugin that allows you to move site settings around to different environments without having to replace your database every time. The plugin is able to track data that is stored in the wp_options table based on your specifications by creating json files with the data. You can then commit the json files to your version control system and deploy them to a new environment. This allows you to  duplicate the configuration in the new environment without having to update settings manually.

What is Site Configuration?

Your site’s configuration includes any items configurable in the CMS dashboard not related to content. Some examples are theme settings, plugin settings and widget locations.

What is Configuration Management?

Configuration management is the act of managing your site configuration in code. Treating your configuration as code allows you to use the same version control and deployment method you use for standard code changes.

Perks of WP-CFM

• Less need to copy the database.

• No need to overwrite your database for a simple setting.

• Track and deploy configuration files using version control

Terminology

Bundle: A group of settings to track. This could be a single setting, or all the site's available settings. It's best to create bundles of related options, such as site name and description, rather than one large, monolithic bundle.

Push: Export configuration from your database to the file system.

Pull: Import configuration from the filesystem into your database.

What can WP-CFM Track?

wp_options is the only table that is automatically tracked by the plugin. This table is populated by the following sources:

• Default settings (/wp-admin/options-general.php)

• Theme option pages - includes customizer options stored in the row theme_mods_yourthemename

• Settings and option pages for plugins

How to install WP-CFM

1. Navigate to Plugins > Add New

2. Search for WP-CFM

3. Click Install

4. Click Activate

How to set up WP-CFM bundles

1. Navigate to Settings > WP-CFM

2. Click Add Bundle

3. Enter the name for your bundle

4. Check off the values from the wp_options table that you want included in that bundle.

5. Click Save Changes

6. Push your bundle

7. Push your code changes to your version control

How to make these changes in your other environments

1. Navigate to Settings > WP-CFM in your other WordPress instances

2. Click Pull on any of the bundles you want to pull changes in for

3. You will see a prompt to confirm you want to make these changes

4. Click Ok

You will notice the database changes have now been made!

Utilizing WP-CLI + Terminus on Pantheon

You can make most of these changes (except creating bundles) with WP-CLI. Below are examples of how you could utilize WP-CLI and Terminus with WP-CFM. 

Install and Activate Plugin

terminus wp sitename.env -- plugin install wp-cfm --activate

Activate Plugin (in other environments)

terminus wp sitename.env -- plugin activate wp-cfm

Push Bundle

terminus wp sitename.env -- config push [bundle_name]

Pull Bundle

terminus wp sitename.env -- config pull [bundle_name]

View the Difference

terminus wp sitename.env -- config diff [bundle_name]

View All Bundles

terminus wp sitename.env -- config bundles

View File Value vs Database Value

terminus wp sitename.env -- config show_bundle [bundle_name]

Tips & Tricks

The config names can be really hard to decipher. The Options Reference on the WordPress Codex explains it fairly well. 

You can view the present options in your website by navigating to your website url + /options.php. For example: http://yourdomainname.com/wp-admin/options.php.

I would recommend creating separate bundles for each area of your site. In my example, I created a bundle for each settings page that is a part of the WordPress core as well as one for my Widgets, Theme & Menu. I also created a plugin bundle that only contained one checkbox for the “active_plugins.” Most plugins will include their own settings and I normally create a separate bundle for each third-party plugin I install.

Suggested Bundle Cheat Sheet

Settings > General

• Site Title: blogname
• Tagline: blogdescription
• Email Address: admin_email
• Membership: users_can_register
• New User Default Role: default_role
• Timezone: timezone_string
• Date Format: date_format
• Time Format: timezone_string
• Week Starts On: start_of_week

Settings > Writing

• Default Post Category: default_category
• Default Post Format: default_post_format
• Mail Server: mailserver_url
• Port: mailserver_port
• Login Name: mailserver_login
• Password: mailserver_pass
• Default Mail Category: default_email_category
• Update Services: ping_sites

Settings > Reading

• Front page displays: show_on_front
  •     Front page: page_on_front
  •     Posts page: page_for_posts
• Blog pages show at most: posts_per_page
• Syndication feeds show the most recent: posts_per_rss
• For each article in a feed, show: rss_use_excerpt
• Search Engine Visibility: blog_public

Settings > Media

• Thumbnail Width: thumbnail_size_w
• Thumbnail Height: thumbnail_size_h
• Crop thumbnails to exact dimensions: thumbnail_crop
• Medium Width: medium_size_w
• Medium Height: medium_size_h
• Large Width: large_size_w
• Large Height: large_size_h
• Organize my uploads into month and year based folders: uploads_use_yearmonth_folders

Settings > Permalinks

• Permalink Common Settings: permalink_structure
• Category Base: category_base
• Tag Base: tag_base

Themes, Widgets & Plugins

• Theme Settings (Customizer settings): theme_mods_themename
• Widgets: widget_nameofwidget
• Plugins (Activated): active_plugins

3rd party plugins may include their own set of settings. Check WP-CFM after installing a plugin to see if there are any new/applicable name options. For example: Yoast SEO has its own settings that can be included in a bundle.