Configuring wp-config.php

Understand how to adjust and customize the WordPress configuration file for your Pantheon WordPress site.

Contributors: Mason James


Overview

WordPress configuration is set in wp-config.php, located within your WordPress site root. When you install a WordPress site, we automatically include this file for you with all the boilerplate you need to get started. Most users will not need to customize this file.

Pantheon uses environment variables to automatically supply configuration settings (e.g. Database credentials) dynamically to wp-config.php - no editing required. However, you are welcome to customize wp-config.php with any customizations you may need for plugins, themes, and caching.

Local Database Configuration for Development

If you are also developing locally and need to configure WordPress for your desktop environment, we recommend you create a wp-config-local.php file. This will be ignored by Pantheon and should not be tracked by version control by default since it's in the .gitignore file.

Pantheon's WordPress Config

Frequently Asked Questions

How can I write logic based on the Pantheon server environment?

Depending on your use case, there are two possibilities:

  1. For web only actions, like redirects, check if $_ENV['PANTHEON_ENVIRONMENT'] exists. If it does, it will contain a string with the current environment (Dev, Test, or Live):

    // Pantheon - web only.
    if (isset($_SERVER['PANTHEON_ENVIRONMENT'])) {
      // Only on dev web environment.
      if ($_SERVER['PANTHEON_ENVIRONMENT'] == 'dev') {
       // Custom code.
      }
    }
    
  2. For actions that should take place on both web requests and wp-cli commands (e.g. Redis cache configuration), use the constant PANTHEON_ENVIRONMENT. Again, it will contain Dev, Test, or Live:

    // Pantheon - all (web and CLI) operations.
    if (defined('PANTHEON_ENVIRONMENT')) {
      // Only on dev environment.
      if (PANTHEON_ENVIRONMENT == 'dev') {
        // Custom code.
      }
    }
    

The following example shows how to hard-code your WordPress debug configuration based on the environment. To learn more, see Defining variables in a wp-config.php:

// All Pantheon Environments.
if (defined('PANTHEON_ENVIRONMENT')) {
  //Wordpress debug settings in development environments.
  if (!in_array(PANTHEON_ENVIRONMENT, array('test', 'live'))) {
    // Debugging enabled.
    if (!defined( 'WP_DEBUG' )) {
    define( 'WP_DEBUG', true );
    }
    define( 'WP_DEBUG_LOG', true ); // Stored in wp-content/debug.log
    define( 'WP_DEBUG_DISPLAY', true );
  }
  // Wordpress debug settings in test and live environments.
  else {
    // Debugging disabled.
    ini_set('log_errors','On');
    ini_set('display_errors','Off');
    ini_set('error_reporting', E_ALL );
    define('WP_DEBUG', false);
    define('WP_DEBUG_LOG', true);
    define('WP_DEBUG_DISPLAY', false);
  }
}

How can I read the Pantheon environmental configuration, like database credentials?

See Reading the Pantheon Environment Configuration.

How do I perform redirection?

See Configure Redirects.

How do I change the default debug.log location?

WordPress has an option to write logging information to a file. When enabled, the file is located in the /wp-content folder, which is not writable on all environments in Pantheon. You can change the location of this file to the uploads folder by adding the following to wp-config.php:

ini_set( 'error_log', WP_CONTENT_DIR . '/uploads/debug.log' );

Where do I specify database credentials?

You don't have to! Pantheon automatically injects database credentials into the site environment; if you hard code database credentials, you will break the Pantheon workflow.

Where can I get a copy of a default wp-config.php for Pantheon?

Troubleshooting

Request to a Remote API Does Not Return Expected Response

The PHP 5.5 default is & and the PHP 5.3 default is &.

If the API expects & as an argument separator but receives & (for example, when using http_build_query), you can override the default arg_separator.ouput value by adding the following line to wp-config.php:

ini_set('arg_separator.output', '&');