Create a Theme Config File in WordPress

One of the aspects of WordPress that people really like is the ability to add options. This is something that WordPress theme and plugin creators use heavily. They’ll create an options page or pages so that anyone who uses their theme or plugin can customize numerous different components of the theme… everything from look and feel, to contact form data, to portfolios, to just about anything else under the sun. Creating an option is as easy as storing adding an option:

<?php add_option('nbs_background_color', '#FFCC66'); ?>

Then to use an option in your webpages you just need to call get_option…

get_option('nbs_background_color')

Note: Notice that I used the prefix “nbs” (for Nine Bit Studios) before my option name. This is a common practice to prevent potential collision with other options because each option has to have a unique name. It’s very possible that another plugin that I have installed may have used the option “background_color”. By adding a prefix this is no longer an issue.

That’s all well and good, but there are a few potential downsides to this. For one, depending how your options are set up, it can be a fair amount of work to add, update, or remove options because you have to edit the code to register the option, edit the form for the user to set or update the option, edit the code to handle the values they set, etc. Hopefully, you have your theme or plugin options set up such that making changes is as smooth and easy as possible. It’s not a difficult process, but it can get a bit involved as the number of options that you want to handle grows in size and complexity.

On top of this, when you deactivate themes or plugins, options do not necessarily get deleted. As a result, there’s the potential that you’ll have old unused options lingering around in your wp_options table which is not the best situation for efficiency. There are plugins out there that supposedly are able to do clean up for you, but their efficacy likely varies (as with many things) :).

All that being said, options should still be used for most of your theme or plugin configuration since they are the default go-to for customizations of WordPress installs. You’ll want to give your less tech-savvy users an easy interface to customize things. But as WordPress continually grows in maturity from being not just a blogging platform as it was in it’s early days, to a full-fledged CMS, and even on to a web application platform, there comes a desire to start introducing some useful components that have been popular and effective in other web application platforms. One of these things that you’ll often find in web application platforms like Django, CodeIgniter, Laravel and countless others is a main “config” file where all sorts of constants can be set. These are useful for everything from running debug code, to setting name strings, to language settings, to charsets, to whatever else. It can be pretty much anything you want.

WordPress uses this approach with its wp-config.php file. It’s the file you edit when you first set up and install WordPress where you set your database name, password, prefix, and a number of other settings. You can also set other settings here as well by adding definitions to this file. For example…

define('WP_DEBUG', false);
define('WP_ALLOW_MULTISITE', true);
define('MULTISITE', true);
define('SUBDOMAIN_INSTALL', false);
define('DOMAIN_CURRENT_SITE', 'localhost');
define('PATH_CURRENT_SITE', '/central/');
define('SITE_ID_CURRENT_SITE', 1);
define('BLOG_ID_CURRENT_SITE', 1);
define('WP_POST_REVISIONS', false );

Here you can see there are debug settings, multisite settings, post-revision settings and a number of others. This is a great place for adding values that will never change (or will only need to be changed when pushing from a development environment to production or vice-versa). A lot of times database names and site base URLs with be different from one environment to the next. The great thing about config files is that if you make a change in one place, you make a change everywhere across all of your files.

However, if you wanted to define constants that are only applicable to your theme or plugin, the wp-config.php file is probably not be the best place to do it because if you were to change you theme or plugin those settings would go away. So another option is creating a theme-config.php file and putting it into the root of your theme directory. Then at the very beginning of your functions.php file, include your theme-config file…

include('theme-config.php');

Now you can add your own constants to this file and then use them across all of your theme files. Below is an example of a few constants that I might set my theme config files.

<?php 
define("NBS_THEME_NAME", "9bit Studios");
define("NBS_THEME_PREVIEW", TRUE);
?>

Note: Here again I have prefixed the definitions with “NBS” (for Nine Bit Studios) so that there is no collisions with duplicate constant names.

The first is my “Theme Name”. I actually use this as a string to set menu names and page titles in the theme options of my WordPress. The “theme preview” constant is just a toggle that configures whether or not to show a little preview panel where you can dynamically change font sizes, colors, and other visual display components directly on the page. You see these used a lot in premium themes. All I need to do to remove this when moving the theme to production or shipping it is to set this value to false. Change once, change everywhere.

Then in your code, you can use the constant wherever you like…

My theme name is <?php NBS_THEME_NAME ?>

For a theme preview you’d just have to set the condition in your code…

<?php 
if(NBS_THEME_PREVIEW) {
    // code to show theme preview panel here
}
?>

So here we have essentially used variables for our theme much in the same way when we use WordPress options. However, we haven’t had to write the form to record the option into the admin panel we haven’t had to write the code to go retrieve it from the database. We’ve achieved something that’s functionally the same, but the process is as easy as editing a text file.

What about plugins? Well, the same thing applies there. It’s a fairly straightforward process to create a plugin-config.php file and include it on initializing the plugin. Like with theme-options.php, you can use it to set any value that you want and have it be specific only to the plugin and have it not affect anything else in your WordPress installation if you choose to deactivate it one day down the road.

Should your theme-config.php and plugin-config.php values replace options? No… especially not for items you want your end-user to be able to customize. But they can be a great supplement to options? Absolutely! They can be especially useful for values that you as the developer are interested in handling (i.e. those that not need to be set by an end-user in the theme options or plugin options). They can be great for test and can be great for quick customizations when moving your theme or plugin from development to production. They can be incredibly useful if you so choose to use them.