WordPress Multi-Environment Config: Work Seamlessly Between Development, Staging, and Production Sites

photo credit: Matteo Bagnoli - cc
photo credit: Matteo Bagnolicc

WordPress doesn’t have built-in support for developers working in multiple environments, i.e. local, staging, and production. It’s no surprise, given that this workflow isn’t part of the vast majority of users’ lives when publishing with WordPress.

Nevertheless, running a separate development site can be a complex and tedious endeavor and WordPress doesn’t make it very easy. The process usually involves updating the database settings in wp-config.php and running a SQL change on the database to update the ‘wp_siteurl’ and ‘wp_home’ settings. Developers have different tools to help streamline the task of moving between different environments, but it’s still a pain.

WordPress Multi-Environment Config

Simon Jones is the founder and technical director of Studio 24, a web development agency that works extensively with WordPress. He believes that the platform should have better support for those working in multiple environments and has created an extension to the WP config system to elegantly support this.

“In order to efficiently work on a project I prefer to have all the setup for different environments in the website code,” Jones said. “So when we push changes to staging things just work.” To that end, he created the WordPress Multi-Environment Config project. It supports using WordPress in local development, staging, and production environments without having to edit your config files or update the site URLS in your database.

Jones used an approach based on FocusLab’s work on the ExpressionEngine master config. It splits the config files out into:

  • wp-config.default.php – any shared settings used across all environments
  • wp-config.{environment}.php – the settings for a specific environment
  • wp-config.env.php – sets up which URLs work for which environments
  • wp-config.php – the original WP config file which now contains loading code

The way it works is that you copy any shared settings, i.e. auth keys and salts, into wp-config.default.php. You then copy your unique settings for each environment, i.e. database access details, to the wp-config{environment}.php file. In the wp-config.env.php file you then specify which URLs are defined for which environment. You can also set the environment via a webserver environment variable if you like.

Once all of this is in place, WordPress will load the default config settings first, followed by the correct environment config based on either the settings in wp-config.env.php or the webserver environment variable. Your configuration then works seamlessly across your local, staging, and production URLs.

Jones’ experience with agency work inspired him to create the WordPress multi-environment config project. “Like many web developers and digital agencies, at Studio 24 we work on multiple environments for client websites,” he said. “In my experience most CMSs don’t have great support for multiple environments, it’s usually a case of local config files or changes to the database when files are pushed live. Even Drupal is only just starting to look at adding support for multiple environments in Drupal 8.”

Jones believes that WordPress needs multiple environment support in core. “Very few CMSs really consider this and it’s an essential feature for people working on the modern web,” he said. “With all the great improvements in WordPress over the past few years, features to help developers deploy and work on multiple environments would be great to see.”

A better configuration management system would allow WordPress developers to be more efficient when working with enterprise environments, which often have more complex deployment workflows. Smaller agencies, individuals and anyone building WordPress sites may also benefit. Even if most WordPress users don’t work on their sites in multiple environments, there might be a way to make configuration management easier for those who do.

In the meantime, Jones’ WordPress Multiple Environment Config provides a nice solution. Although it doesn’t handle migration of database data between environments, this setup offers a clean and convenient way to manage configuration when moving between sites. For more details on how to install and use it, check out the project’s page on GitHub.

24 Comments


  1. Sounds impressive Sarah

    “Work Seamlessly Between Development, Staging, and Production Sites” is perhaps the “Philosopher’s stone” of WordPress.

    I’ll have to read this one a couple of times to understand the details.

    Report


  2. First we will copy database to all enviroments?
    Sorry for about dumb question but I’m new. .(

    Report


    1. Yeah this solution basically just handles the config aspect of it, doesn’t take care of migrating databases – you’ll still have to do that.

      Report


      1. Which is precisely the REAL issue when trying to tackle multi-environment WP project.

        Report


      1. Let’s say my client create contents on the production site and we are developing some features on the dev -> staging part. How can we merge these databases ? Have you got some articles or ressources for this problem when working on multiple environment ?

        Report


  3. Thanks for the article – will definitely check this out.

    The WP CLI tool has a very handy “deploy” plugin that migrates the database…for those comfortable with the command line.

    Report


  4. Hi @Sarah !
    Thanks about that. How can we manage de DB problem on a dev/staging/production environment ? Let’s say my client create contents on the production site and we are developing some features on the dev -> staging part. How can we merge these databases ? Have you got some articles or ressources for this problem when working on multiple environment ?

    Thanks a lot !

    Report


  5. hi ThachPham, this solution takes care of different config settings on your local and live websites, and a staging test site if you have one. It doesn’t take care of the database itself, however.

    I use it for things like database login details, debug mode, anything that you want to be different between your local test site and your live one. It also takes care of the site URL in the WordPress database so you don’t need to hack that in the database when going live.

    You’re quite right, you need to copy your database from local to your live environment too. I usually work on a local copy of the site while building a site so when I’m ready to review this on staging or live I’ll just copy the DB up to the live website (via SQL dumps). If you have database connection settings correctly setup in the multi-environment config it should then just work.

    Maybe there’s a need for easy database synching too! But I think there are a few solutions out there already like WP Migrate DB https://wordpress.org/plugins/wp-migrate-db/

    Report


    1. WP Migrate DB (or the Pro version) does not merge databases. It simply overwrites the targeted tables with the source tables. It is very elegant and works well for what it does. One really handy thing it does is to automatically replace URLs as needed from one environment to the other.
      But it does not solve what seems to be the Holy Grail of multi-environment collaborative WP development…which at least for me is the biggest pain point of multi-environment developing.

      This multi config file thing looks very clever and should at least help with part of the pain anyway! Thanks!

      Report


  6. Something similar but superior (IMHO) has already been implemented for WordPress by the roots guys as part of their Bedrock project. Their approach is much simpler and uses environment variables stored in .env files. When combined with Capistrano deploys, it works like a charm.

    http://roots.io/wordpress-stack/

    Report


    1. Genesis Skeleton for WordPress is also a good alternative. I find it sharing many aspects of Roots.io. The main advantage that I see with GSW is that it doesn’t alter WP’s folder structure. It has the whole package of multi-environment work, along with utilities that will copy DBs for you and even do backups (something Roots still has on their to-do list on Bedrock).

      https://github.com/genesis/wordpress

      Report


      1. Nice link. There’s a lot of things to learn with GSW. Looks like more complicated than the wp-config.php setup, but interesting to check it out.

        Report


  7. Very sweet post Sarah – thanks! Looks like its time to revisit the mysql via git thing again :)

    Report


  8. I can’t wrap my head around which problem this solves. The wp-config.php file should be unique for each site. You shouldn’t be managing it under version control. And why do I need the database credentials for the live site on your testing server? Or your local development machine? If I break into your testing server then I would also have the necessary credentials for your live server now.

    If you really want to have some settings keep them in a separate file in the root of your WordPress install and include it in wp-config.php and then version control that file.

    Pro tip: If you need to enable WP_DEBUG temporarily you can set-up a simple conditional in wp-config.php

    <?php
    if( isset($_GET['xyz']) ) {
    define('WP_DEBUG', true);
    }

    Then just add ?xyz to the end of a URL to show error messages. Handy when you have a problem on the live server and want to see what the error message is.

    Report


    1. This is attempting to solve a problem when it is not feasible to have multiple versions of the same file — e.g. a repository structure. The goal is to make the entire codebase server-agnostic, which is not an easy thing to do.

      Report


  9. Russell Heimlich – I disagree, it is useful to keep configuration in version control so when different people work on a project things can be up and running easily. If someone can break into a test server, they can break into a live server. Most config settings aren’t unique between a test and live version of a site, except perhaps database and debug settings.

    Also, I wouldn’t advocate adding a GET param to enable debug mode since is a security risk in live environment. Security through obscurity isn’t a great approach.

    Paul – the if/switch approach is what we used to use, though I prefer the organisation of splitting this out into multiple files. Makes things a bit more transparent and easier to manage. But there are lots of ways of achieving the same aim :)

    Report


  10. This is a very nice solution. Does this method also supports a WordPress multisite setup?

    Report


  11. This is not working if lime we you do not use the host file and instead use different folders in htdocs for the development environment. I am using for instance localhost/nameofsite for my development environment and I get a ‘error establishing a connection to database’. Anything that can be done for this particular case?

    Report


  12. This is nice but it only tackles the easy part of multi-environment WP configurations. If you build a site and launch it live and then get a change request from the client, you either have to do a content freeze on the live site and work on dev->staging and deploy to Live post QA OR you have to tackle the challenge of merging your new dev work into the live DB. That is the REAL issue we need a solution for in the world of WP development. RAMP is the only solution that I’ve found which comes close.

    Report


  13. Interesting discussion. As freelance developer I have years of experience using corporate CMS’s based on SAP, and would never imagine a scenario without different environments.
    Minimum is always 3. Dev, Test and Prod. But I’ve been with customers where 4 or more is the norm.
    The lack of any sort of support on this area when using WordPress (or any othe open source CMS for that matter) is something that really frightens me. Not only from a maintenance perspective, but also when you’re trying new stuff, were you’re often forced to try that in Production.

    That is why I find the idea of Flat File CMS’s (like Kirby http://getkirby.com/ for example) a very interesting alternative (at least when it comes to solve this developers dilemma).

    I’m not comparing which type of CMS is better, or want to dive into the DB or no DB debate.

    But the fact that replicating an environment (content included) happens in a snap, makes me consider very seriously the Flat File CMS option.

    Any thoughts on this ?

    Cheers.

    Report

Comments are closed.