The WordPress wp-config File: A Comprehensive Guide
The WordPress configuration file, also known as wp-config.php, is most frequently used to set up a database connection and is then forgotten. Despite its neglected nature, it is a powerhouse of features and opportunities for optimization.
While you don’t typically use the config file on a day-to-day basis, I’m betting that almost every WordPress install could benefit from adding a couple of things to this file. A well thought out config file can not only make a website faster and more secure, it can also add features like the ability to empty the trash more frequently, or disabling features such as revisions and offer advanced debugging capabilities.
In this article we’ll look at the default settings that ship with your config file and how you can tweak it to better suit the needs of your WordPress website.
What is the wp-config.php File?
According to the WordPress Codex, the config file is
One of the most important files in your WordPress installation. It file is located in your WordPress root directory and contains important information such as database connection data (username, password, etc.) and various settings.
wp-config.php is actually not a part of the files that ship with WordPress. If you download the WordPress software you won’t find this file anywhere. Instead, you’ll find
When you install WordPress you can rename this file to
wp-config.php to set up your environment, or WordPress will create a final config file based on the information you give it during installation.
The Default Config Content
You can take a look at the default content of your config file by checking out this sample at GitHub. This is the same
wp-config-sample.php file you get in your own installations. The file is extremely well documented and I’ll explain some of the settings here nonetheless.
Many settings in the config file use PHP constants. As the PHP documentation states, a constant is an identifier for a simple value. The value can not be changed for the duration of the script. The general format of a constant is
define( 'CONSTANT_NAME', 'CONSTANT VALUE' ).
So let’s go through what all the code in the wp-config.php means.
The first six settings are all about the database connection. WordPress stores posts and various other bits and pieces of data in a database; it needs access to said database to function. A database connection typically requires a host, a username, a password and a database name.
The code above shows the constants without the inline documentation. The first four lines define the four settings I talked about previously. The charset and collation both have to do with languages and how specific characters are stored. UTF8 is a good choice because it contains special characters like “ő” for example. Collation determines how strings are compared in the database. Some collations may be case sensitive, others may be case sensitive for example. Unless you specifically know about these things it is best to leave these two settings alone.
Salts And Keys
The next eight settings are all used for securing WordPress. Authentication keys are used as security checks while salts are used when hashing passwords.
You can fill these out yourself but there really is no need. You can use the secret key generation utility to create these constants very quickly.
I highly recommend reading Why WordPress Authentication Unique Keys and Salts Are Important – it is a great read. As the article mentions, changing your keys and salts now and again is not a bad practice. Why not set a reminder every 90 days or so?
Other Config Settings
There are two more settings in there, the table prefix and the debug setting. The table prefix tells WordPress what prefix your database tables use. The default is
wp_, which would mean that your posts table is named
One of the best ways to protect against attacks is to be unpredictable. It is a good idea to use default settings as little as possible, especially when they pertain to something as crucial as your database. If you’re just installing WordPress it’s a good idea to use an obscure prefix such as
Jbh8h3dD_oj3e_. WordPress won’t mind that this is a lot more complex; to a script there is very little difference between
The next setting is all about debugging WordPress. By default it is set to false, which means that error messages will be hidden. This is desirable behavior on production websites, but while coding or debugging you definitely want to see errors so you can fix them. If you ever activate a theme or a plugin and get a white screen you can at least figure out what the issue is by setting the
WP_DEBUG constant to “True.”
Customizing the wp-config File
The config file is just like any other file, which means you can add any valid PHP to it. That being said, you should take care when editing
wp-config.php. Only add to it when absolutely necessary and take care when editing because any incorrect edits you make could cause your website to stop functioning. After all, this is the heart of WordPress we’re tinkering with!
It’s a good idea to refer to the wp-config documentation in the WordPress Codex for all the official tweaks you can make to this file. All the additions I’ll be mentioning in this article are safe to use if pasted correctly, but please be aware of what each of them does.
There are some edits that you can make which have a place in the config file but are not a part of the documentation. One good example of this is the API access key and secret for your Amazon S3 server when using the Amazon S3 and Cloudfront plugin. You could also use it to store your Google Fonts or Google Maps API key and other similar things.
Do keep in mind though that this method is not for every single bit of data around. If you’re creating a plugin where the user needs to enter his/her address it should be stored in the database.
1. WordPress URLs
There are two settings you can set in the config file which control WordPress URLs. One is the
WP_HOME constant and the other is the
WP_SITEURL constant. There is always some confusion about these, so let’s clear things up.
Both settings can be controlled from the WordPress settings section in the admin. The first setting in the screenshot, the WordPress address, corresponds to
WP_SITEURL.The second setting, site address, corresponds to
When you use the config file to define these URLs, the settings given in the admin are overwritten and the config file takes precedence.
The WordPress address, or
WP_SITEURL, is the URL that users enter to visit your website. The site address or
WP_HOME should point to the root of your WordPress install, which could be in a sub-directory.
To learn more about the use and issues with these URLs I suggest reading Using WP_SITEURL and WP_HOME to migrate a WordPress site.
2. Custom Directory Locations
The config file allows you to modify the location of various folders used by WordPress. You can move the content, plugins and uploads directories and create additional theme directories using the method outlined below. There are three reasons you may want to do this:
- Mimicking a folder structure following a site migration from another system
- Additional security based on not relying on the default structure
- Clearing up clutter from the root directory
Note that different folders behave slightly differently. The
wp-content folder requires an absolute path and a full URI to be given. The
plugins directory is much the same, but for compatibility issues you may want to use the
PLUGINDIR constant as well.
Themes and uploads are a bit different. The default theme directory is hardcoded into WordPress, it is always set to the directory named
themes inside the content directory. You can, however, add additional theme directories. In the code above I created a theme directory in the root folder.
The uploads directory is always relative to the
ABSPATH directory, which would be your root directory. In this case I have placed the directory in the root folder.
Assuming WordPress is in a
wordpress sub-directory the code above would result in the following folder structure:
There is a special kind of plugin folder not many people know of called
mu-plugins, short for “Must-use Plugins.” These plugins are loaded by default before any other plugins. To learn more about them ready the Must Use Plugins documentation in the Codex. If you like the idea but want to change the location you can do so in a similar fashion to how we changed the plugin directory above.
3. Custom Default Theme
The default theme in WordPress is the most recent twenty-something theme. In WordPress 4.0 this would be Twenty Fourteen. If you would like a different fallback theme you can change the
WP_DEFAULT_THEME to the folder name of your preferred theme.
If you must change this I advise choosing a simple but very well-coded theme. If something goes wrong and your site’s theme is missing it will revert back to the default theme.
Custom Database Tables
WordPress has the ability to use a different table name for the users and usermeta tables. Using a custom table name could give you some additional protection although it is highly probably that if someone has access to your database they will figure this one out.
Before you make the change be sure to read up on changing user tables to make the transition as smooth as possible.
4. Revisions, Autosaves And Trash
I’m betting that many WordPress users don’t use the post revisions feature. Even though it has been around since WordPress 2.6 it’s use is relegated to niche corners of the web. Luckily, WordPress allows you to limit or disable revisions easily using the
Note that you should only use one or the other, I’ve just placed both in one example for easy reference.
The use of autosaves are more widespread but these may happen a bit more frequently than you need them to. By default WordPress saves your post every 60 seconds. If you create content by copy-pasting it, or you’re not worried about loosing a minute’s worth of work you could increase the autosave time.
The trash is another source of clutter which can be controlled easily. By setting the
EMPTY_TRASH_DAYS constant you can control how many days a post stays in trash before it is completely deleted. You may also set this to 0 to disable the trash altogether.
5. WordPress Multisite
The config file is the starting place for creating a multisite install. The Create a Network page in the Codex sums up what a Multisite installation actually is:
A multisite network is a collection of sites that all share the same WordPress installation. They can also share plugins and themes. The individual sites in the network are virtual sites in the sense that they do not have their own directories on your server, although they do have separate directories for media uploads within the shared installation, and they do have separate tables in the database.
Multisite allows you to create separate sites based on the same WordPress install. This allows you to manage a multitude of sites very easily. Multisite is commonly used for corporate websites where the shop, blog and company site may be separate. It could also be used to host websites for a community of bloggers. Developers use it to host multiple themes and plugins.
To get started you’ll need to define a single constant:
Once defined, reload the WordPress admin and you should see a “Network Setup” option in the “Tools” section. Follow the instructions outlined there. WordPress will ask you to add additional settings to your config file as well as your .htaccess file. Once done you should be logged out and when you log back in you’ll have a nice new network install. Refer to the Create A Network page for a more complete setup guide.
A setting related to Multisite installs allow you to redirect users when someone accesses a sub-site, which does not exist. The
NOBLOGREDIRECT constant defines the URL users are directed to in these cases.
Especially when working with Multisite installations you may want to make sure that plugins and themes cannot be edited using the built-in file editor, you may even want to make sure users can’t install their own plugins and themes. This can be achieved with the
Note that if you define
DISALLOW_FILE_MODS as true you don’t need to define
DISALLOW_FILE_EDIT since this will be disabled as well.
6. Developer Settings
The config file has a number of settings which help developers catch errors or write better code. The most prominent of these is the
WP_DEBUG constant, which we’ve already look at. Defining this as “True” will force errors to be displayed.
By default, scripts are concatenated and minified. Concatenation is the process of joining files. Instead of loading 20 scripts individually WordPress concatenates them into one file and loads that. Minification is the process of compressing a file into a format which is non human-readable but computers work just fine with it. These two methods save considerable loading time and server resources.
Debugging often relies on log files, especially if errors are not shown. Many errors only occur in specific circumstances so as a developer we don’t always encounter them. This is where logging comes in handy. Instead of displaying error messages we can log them to a file and look over them every now and again. This can be done by defining
When enabled the errors encountered will be logged to a file named
error.log in the
For the hardcore optimizers among us, the
SAVEQUERIES constant is a life-saver. By defining this constant to be true we can access detailed profiles of the SQL queries performed by WordPress:
Once defined we can print the content of
$wpdb->queries to get an overview of all the queries.
If you’re feeling particularly fancy or you need to look at these queries all the time you can hook this into
wp_footer to make sure they are always displayed at the end of each page.
7. Increasing The Memory Limit
In some rare cases you may need to manually allot more memory to WordPress. While I have encountered situations where PHP ran out of memory while running WordPress, these were all caused by wasteful themes or plugins.
If you need to you can set the memory limit with the
WP_MEMORY_LIMIT constant and the
WP_MAX_MEMORY_LIMIT constant, which controls the amount of memory available for the admin.
8. Cron Settings
Cron is a time-based job scheduler in Unix-like environments. WordPress has a cron feature, which is not a real cron but copies its features closely. WordPress cronjobs run at regular intervals and perform various tasks. For example, the cron system is responsible for publishing posts at the correct time.
The drawback of the system is that it relies on site visitors to perform cronjobs so the task may not run at the exact given time. If you set a real cron on your server to run at 1am every night it will do so with extreme precision.
WordPress crons are triggered by visitors loading the site. This means that if you use WP cron to initiate an action at 1am it will be run the first time the website is loaded after that time. If you don’t have any visitors until 11am, the task will be completed then.
In most cases this is not a problem. If you’ve set a post to be published at 1am and noone visits the site until 11am the post will be published before the site loads for the user, for all intents and purposes, the post was published on time.
In some cases the cron system may throw a fit and refuse to work properly. I have never personally encountered this, but if you see this happening you can try using an alternative cron method:
The config file also allows you to disable the cron altogether and to limit the repeat interval between the same cronjob.
9. Disabling Table Updates
When WordPress is updated it may run a
dbDelta() function, the purpose of which is to modify your database to conform to the latest specifications. This usually poses no threat at all but for sites with huge tables (especially username tables) this may take a while to complete.
Many large sites prefer to take care of these operations themselves, or perhaps schedule them for a time when there is little traffic. This can be done by disabling the upgrading of global tables:
10. SSL In The Admin
There are two options in the
wp-config.php file which allow you to use SSL.
FORCE_SSL_LOGIN makes sure that logins always use SSL, but the admin sessions themselves don’t. This adds some protection while making sure SSL doesn’t slow down the admin process.
You can also use
FORCE_SSL_ADMIN, which will use SSL for login and throughout the admin session, including the cookies:
FORCE_SSL_LOGIN, so if you’re using the more secure option there’s no need to define
Depending on your server setup there may be a bit more you need to do to access your site via SSL. I suggest reading the excellent Administration Over SSL guide in the Codex.
11. Disable Automatic Updates
I personally enjoy automatic updates because they make my website safer and ensure I’m always running the latest version of WordPress. Being always up-to-date is a good thing and there are very few legitimate cases where not updating is a good idea. Modifying WordPress core files, a downloaded theme or plugin is never one of them.
If you need to disable updates for any reason, WordPress gives you two constants to do so.
AUTOMATIC_UPDATER_DISABLED can disable all automatic updates in one go. A better way to do this is to use the
This can be set to “True” to enable updates and “False” to disable them. In addition, you can set it to “Minor” (this is the default) to grab minor updates by default:
As you can see, the WordPress configuration file offers plenty of opportunities to tweak your site and make it your own. From modifying directory locations to logging in via SSL, a lot is possible.
What are your favourite
wp-config.php tricks, did I miss anything or do you use something which isn’t official but works great? Let us know in the comments below.