Taking A Closer Look At The WordPress wp-config.php File

Some people will never touch the file that sets the most important details that make a site unique: wp-config. In fact, since WordPress automatically creates the file during its famous “5 minute installation” a lot of users don’t even know it’s there or ever need to touch it. That’s a great thing.

Part of what makes WordPress such a great tool, for anything from simple blogs to the backbone of a complex web apps is both its simplicity and flexibility. Different users have different needs, but once you start getting into any type of development work with WordPress, you’re going to need to do some customization, much of which begins in wp-config.

In this article, I’ll walk you through what wp-config must have. After that, I will show you how to use it to help with debugging and how to modify the WordPress directory structure. Then at the end, I’ll give you a few other quick tips.

There is one thing to keep in mind before I begin though. When I say wp-config.php must have or can have, I’m actually referring to that file or any file included in it. Also, keep in mind that when wp-config is run, almost none of the rest of WordPress has been loaded yet. Therefore, pretty much any WordPress functions can not be used. For this reason, you can only safely use functions defined in PHP itself.

What Are Constants?

Most, but not all of what you do in wp-config is set the values of constants, so it’s important to understand constants, before discussing wp-config. Constants are a type of identifier, that like a variable holds a value. The big difference between a constant and variable, is that once  a constant is defined, its value can not change.  They are like non-variable, variables.

This means that we can use them to house global settings for an application, IE WordPress, or for a component of it, IE a plugin or theme.

Constants are defined using a simple function called define(). This function accepts two parameters, the name of the constant and the value. By convention constants are always in all caps. Here’s a simple example:

 define( 'DB_NAME', 'wp42' ); 

Because of the nature of constants, attempting to define  a constant that is already defined, will generate an error. As a result, we often wrap constant definitions in a conditional check using the function is_defined(), to check if the constant was already defined. For example, a plugin might have a “dev mode” to make the the plugin easier to debug, but less performant. In the plugin itself, that would be defined inside of a conditional check, like this:

if ( ! defined( 'SLUG_DEV_MODE' ) ) {

define( 'SLUG_DEV_MODE' , false );

} 

This way an end-user can override the default value by defining a different value for the constant before the plugin runs. The best place to do this is in wp-config. Why? Because wp-config is one of the first things that WordPress runs. Also, when you update WordPress, wp-config is not changed.

Because of this, we can make various customizations there, before WordPress assigns the default values.

What wp-config must have

There are a lot of constants that you can define in wp-config, that if you do not, WordPress will set a default value. But, there are certain values that do not have a default, and therefore you must define in wp-config, or WordPress will not function.

These constants without defaults, can be lumped into two categories: database credentials and security salts. There is one more required constant you must set, and that is ABSPATH, which is the path, relative to wp-config for WordPress itself.

There are a few other things that wp-config must do that do not deal with constants. One is setting the database prefix in a global variable, $table_prefix. The other is load the next file in the process of loading WordPress itself. That’s why wp-config.php should always end with this line:

require_once(ABSPATH . 'wp-settings.php');

Unless you need to change your database details later, you should never need to modify the constants for your database. Those are the ones that begin with DB_. The same goes for the salts. That is as long as they are not compromised.

Now that we’ve covered what wp-config.php can have, let’s talk about the basics of what it can do.

WordPress Debugging

Have you ever gotten the dreaded “white screen of death” and not known why this happened? When you see only a white screen, that means PHP has encountered a fatal error. It would have told you what the error is, but by default WordPress suppresses all errors and warnings. As we just discussed, wp-config is the place where we override defaults.

There are three main constants that deal with debugging. The first is WP_DEBUG, which turns on debugging in WordPress, when set like this:

define( 'WP_DEBUG', true );

Now that same white screen of death will print an error. The reason why it does not by default is that you probably do not want that in a live site, visible to the whole world. Also, not all errors and notices PHP generates are fatal. While its a good idea to address each of them, sometimes you need to live with them.

That doesn’t mean to ignore them entirely. That’s where the other two constants I mentioned come in. You can add the following two constants to prevent errors from being displayed, but write them to your error log:

define( 'WP_DEBUG_DISPLAY', false );
define( 'WP_DEBUG_LOG', true );

These functions do exactly what there names imply. The first one WP_DEBUG_DISPLAY, when false prevents errors that would be shown, if WP_DEBUG is defined as true, from being visible. The second, will write each error to a log file in your content directory.

Changing WordPress’ Directory Structure

Notice that in the previous paragraph I wrote “content-directory” not “wp-content”. That is because wp-content is what its called when you use the default value of the two constants that define the location of the content directory. I make this distinction not just to be semantically correct, but to point out why a hard coded reference to wp-content is never a good idea.

The path to your content directory is set by two constants WP_CONTENT_DIR and WP_CONTENT_URL. These set the file path and url for the content directory.  Here is an example where the content directory is renamed ‘content’ and moved inside of  a sub directory of the directory that wp-config.php is in

define( 'WP_CONTENT_DIR', dirname(__FILE__)  . '/resources/content' );
define( 'WP_CONTENT_URL', 'http://' . $_SERVER['HTTP_HOST'] .  '/resources/content';

I love renaming the content directory to something that matches the name of the site. This makes more sense when viewing the file structure. In addition is means I can search my computer for the content directory of a particular site by its name and get one result, as opposed to a search for wp-content, which is going to return a result for every WordPress site on my computer, plus all the random WordPress downloads floating about.

You can also move the location of WordPress itself by changing the value of ABSPATH. It’s very common to move it to a folder called ‘wp’, like this:

if ( ! defined( 'ABSPATH' ) ) {
    define( 'ABSPATH', dirname( __FILE__ ) . '/wp/' );
}

This is a great thing to do if you have your site under Git version control, as you can easily set Git to ignore that directory. That way updates to WordPress can still be handled via the WordPress updater, and doing so doesn’t create a huge commit in your Git repository.

What Else Can It Do?

You can do a lot in wp-config to help adapt WordPress to fit your needs. There are a lot of other simple problems you can solve there. For example, do you want to disable the plugin and theme editors in the WordPress admin. It’s as simple as adding this to your wp-config:

define( 'DISALLOW_FILE_EDIT', true );

Another good thing you can do there is limit the number of revisions to keep per post, or to disable them entirely. The number of post revisions is set using the constant WP_POST_REVISIONS. To limit to 15 revisions, you can do this:

define( 'WP_POST_REVISIONS', 15 );

Or to disable post revisions completely:

define( 'WP_POST_REVISIONS', false );

One more before we go. By default, WordPress allocates 40MB of memory to PHP. Once you start adding on a ton of plugins, or start working with anything that requires a lot of database queries, that can quickly become not enough.

Of course, there is a constant to override that default, WP_MEMORY_LIMIT. For example, to allocate 96MBs of memory, you would use this:

define( 'WP_MEMORY_LIMIT', '96M' );

I intentionally left off the “B” in MBs. This constant should always be a number followed by M. Even if you wanted to allocate a gigabyte of memory. In that case you would use “1024M”. The other thing to keep in mind is that while you can define any value there, your server can only allocate as much memory as it has available.

Article thumbnail image by Jane Kelly / shutterstock.com