ConfMaps configuration management for WordPress WP-CLI - Tame your wp_options using WP-CLI and git

This is a CLI-based tool for managing WordPress settings defined in the wp_options database table.

TL;DR:

• This is a WP-CLI package
• It manages options in your wp_options table
• Source of truth are PHP files (called "conf maps")
• Multiple conf maps can be merged into the final desired configuration (think per-environment overrides)
• You can dump database values back into the conf maps

In short, if your answer to the question "Do I want to track my WordPress configuration that is stored in the wp_options table by storing it in a git repository?" is "Yes, definitely!", then this tool is what you're looking for.

Installation

Prerequisites:

• WordPress
• WP-CLI
• Shell access to your WP instance(s)

Install the wp-cli-confmaps package:

wp package install wp-cli-confmaps/wp-cli-confmaps

Initial (basic) configuration

To start using this tool, at least one conf map needs to be created. The simplest way to get started is to generate a conf map from your current wp_options content:

wp confmaps generate --from-db

This will dump out your first conf map, in a form of PHP code. It should look something like this:

<?php

// Generated by `wp confmaps generate --from-db --values-from-db` on 2022-01-15T19:41:07+00:00.

return [
  'metadata' => [
    'version' => 1,
  ],
  'data' => [
    'WPLANG' => 'sl_SI',
    'active_plugins' => [
      'encoding' => 'serialize',
      'type' => 'array',
      'undef-key-action-apply' => 'delete',
      'value' => [
        0 => 'parent-category-toggler/parent-category-toggler.php',
        1 => 'post-expirator/post-expirator.php',
        2 => 'posts-in-sidebar/posts-in-sidebar.php',
        3 => 'restrict-categories/restrict-categories.php',
      ],
    ],
    'admin_email' => 'YOUR-ADMIN-EMAIL-HERE@SOME-DOMAIN.COM',
    'admin_email_lifespan' => '2000000000',
    // ...

You can see that a "conf map" is actually structured dump of your wp_options content.

Store this generated conf map in some file (i.e. ../conf/maps/common.php). The generate command we used above can help you with that:

wp confmaps generate --from-db --output=../conf/maps/common.php

Now define your conf map set:

define('WP_CLI_CONFMAPS', [
    'common' => ABSPATH . '../conf/maps/common.php',
//  WP_ENV   => ABSPATH . '../conf/maps/'. WP_ENV .'.php',   // This one is for later, when you'll have a per-environment value overrides
]);

You can add this^ to any suitable WordPress source file, however there is a dilemma:

• wp-config.php file, as intended by WordPress, should not be replicated between environments, but
• Changes to other WP source files will be overwritten by WordPress updates.

To help you with the decision where to put this code, see a saner WordPress directory structure for a better how to structure your WordPress directory hierarchy.

Usage

To verify if wp_options content still matches what your conf map(s) definitions say, use the, well, verify command:

wp confmaps verify

To apply all options defined in your conf map(s) to the database:

wp confmaps apply --commit

This command transfers all defined option values (defined in one or multiple conf map files) into the wp_options table. The transfer is performed according to the individual value specification (literal copy, merged, etc.).

Alternatively, if you've been tweaking your WordPress configuration in the admin section of a particular instance (i.e. your local development instance), and now you want to transfer the new configuration to your other environments (i.e. staging and later production), you can update your conf maps with your current database values:

wp confmaps update

This will update all defined conf maps in-place. Now git commit -av, git push, git pull and wp confmaps apply are all that you need to reliably transfer this new configuration to all the other environments.

Advanced configuration - environment-specific value overrides

You've probably noticed the WP_ENV above. This is one way how you can define per-environment overrides:

• Make sure each environment defines a correct WP_ENV constant (i.e. with dev, stg or prod values)
• Besides common.php, create conf maps called dev.php, stg.php and prod.php

Here is the directory structure you should end up with:

./
./.git
./public                     # Here is the original WordPress code, and vhost root actually points to this location
./public/index.php
./public/wp-config.php       # This file is actually committed to the git repository, see it's content below

./conf
./conf/wp-config-local.php   # The actual local configuration (containing instance URLs, DB access credentials and salts, and WP_ENV definition)

./conf/maps                  # Location of our conf maps
./conf/maps/common.php
./conf/maps/dev.php
./conf/maps/stg.php
./conf/maps/prod.php
./conf/maps/local.php        # For fun, let's make this one optional

Now, in your conf map set definition, include a second conf map. But make the choice dynamic, based on your WordPress instance's configured environment. Additionally, let's include a local.php conf map too, if it's found:

$confMaps = [
    'common' => ABSPATH . '../conf/maps/common.php',
    WP_ENV   => ABSPATH . '../conf/maps/' . WP_ENV . '.php',
];

$localConfMapPath = ABSPATH . '../conf/maps/local.php';
if (file_exists($localConfMapPath)) {
    $confMaps['local'] = $localConfMapPath;
}

define('WP_CLI_CONFMAPS', $confMaps);
unset($confMaps);

Now, in a dev environment, when running wp confmaps verify or wp confmaps apply:

• All the option values specified in the dev.php file will override matching definitions from the common.php file
• All the option values specified in the local.php file will override matching definitions from both common.php and dev.php file

But in a stg environment:

• All the option values specified in the stg.php file will override matching definitions from the common.php file
• All the option values specified in the local.php file will override matching definitions from both common.php and stg.php file

And in a prod environment:

• All the option values specified in the prod.php file will override matching definitions from the common.php file
• All the option values specified in the local.php file will override matching definitions from both common.php and prod.php file

Expert configuration

For more information, review the document that describes all details of the structure of a conf map.

License

/*
 * ConfMaps configuration management for WordPress WP-CLI - Tame your wp_options using WP-CLI and git
 *
 * Copyright (C) 2022 Bostjan Skufca Jese
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * version 2 as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, see <https://www.gnu.org/licenses/gpl-2.0.html>.
 */

Author

Created by Bostjan Skufca Jese.