Twelve-Factor WordPress App #12: Admin Processes

Factor #12: Admin processes

Run admin/management tasks as one-off processes

The process formation is the array of processes that are used to do the app’s regular business (such as handling web requests) as it runs. Separately, developers will often wish to do one-off administrative or maintenance tasks for the app, such as:

• Running database migrations (e.g. manage.py syncdb in Django, rake db:migrate in Rails).
• Running a console (also known as a REPL shell) to run arbitrary code or inspect the app’s models against the live database. Most languages provide a REPL by running the interpreter without any arguments (e.g. python or erl) or in some cases have a separate command (e.g. irb for Ruby, rails console for Rails).
• Running one-time scripts committed into the app’s repo (e.g. php scripts/fix_bad_records.php).

This should be fairly self-explanatory but the key point is to learn to separate out admin/management tasks as scripts instead of trying to incorporate into WordPress (like an admin page for example).

Example: you need to do a search and replace in all posts to update a URL.

Since this is a one-time process it might make sense just to do it directly through the console, or right in MySQL. But it’s often better to write a script that will be committed to your codebase. This gives you a history of them and it’s easy to copy it for a different task later on.

In Practice

One-off admin processes should be run in an identical environment as the regular long-running processes of the app. They run against a release, using the same code and config as any process run against that release. Admin code must ship with application code to avoid synchronization issues.

One-off processes, REPLs, or admin scripts are made much easier by one tool: WP-CLI.

wp shell provides you with an interactive PHP console:

allows you to evaluate PHP statements and expressions interactively, from within a WordPress environment. This means that you have access to all the functions, classes and globals that you would have access to from inside a WordPress plugin, for example.

The easiest way to write a script that guarantees you’ll have access to your WP environment is to write a custom WP-CLI command. This is the equivalent of a one-off script. Create a /scripts directory in your codebase and keep them all in the same place.

The WP-CLI Wiki offers the basic on creating a custom command. They go through the process for an example command. Running it looks like:

wp example hello --name=Joe foo --verbose bar

Using my above example of updating a URL in all posts, you could even make a generalized command that could be used like:

wp update-post-body --search=old.com --replace=new.com