Dictator is a proper provisioning tool for WordPress, allowing you to document the current state of your WordPress configuration in a flat YAML file.

What’s It Do?

Dictator is a package built on top of wp-cli that allows you to export configuration files straight from the command line. The exported file is in YAML format and contains information in three categories. The first is general settings of WordPress, including title, description, date format and active themes and plugins. The second is user information, email, description, display_name, etc. The last is term meta, including categories, custom post types, and tags. All of this information is stored in one config file, which can be compared to your current WordPress install and can be applied to any WordPress install to automatically update its configuration.

What this really allows you to do is keep the non-post data information from your site portable enough that it can be applied to any WordPress install, and passed around by team members in order to keep development and local environments in sync. For a full description of what dictator can do, you can check out my post on Torque Mag.

How’s It Work?

In order to install Dictator, you need to make sure to install WP-CLI and Composer first. Personally, I think having a development environment like Varying Vagrant Vagrants, which includes both tools pre-installed, is extremely helpful.

Once you have that installed, the next step is to set-up the WP-CLI package index. If you are using VVV, simply navigate to the wp-cli folder in the “www” directory and open up the composer.json file. just below the “require-dev” section, add in:

    	"repositories": {
	    "wp-cli": {
	        "type": "composer",
	        "url": "http://wp-cli.org/package-index/"
	    }
	},

If you are not using VVV, then from your terminal create a new folder in order to install your WP-CLI packages into, let’s call it “.wp-cli”, and then cd into it.

mkdir -p ~/.wp-cli 
cd ~/.wp-cli

Next up, create a composer.json file and add the WP-CLI package index.

php composer.phar init --stability dev --no-interaction 
php composer.phar config bin-dir bin 
php composer.phar config vendor-dir vendor 
php composer.phar config repositories.wp-cli composer 'http://wp-cli.org/package-index/'

Finally, create a config.yml file in this directory and add the proper autoload settings. If you are using something like Vagrant, you can create this file using vim (“vim config.yaml”).

require: 
- vendor/autoload.php

If this is confusing to you, there is a shell script which will perform all of these actions for you automatically.

To actually install Dictator simply use:

composer require danielbachhuber/dictator=dev-master

And the Dictator plugin for WP-CLI will be installed. To see if it works, type in “wp dictator –info” and make sure that the command is recognized. Dictator comes with a few commands out of the box. The first is “dictator export” which is used to actually create the config YAML file. Make sure you cd into the directory of your WordPress install and then type:

wp dictator export site site-state.yml

Note that “wp” is the alias I have set up for WP-CLI. Yours may be different. This command will export a file into the directory called “site-state.yml.” That file will contain basic information about your WordPress configuration, including basic info like title, description, and posts per page, but also which theme is active and which plugins are activated.

A chunk of your YAML config file

If you are using a multisite or network set-up the command is a bit different. You want to make sure to specify “network” instead of “site” as the state type, like so:

wp dictator export network network-state.yml

You can also use “dictator compare” to check the config file against the settings of your WordPress install. These changes will be output right in the terminal in a colorized (highlighted) format. You will easily be able to see the differences between your config file and the current settings. This is useful if you have pulled down the config file and need to see how your settings compare to the master version quickly.

wp dictator compare site-state.yml

Compare the config file to your current WordPress install

Another command is “dictator impose” which will actually apply the configuration from the file to the current WordPress install. Keep in mind, this will not install plugins or themes for you, but it will switch on or off plugins based on the config settings in the state YAML file. It will also change the title, description, and any other configuration options based on the file. This is useful if you need to keep your configuration up to date with its current state, or if you want to quickly revert your site to a testing or previous environment.

wp dictator impose site-state.yml

The last command is “dictator validate,” which will validate your file to make sure it checks against the schema of your regions. I haven’t found a great use case for this command yet, but I’m sure it’s out there.

wp dictator validate site-state.yml

Those are the commands for dictator you can start using. You can also use the Dictator::add_state(); method in order to create your own state (apart from “state” and “network”) and include configuration options that already exist, and new ones. This, for example, can be used to save all of the specific options for a plugin if you want to include this in your config file. I haven’t dived into the details of this just yet, but I’d be interested to hear if anyone has any examples of this.

Costs, Caveats, Etc.

Dictator is very much in its early stages, and it is being developed on GitHub if you would like to contribute to the project. It is meant for developers only, so make sure you have a good sense of the command line and WordPress development before you dive in. If you are searching for some help, you can post an issue to GitHub or check out the post by the developer introducing the new tool.