Tips for Writing Maintainable WordPress Themes: Tools

By Tom McFarlin

Throughout this series, we’ve been talking about a number of practices that we can employ in our WordPress theme development that will help not only provide a consistent foundation off of which we can build our existing and future projects, but that will also help us maintain them after they’re released.

Up to this point, we’ve covered:

  1. Directories
  2. Naming Conventions

Before diving into this article, I recommend reading the first two so that you can get a feel for the perspective that we’re taking when looking at theme development. In addition to those points, there are also a number of tools that I think should be installed in order to help make sure that we’re writing the best code possible.

Of course, this is not only in addition to the tips previously mentioned, but applying the WordPress Coding Standards, as well.

In this final article, I’ll be talking about several different settings and plugins that I think should be defined and/or installed in every WordPress development environment to make sure that you’re using the most up-to-date APIs, that you’re not negatively impacting performance, and that you’re not causing any notices, warnings, or errors to be thrown via PHP.


Before we jump into talking about various plugins that are available, there are a number of settings that I highly recommend setting on your web server and in your WordPress environment.

Some of these settings will contribute to the functionality of plugins that we’ll be taking a look at later in this article, others are going to provide functionality that will help warn us when we’re making mistakes in PHP and/or in our WordPress-specific code.

Web Server Settings

Although not everyone works with Apache, PHP, and MySQL, it’s still arguably the most common configuration that is used when working with WordPress. One of the things that I always recommend developers do in this environment is to make sure that they’ve configured PHP to log everything to a log file on their machine.

That is, when given the options to log:

  • startup errors
  • errors
  • warnings
  • notices
  • all other errors and warnings

Make sure, that you check everything. If you use a tool such as MAMP, XAMPP, or WAMP then this is usually very easy to do via the user interface; however, if you’re not sure where to configure these options, then you can always set them within php.ini using the notes that are outlined in the PHP manual.

Keeping track of errors that are logged that may not be displayed on the screen (although we’re going to do what we can to make sure that we do see them on the screen later in this article) is essential in making sure that you’re writing code that catches any potential problems with the code.

Granted, this should be able to be done when using other web servers – after all, this is really just a PHP configuration setting – but I currently don’t use many of the other options that are available so I wanted to be explicit about the environment in which I configure my settings.


WP_DEBUG is a constant that you can set within your WordPress wp-config.php file. Most installations will have this set to false, by default. If yours is already set to true, then it means that someone has already done it or that you have a copy of WordPress with settings that are not shipped by default from WordPress.org.

Anyway, in the configuration file look for the constant and if it’s set to false, then set it to true. If it’s not found, then add the line. Ultimately, this is what your functions.php file should contain (in addition to the other code that was already there):

define( 'WP_DEBUG', true );

In short, this particular constant will make sure that PHP notices are written out to the display as well as WordPress-specific debug messages. This is really useful whenever you’re working on a theme and you try to check, say, an empty index of an array or you end up using a function that’s no longer support by the current version of WordPress.

There’s also a fantastic plugin related to this very technique that we’ll cover later in this article.

Also, there are also two more constants that you can define that will give even more information that what this one will. You can read the corresponding Codex article for more information but, in short, the constants and their definitions are as follows:


WP_DEBUG_DISPLAY is another companion to WP_DEBUG that controls whether debug messages are shown inside the HTML of pages or not. The default is ‘true’ which shows errors and warnings as they are generated. Setting this to false will hide all errors. This should be used in conjunction with WP_DEBUG_LOG so that errors can be reviewed later.

Out of the box, WordPress will display all errors, warnings, and notices within the context of a page. If you want to continue debug WordPress but want to prevent the information from being rendered to the page and only written to a log file, then you can set this constant to false.

Personally, I’m a not a fan of keeping things hidden as I like to see problems as soon as they crop up (read: as soon as I’ve generated them), but everyone has different workflows. To that end, if seeing the messages on the pages conflicts with your development style, then define this constant appropriately along with WP_DEBUG_LOG.


WP_DEBUG_LOG is a companion to WP_DEBUG that causes all errors to also be saved to a debug.log log file inside the /wp-content/ directory. This is useful if you want to review all notices later or need to view notices generated off-screen (e.g. during an AJAX request or wp-cron run).

This is a useful constant to define if you’re big on monitoring your error logs (which most developers should be). In addition to the log generated by PHP, this is yet another file that can provide insight on as to what a given problem may be and where it is happening whenever you’re working on a theme.


This constant is another one that will come in handy with some of the plugins that we’re going to be looking at later in this article; however, it’s worth setting in functions.php even if you don’t have additional plugins installed.

First, like the WP_DEBUG constant above, you can add this to functions.php. It should look like this:

define( 'SAVEQUERIES', true );

Looks good, sure, but what does it actually do? SAVEQUERIES instructs WordPress to keep track of two things:

  1. All of the queries that are executed
  2. How long it took to run each query

This interfaces directly with $wpdb which is the WordPress database class. As mentioned earlier, there’s another plugin that works directly with this particular constant such that you can see all of the queries from within WordPress; however, if you’d rather forgo using a plugin to help render the information, simply define this constant, and then print the result of $wpdb->queries to your output format of choice.


In addition to setting constants, there are a number of powerful plugins that I think should be installed in each developer’s WordPress installation that can provide even more help when used with the settings above.

Though many of you will have plugins to add to this list and others will have opinions about each of these plugins, these are the ones that I have found to be most useful in my development efforts.

Debug Bar

Debug Bar introduces an option in the admin bar of your WordPress installation that gives information about queries, the cache, and other information.

This plugin is best used with WP_DEBUG and SAVEQUERIES enabled. Note that this plugin is also required for a number of the plugins that I’m listing after this one. That is, it has a number of extensions that make it even more powerful.

Debug Bar Actions and Filters Addon

This plugin introduces two more tabs within the Debug Bar that allows you to see all of the actions and the filters (that is, all of the hooks) that are executed on the current page request.

This is exceptionally helpful if you’re building a complex theme or if you’ve inherited a codebase from someone else and you’re trying to find why certain things are happening that may not be easy to find because of the way the theme is built.

Debug Bar Console

Unfortunately, this particular plugin hasn’t been updated in a couple of years so I don’t know how long it will continue to work with WordPress (unless someone adopts it for development), but it works in conjunction with Debug Bar to give you the ability to to execute PHP and MySQL directly from within WordPress.

This is very helpful when trying to figure out why, say, a function in your theme isn’t performing like it should be. That is, you’re able to write a function directly within the console, execute it, and see the result without having to constantly hop back into your IDE, change the function, refresh, and check the result.

Debug Bar List Script and Style Dependencies

If you’re working with a theme that uses a lot of styles and a lot of JavaScript files especially those that depend on other stylesheets and other JavaScript files, then it’s helpful to know the order in which they are being loaded and how they should be loaded.

That’s where this Debug Bar addon comes into play.

It allows us to visualize the order in which scripts and styles are loaded and executed so that we can make the necessary changes to ensure that all dependencies are loaded in the way that they should be for our theme to work properly.

Debug Bar Post Types

If your theme introduces custom post types into the dashboard, then odds are you’ve had to work with a variety of different properties, rewrite rules, and more.

It can get complex really fast depending on how much you decide to tweak the features of the custom post type.

This plugin adds yet another panel to Debug Bar such that you can easily see the properties for each post type. It doesn’t allow for modification or editing on the fly (as that can be done in the Debug Bar Console or it can be done by simply editing your custom post type definition), but it does provide a much cleaner format than a giant array in the screen of an IDE.

Log Deprecated Notices

This is a simple plugin that will log the use of old files, function, arguments, and so on to a file. Specifically, when you’re writing a theme, this plugin will notify when you’re running something that is not 100% compatible with the current version of WordPress.

For those who want to make sure they are future-proofing their work and who are staying up to date with the latest APIs, I highly recommend this plugin.

WordPress Plugin Performance Profiler

One of the largest misconceptions about WordPress is that running a lot of plugins causes your site to load slowly or that a lot of plugins causes bloat. That isn’t true. It’s poorly-written plugins that do that. Those that follow WordPress best practices and the coding standards should have minimal impact on load time.

With that said, this plugin will identify exactly which plugins are impacting performance the most. Sure, this can be useful when you’re trying to narrow down the reason a site is performing slowly, but it’s also useful to execute against your own code to ensure that you’re not negatively affecting the site’s performance.

Rewrite Rules Inspector

For anyone who has done extensive work with custom post types, custom routes or URLs, or who have had to venture into the Rewrite API, you know the challenges that exist.

This plugin help to give a visual representation of the rewrite rules for your installation. It’s useful for inspecting rules that exist within the current theme, but also useful for helping to debug when you’re trying to define a custom scheme and are having a difficult time nailing the regular expression to do so.

RTL Tester

If you’re looking to market your plugin to the widest audience possible, then you’re going to want to test how it looks in languages that read from left-to-right and right-to-left, as well.

That is, if you want to make sure that you’ve properly internationalized your theme, then this plugin will let you see what your work looks like for internationalized languages.

If you’re looking to sell your theme, say, on WordPress.com, then this is a must-have.

Theme Check

If you’re looking to make sure that your theme is up-to-date with the current WordPress Theme Review guidelines, then Theme Check is a non-negotiable.

It will perform an automated audit of your theme and will make sure that all of your code is up to par with the current guidelines. If not, it will show you a clean read-out of the problems and links to the guideline that you’re not following. It also provides suggestions on things that you should have implemented.

Note that most (if not all) of these are freely available from within the WordPress Plugin Repository so they can be installed directly from WordPress itself.


As I’ve stated in previous articles, many of the things that I’ve shared throughout this series are a bit subjective or may not work in your current environment. Although the practices and tools that I’ve shared have been tried and proven throughout my own personal experience in working with WordPress for several years, I also recognize that we don’t all use the same toolset.

As such, this means that some of the configuration, organization, and settings may vary for you. That’s okay. Ultimately, the point is that we, as theme developers, need do a better job of writing maintainable themes because we spend so much time working on them after their initial release.

Perhaps some of the things suggested throughout this series will help you do just that. Perhaps you’ll need to tweak some of the suggestions to match the tools that you use. Whatever the case may be, I hope that it’s not only been a useful series with some practical tips to help in your ongoing theme development, but that it’s also sparked an interest in setting a foundation for how you organize and structure your projects moving forward.

As usual, please feel free to keep the discussion going with comments, questions, and any other general feedback in the comment thread below.

Source: Nettuts+

I've worked very hard for this, so please help me by donating a cup of coffee. Thanks in advance.

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *