No longer worry about keeping configuration correct on different environments. WebOps teams can automate configuration management with the WP-CFM Pantheon integration.
What is WP-CFM?
WP-CFM is a WordPress configuration management plugin that provides the ability to copy configuration settings stored in the database across different site environments.
When you complete plugin configuration changes on a non-production dev environment, you need to recreate those changes on the staging and production environments, too. The WP-CFM plugin does just that by reading the `wp_options` table and exporting the selected configuration, from a plugin or WordPress core, as files in the WordPress project filesystem.
Now you can apply version control to track your site configuration, along with the rest of the code, and quickly re-apply these settings once the configuration files are deployed to a new environment by importing their values.
Read more details about WP-CFM and Pantheon in the platform docs.
What's New in WP-CFM 1.6
Forum One, the creators of WP-CFM, and Pantheon are excited to add integration for the Pantheon workflow to WP-CFM. We have come out with v1.6, which includes some new cool features for the plugin that expand its capabilities and use cases, including multiple environment support. We hope they will be as useful to other WP-CFM users as they are for us!
Multiple Environment Support
The WP-CFM plugin now includes two new filters, meant to be used in conjunction, that enable multi-environment mode. The new filters, `wpcfm_multi_env` and `wpcfm_current_env`, allow exporting WordPress configuration to different variations—one for each environment of your WordPress website.
This is useful when you develop your WordPress site in multiple places (e.g. development, testing, production) and you need to maintain different configurations between them. For example, you might need to have certain plugins only active on “dev” and “test;” or, you might need a specific and different configuration for a plugin just in “prod.”
Enabling Multiple Environment Support
Note: If you are using WP-CFM on Pantheon, manually configuring multiple environments is not necessary. Feel free to skip down to the next section, Pantheon integration.
First, the filters `wpcfm_multi_env` and `wpcfm_current_env` must be set in a mu-plugin. Since they alter the default configuration of WP-CFM when it is initialized, they must be defined in a mu-plugin and registered before the plugin is loaded.
We recommend adding a file called “wp-cfm-multi-env.php” inside “wp-content/mu-plugins/” just for this purpose.
Once the mu-plugin file is ready, add the `wpcfm_multi_env` filter to register all the environments the WordPress website will be using. Check with your specific hosting provider about what their environments' names are. For example, on Pantheon those are “dev,” “test,” and “live.” The environments indicator names that output the PANTHEON_ENVIRONMENT server variable.
For each environment name specified here, WP-CFM will create a subfolder inside the config directory located at "wp-content/config/" where it will export the configuration file bundles created from the plugin admin interface.
There will also be a dropdown in the plugin admin page allowing you to switch between the different registered instances and to push and pull configuration accordingly.
Lastly, add the filter `wpcfm_current_env,` which will contain the logic to detect and tell WP-CFM the server environment the WordPress site is currently running on in order to pull the correct configuration bundles files from the config directory. For example, “wp-content/config/dev/*.json” if we are in the development environment.
See the following Gist for a full example “wp-cfm-multi-env.php” file with all of this together:
Pantheon Integration Out of the Box
WP-CFM has great multi-environment features, allowing you to create per-environment configurations. The good news is that if you are running your WordPress project on Pantheon, the dev, test and live environments are configured out of the box - no additional coding necessary!
WP-CFM will detect you Pantheon site and register matching “dev,” “test,” and “live” environments out of the box. If your WordPress project uses Pantheon Multidev environments, they will be treated as “dev” (the default case).
When on Pantheon, WP-CFM will also change the default directory where bundle export files are stored from "wp-content/config/" to “private/config/” in order to make the configuration files non-web accessible. The plugin determines the currently running environment from the value returned by PANTHEON_ENVIRONMENT.
Read more about Private Paths for Files and Code on Pantheon.
You won’t need to create a “wp-cfm-multi-env.php” mu-plugin file with `wpcfm_multi_env` and `wpcfm_current_env` filters in it. This is already included in the plugin’s code since v1.6 is ready to go.
If you wish to disable the WP-CFM multi-environment feature while running on Pantheon, however, you can use the same mu-plugin file. This time, only include the filter `wpcfm_multi_env` and return an empty array to override the assumption that we are on Pantheon hosting. Doing so will disable this feature and it will export and read all bundled files defined in “wp-content/config/” across all Pantheon environments.
Use your wise dev judgment to determine when you need to use it or not!
Override Database Values With Configuration in Code
The filter accepts only one boolean parameter. The default value is `false,` but filtering it to `true` will tell WordPress to load the options tracked by WP-CFM directly, reading them from the bundle's config files at “wp-content/config/*” instead of from the database.
This filter must also be added via a mu-plugin.
Enabling `wpcfm_is_ssot` gives many new possibilities for developers who use WordPress in a more advanced or custom-crafted way. Using the multi-environment filters, if you add some code logic to detect which environment WordPress is running in, you can force transactional test mode in non-production or ensure that development plugins are disabled in production.
It will also make your WordPress site configuration more reliable and stable because it will be fully defined and read directly from the source code, rather than the database. This helps mitigate against human errors, database errors, and even hacks that purposely look into changing your plugins or WordPress core configurations to make the site more vulnerable.
Pro Tip: Your WordPress site will be doing less get_option() calls. Reading the small bits of code from WP-CFM bundle files will always be faster than doing a MySQL database connection and query ;)
Expanded Documentation On The WP-CFM Wiki
To read more about these new additions and all you can do with other available filters, consult the WP-CFM Filters Reference page in the GitHub wiki.
A Practical Example: Enabling Different Plugins On Different Environments
Let’s see a practical example of using these features in a WordPress site hosted on Pantheon. Query Monitor is a plugin that watches database transactions to help debug slow queries during development. However, it should not be activated on production as the additional overhead will negatively impact performance. We will use WP-CFM's new features and Pantheon integration to ensure the plugin is only active in dev and multidev environments.
Install and Activate Query Monitor Plugin
Create a WP-CFM Bundle to track which plugins are active in the WordPress site environment.
Working directly from a WordPress site hosted in Pantheon, we don't need to add the `wpcfm_multi_env` and `wpcfm_current_env` filters. WP-CFM already detects we are on Pantheon, displays the current environment name (Dev), and provides a dropdown to switch to the others environment bundles configurations (Test, Live).
To create a bundle that keeps track of the active plugins in your WordPress site, click “Add Bundle,” give it a descriptive name, and select the `active_plugins` option key. This is the WordPress core option that dictates which plugins are active. Don’t forget to click “Save Changes” to save your bundle configuration in WP-CFM.
Pro Tip: Create many smaller bundles, rather than a few large, monolithic bundles, to track configuration.
Export The Active Plugins Bundle
Now we will want to export the selected configuration options to the filesystem. Make sure your dev environment is in SFTP mode and click the “Push” button for this new created bundle. It will drop a JSON file called `active_plugins.json` inside the “private/config/dev/” directory for the dev environment. Congratulations, you just created your first WP-CFM bundle!
From your Pantheon Dashboard, go to the Dev tab and select “Code.” The bundle file is ready to be committed into Pantheon—even when in SFTP mode—making a commit tracks everything in version control.
If you are curious, you can also view the differences between `active_plugins` in the database and the configuration file saved to the filesystem by clicking the “Diff” button in WP-CFM. This will help you understand what these options looks like, and what will be exported into your filesystem to commit along in version control with the rest of your WordPress project code.
Security Pro Tip: Do not track with WP-CFM secrets stored by plugins in `wp_options`, for instance, things like license keys and security tokens.
Disable Query Monitor plugin in the Active Plugins Bundle on Test and Live
At this point, you have the proper config exported for the Pantheon “dev” environment, where you want to have the Query Monitor plugin always active.
In the “test” and “live” environments, however, you don’t need this plugin. Since it is only intended for development purposes, we want it to only be active in the “dev” environment.
Go back to the plugins management page and deactivate the Query Monitor plugin. Then return to WP-CFM page. Select “Test” from the Switch Config dropdown and click the “Push” button again. This time, WP-CFM will export the current active plugins configuration (with Query Monitor deactivated) to the “private/config/test/” directory. Repeat the same process for the “Live” environment configuration, saving the configuration to “private/config/live/.”
Now you should have three versions of the `active_plugins.json` file, one for each Pantheon environment, where the Query Monitor plugin is activated on “dev” but deactivated on “test” and “live”.
Voilà! You have a full independency across each environment configuration. Isn’t that neat?
To deploy the configuration to the Test and Live environments, return to the Dev tab of the Pantheon site Dashboard and select “Code.” Commit the configuration for Test and Live. Then, deploy to Test and Live tab following the Pantheon WebOps workflow as usual.
After each environment deployment is completed, go to the WP-CFM page in the WordPress backend and click “Pull” in the Active Plugins bundle to import the new configuration. The pull action will read the `active_plugins.json` file exported for the current environment and update the values in the database.
Override DB Value For Active Plugins on Live With a Filter
How do we ensure Query Monitor is always disabled on the live environment? Tracking our configuration is great, but the plugin can always be reactivated.
The other new WP-CFM feature, allows you to override the database configuration values with those tracked by WP-CFM. Follow this sample to lock-in the tracked configuration in this case, the active plugins, on Live.
You can either drop this file gist inside the mu-plugins directory (wp-content/mu-plugins/), or add the filter code to your existing mu-plugin file.
Get Started Today
Stop worrying about keeping configurations correct across different environments. Get started with a free Pantheon account and WP-CFM to automate configuration management and increase the efficiency of your WebOps team.