Skip to main content

Configure Your wp-config.php File

Adjust and customize your WordPress configuration file on Pantheon.


This section provides information on how to configure the wp-config.php file for a WordPress site. Refer to Configure Your Settings.php File if you have a Drupal site.

WordPress Configuration

WordPress configuration is set in wp-config.php in your WordPress site root. Pantheon automatically includes this file for you with all you need to get started when you install a WordPress site.

Most users do not need to customize this file. However, you can customize the wp-config.php file with any customizations you need for plugins, themes, and caching.

Two additional config files are referenced in wp-config.php:

  • wp-config-local.php: this is an optional file for local development settings and is based on the example wp-config-local-sample.php found in your WordPress site root.

  • wp-config-pantheon.php: this is for dynamically-supplied platform configuration settings (such as database credentials).

Warning:
Warning

Never put the database connection information for a Pantheon database within your wp-config.php file. These credentials will change.

Ensure that you are running the latest version of WordPress core and have the correct wp-config.php file for Pantheon if you experience connection errors.

Pantheon's WordPress Config

View Pantheon's WordPress Configuration

You can also find this file on GitHub.

<?php
/**
 * This config file is yours to hack on. It will work out of the box on Pantheon
 * but you may find there are a lot of neat tricks to be used here.
 *
 * See our documentation for more details:
 *
 * https://pantheon.io/docs
 */

/**
 * Pantheon platform settings. Everything you need should already be set.
 */
if (file_exists(dirname(__FILE__) . '/wp-config-pantheon.php') && isset($_ENV['PANTHEON_ENVIRONMENT'])) {
	require_once(dirname(__FILE__) . '/wp-config-pantheon.php');

/**
 * Local configuration information.
 *
 * If you are working in a local/desktop development environment and want to
 * keep your config separate, we recommend using a 'wp-config-local.php' file,
 * which you should also make sure you .gitignore.
 */
} elseif (file_exists(dirname(__FILE__) . '/wp-config-local.php') && !isset($_ENV['PANTHEON_ENVIRONMENT'])){
	# IMPORTANT: ensure your local config does not include wp-settings.php
	require_once(dirname(__FILE__) . '/wp-config-local.php');

/**
 * This block will be executed if you are NOT running on Pantheon and have NO
 * wp-config-local.php. Insert alternate config here if necessary.
 *
 * If you are only running on Pantheon, you can ignore this block.
 */
} else {
	define('DB_NAME',          'database_name');
	define('DB_USER',          'database_username');
	define('DB_PASSWORD',      'database_password');
	define('DB_HOST',          'database_host');
	define('DB_CHARSET',       'utf8');
	define('DB_COLLATE',       '');
	define('AUTH_KEY',         'put your unique phrase here');
	define('SECURE_AUTH_KEY',  'put your unique phrase here');
	define('LOGGED_IN_KEY',    'put your unique phrase here');
	define('NONCE_KEY',        'put your unique phrase here');
	define('AUTH_SALT',        'put your unique phrase here');
	define('SECURE_AUTH_SALT', 'put your unique phrase here');
	define('LOGGED_IN_SALT',   'put your unique phrase here');
	define('NONCE_SALT',       'put your unique phrase here');
}


/** Standard wp-config.php stuff from here on down. **/

/**
 * WordPress Database Table prefix.
 *
 * You can have multiple installations in one database if you give each a unique
 * prefix. Only numbers, letters, and underscores please!
 */
$table_prefix = 'wp_';

/**
 * For developers: WordPress debugging mode.
 *
 * Change this to true to enable the display of notices during development.
 * It is strongly recommended that plugin and theme developers use WP_DEBUG
 * in their development environments.
 *
 * You may want to examine $_ENV['PANTHEON_ENVIRONMENT'] to set this to be
 * "true" in dev, but false in test and live.
 */
if ( ! defined( 'WP_DEBUG' ) ) {
	define('WP_DEBUG', false);
}

/* That's all, stop editing! Happy Pressing. */




/** Absolute path to the WordPress directory. */
if ( !defined('ABSPATH') )
	define('ABSPATH', dirname(__FILE__) . '/');

/** Sets up WordPress vars and included files. */
require_once(ABSPATH . 'wp-settings.php');
Info:
Note

$_SERVER['SERVER_NAME'] should not be used to set WP_HOME or WP_SITEURL. Refer to SERVER_NAME and SERVER_PORT on Pantheon for more information.

Pantheon Platform Settings in wp-config-pantheon.php

Pantheon includes the wp-config-pantheon.php file to get the latest WordPress upstream updates while avoiding merge conflicts.

Apply the latest upstream updates in WordPress and Drupal Core Updates if you don’t see the wp-config-pantheon.php file in your WP code directory.

Do not edit the wp-config-pantheon.php file. It includes database and environment configuration settings that the platform uses and that Pantheon maintains.

Environment-specific Configuration

Write Logic Based on the Pantheon Server Environment

There are two options for writing logic based on Pantheon server environment:

  • Check if $_ENV['PANTHEON_ENVIRONMENT'] exists for web only actions, such as redirects. If it exists, it will contain a string with the current environment (Dev, Test, or Live):

    wp-config.php
    // Pantheon - web only.
    if (isset($_SERVER['PANTHEON_ENVIRONMENT'])) {
         // Only on dev web environment.
         if ($_SERVER['PANTHEON_ENVIRONMENT'] == 'dev') {
          // Custom code.
         }
    }
  • Use the constant PANTHEON_ENVIRONMENT for actions that should take place on both web requests and wp-cli commands (for example, Redis cache configuration). It will contain the current Dev, Test, or Live:

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

Local Database Development Configuration in wp-config-local.php

The Pantheon WordPress upstream includes a sample configuration file for local development.

Make a copy of the wp-config-local-sample.php file called wp-config-local.php if you are developing locally and need to configure WordPress for your desktop environment. This file is listed in the .gitignore file and will not be tracked by version control by default.

WordPress makes local development easier by using the configuration in the wp-config-local.php file instead of the settings in wp-config.php whenever wp-config-local.php is detected.

Frequently Asked Questions

How do I enable debugging?

The following example shows how to hard-code your WordPress debug configuration based on the environment. Refer to Advanced Options for wp-config.php for more information:

wp-config.php
// All Pantheon Environments.
if (defined('PANTHEON_ENVIRONMENT')) {
  // Turns on WordPress debug settings in development and multidev environments, and disables in test and live.
  if (!in_array(PANTHEON_ENVIRONMENT, array('test', 'live'))) {
    // Debugging enabled.
    if (!defined('WP_DEBUG')) {
      define( 'WP_DEBUG', true );
    }
    if (!defined('WP_DISABLE_FATAL_ERROR_HANDLER')) {
      define( 'WP_DISABLE_FATAL_ERROR_HANDLER', true ); // 5.2 and later
    }
   if (!defined('WP_DEBUG_DISPLAY')) {
      define( 'WP_DEBUG_DISPLAY', true ); // requires WP_DISABLE_FATAL_ERROR_HANDLER set to true
    }
    define( 'WP_DEBUG_LOG', __DIR__ . '/wp-content/uploads/debug.log' ); // Moves the log file to a location writable while in git mode. Only works in WP 5.1
  }
  // WordPress debug settings in Test and Live environments.
  else {
    // Debugging disabled.
    ini_set( 'log_errors','Off');
    ini_set( 'display_errors','Off');
    ini_set( 'error_reporting', E_ALL );
    define( 'WP_DEBUG', false);
    define( 'WP_DEBUG_LOG', false);
    define( 'WP_DISABLE_FATAL_ERROR_HANDLER', false );
    define( 'WP_DEBUG_DISPLAY', false);
  }
}

How can I override the default PANTHEON_HOSTNAME value?

In your wp-config.php, above the line that requires wp-config-pantheon.php, you can set the PANTHEON_HOSTNAME constant to the desired value:

wp-config.php
define( 'PANTHEON_HOSTNAME', 'example.com' );

Note that in most cases you shouldn't need to do this. The logic in the wp-config-pantheon.php covers most instances where you might need a unique hostname. It's recommended that you only change this in very specific cases and your code has conditions to handle those.

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

Refer to Reading the Pantheon Environment Configuration.

How do I perform redirection?

Refer to 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 your wp-config.php file:

WP version 5.0.x and older versions:

wp-config.php
ini_set( 'error_log', WP_CONTENT_DIR . '/uploads/debug.log' );

As of WP version 5.1 and newer:

wp-config.php
define( 'WP_DEBUG_LOG', __DIR__ . '/wp-content/uploads/debug.log' );

Where do I specify database credentials?

You don't need to specify database credentials. 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?

How do I enable ionCube Decoder support?

  1. Verify that you are running PHP 7.1 if you are using a licensed plugin that requires ionCube Decoder support. Please note that later PHP versions do not currently support ionCube.

  2. Enable ionCube Decoder support site-wide by adding this line to settings.php:

    settings.php
    ini_set('ioncube.loader.encoded_paths', '/');

More information can be found in our PHP 7.1 & ionCube Decoder Now Available for All Sites on Pantheon blog post.

Can I increase the memory limit of my WordPress site?

WordPress installations have a core PHP memory limit of 40MB for single sites and 64MB for WordPress Multisites by default. You can increase this limit up to the limit of memory allocated for your site plan.

Example for Elite sites:

wp-config.php
define( 'WP_MEMORY_LIMIT', '512M' );

Troubleshooting

Actions and Filters in wp-config.php

Actions or filters that require CLI tools like WP-CLI might fail from wp-config.php, because the functions required are not yet accessible. Put these directives in an MU Plugin to resolve this issue.

More Resources