wordpress-multi-env-config: splitting one wp-config.php across three environments

One wp-config.php becomes three layered files

The problem this package addresses is mundane and recurring. A WordPress installation normally keeps every setting, from the table prefix to the database password, in a single `wp-config.php` file in the web root. Run the same codebase in production, in staging and on a developer's laptop and you now have three copies of that file to keep in step, each holding the same secrets in three places.

Studio 24's setup replaces that with up to three files that are loaded in order. The README lists them as the default configuration in `wp-config.default.php`, holding shared settings such as `$table_prefix`; the environment configuration in `wp-config.{ENVIRONMENT}.php`, holding anything specific to one environment such as the database name or debug mode; and the optional local settings in `wp-config.local.php`, intended for sensitive values such as the database password that should not be committed to version control.

The split is not cosmetic. A setting that is identical everywhere lives in the default file and is written once, a setting that differs per environment lives in the per environment file, and a secret lives only in the local file. That last file is the reason to use the package at all: it gives the sensitive values a home that is separate from the code that gets deployed.

The repository ships the matching sample files, `wp-config.development.php`, `wp-config.production.php`, `wp-config.staging.php` and `wp-config.local.php`, along with `wp-config.env.php` and `wp-config.load.php`. The README credits FocusLabs EE Master Config for the inspiration for the organisation of these config files.

Environment detection has three routes, and the hostname is only the default

The current environment is resolved at request time. The README describes three ways to set it, and the order matters because one of them overrides the others.

The first and most explicit is the `WP_ENV` environment variable, set in the webserver configuration. The README shows the Apache form.

    SetEnv WP_ENV production

The second is the server hostname, matched against the domains defined in `wp-config.env.php`. This is the default behaviour, so a site with no explicit `WP_ENV` will be classified by the hostname the browser requested. The third route is WP-CLI, where the environment is written as a plain string in a file called `.env` placed among the `wp-config.*.php` files.

development

The README notes that this `.env` file needs to sit with the other `wp-config.*.php` files, which matters if you keep those in a sub-folder with only `wp-config.php` in the web root. It also recommends that the file is not added to version control, which is a sensible rule because it records which environment a developer is pointed at.

One side effect is worth knowing about. The README says the package sets `WP_ENVIRONMENT_TYPE` with the current environment, and that this is the PHP constant WordPress uses to return the current environment and that some plugins rely on it. That is a useful side effect, but it also means the package writes a constant that core WordPress owns, so a site running a plugin that checks `WP_ENVIRONMENT_TYPE` will start seeing values it did not see before.

wp-config.env.php must be edited first, whatever route you take

There is one file you have to touch regardless of how the environment gets detected. The README is emphatic that `wp-config.env.php` needs to be set no matter which method is used, since all methods set the WordPress URL through the settings in that file.

It holds one array keyed by environment name, and each entry can carry three values: a domain, which is either a string or an array of multiple domains, a path for installs living in a sub-folder, and an ssl flag, which when set also turns on `FORCE_SSL_ADMIN`. The basic shape looks like this.

$env = [
    'production'  => [
        'domain' => 'domain.com',
        'path'   => '',
        'ssl'    => false,
    ],
    'staging'     => [
        'domain' => 'staging.domain.com',
        'path'   => '',
        'ssl'    => false,
    ],
    'development' => [
        'domain' => 'domain.local',
        'path'   => '',
        'ssl'    => false,
    ],
];

The README calls out several variations on that structure. If your local test site runs on localhost, set the development hostname to `localhost` rather than `domain.local`. A sub-folder install plus SSL looks like this.

    'production'  => [
        'domain' => 'domain.com',
        'path'   => 'blog',
        'ssl'    => true,
    ],

Multiple domains for one environment are an array of strings.

    'production'  => [
        'domain' => ['domain.com', 'domain2.com'],
        'path'   => '',
        'ssl'    => false,
    ],

And for WordPress Multisite a wildcard domain is supported, with the caveat that a wildcard domain has to be a single string rather than an array.

    'production'  => [
        'domain' => '*.domain.com',
        'path'   => '',
        'ssl'    => false,
    ],

The three default environment values are `production` for the live website, `staging` for a test website for client review, and `development` for a local development copy. Additional names can be added by extending the same `wp-config.env.php` file, and each one then needs its own `wp-config.{environment}.php` file.

Installing means copying four files and demoting your existing config

The install path is a manual copy, and the README is careful to put a backup step first. PHP 5.4 or above is required, and the README adds that you should really be on PHP 5.6 at a minimum.

You download a zip archive of the release, back up your existing `wp-config.php`, then copy four files from the repository into your WordPress installation.

wp-config.default.php
wp-config.env.php
wp-config.php
wp-config.load.php

After that you edit `wp-config.env.php` for your domains, create one `wp-config.{environment}.php` file per environment using the samples in the repository as a starting point, and then move the settings out of your backed up `wp-config.php` into the right place.

wp-config.development.php
wp-config.production.php
wp-config.staging.php
wp-config.local.php

The README suggests a simple rule for the migration itself: a setting that is the same across all environments goes to `wp-config.default.php`, a setting unique to one environment goes to that environment's file, and a sensitive setting such as the database password goes to `wp-config.local.php`. It also tells you to update the authentication unique keys and salts in `wp-config.default.php`, which is easy to forget when moving a working site across.

If you use version control, exclude the local file.

# .gitignore
wp-config.local.php

That exclusion is the whole point of the local layer. If a developer clones the repository and `wp-config.local.php` is absent, the site has no database password until someone supplies one locally.

Compared with a single config file, the win is the secrets split and the cost is the file count

The obvious alternative is the one WordPress ships with: keep one `wp-config.php` per environment and copy it during deploys. The difference in approach is that the manual approach repeats shared settings in every copy, so a change to a non environment specific value has to be applied everywhere, and secrets end up committed to the repository unless you add the file to a ignore list yourself.

This package makes both problems structural rather than procedural. Shared settings are written once in `wp-config.default.php`, environment specific ones are grouped by environment name, and the sensitive values live in a file the README tells you to keep out of version control. Because the environment name in a filename is the same string used by the environment variable, the hostname map and the `.env` file, the same code path resolves the right file in all three cases.

The cost is complexity and a learning curve. Four files replace one, and a mistyped environment name means the loader silently looks for a config file that does not exist, which the README does not describe because it does not document any fallback behaviour for a missing environment file. A team of one with a single staging-less site gains little here.

There is also an older line of this project. The README states that the current version is v2 and links to the v1 release for anyone who needs the older arrangement, so migration paths and differences between the two versions live in those tagged releases rather than in the current README.

Release history: v2.0.3 in June, with v2.0.1 older than most WordPress installs

The version line is worth reading carefully before you pin anything. The most recent release is v2.0.3 on 2026-06-26, and the last push to the repository carries the same date. Before that came v2.0.2 on 2025-03-24, and before that v2.0.1 on 2022-08-23, which means the gap between the first two v2 releases covers a stretch of about two and a half years.

That gap is the practical signal here. This is not a package that changes every month, and the repository is not archived, but between v2.0.1 and v2.0.2 nothing was released, so a site can sit on an old v2 point release for a long stretch. If you adopt it, adopt the current v2.0.3 rather than an older tag, and read `CHANGELOG.md` before moving between versions.

The repository also includes `version.txt`, which is consistent with the README's advice that anyone needing the v1 behaviour should look at the linked v1 release rather than try to reconstruct it. Files for contribution and reporting problems are present as `CONTRIBUTING.md`, `SECURITY.md` and `CODE_OF_CONDUCT.md`.

One thing the README is silent about is the licence. The repository carries a `LICENSE` file, but the licence identifier for this project is not stated in the README, so before you copy these files into a commercial site, read the licence file in the repository yourself and check that its terms suit your use.

Editorial conclusion

Use wordpress-multi-env-config when you run the same WordPress codebase across production, staging and a local copy and want debug mode or database settings to change per environment without a hand edited config file. Do not use it for a single-environment site, where the extra files cost more than they save, and check first that your PHP version is at least 5.4 as the README requires. Before you rely on it, copy your existing wp-config.php into wp-config.default.php or wp-config.{environment}.php, exclude wp-config.local.php from version control, and confirm your hosting layer actually sets the WP_ENV variable or serves the hostname listed in wp-config.env.php.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. studio24/wordpress-multi-env-config on GitHub