Practical WordPress Development

On Using Helper Files in WordPress

One of the things that I appreciate about certain application development frameworks is their approach to convention over configuration.

By that, I mean that they tend to take the approach of “a place for everything, and everything in its place” rather than setting a ton of variables in a set of different files to tell the core system where everything is located.

In my opinion, WordPress is a little bit of hybrid of this kind of stuff, but I tend to look at it in the direction of modifying configuration files.

After all, we have both `wp-config.php` and we have `functions.php`. Both of these serve their purpose, but `functions.php` can get specifically cluttered as a theme or an application grows.

Introducing Helper Files in WordPress

As far as WordPress configuration goes, messing with `wp-config.php` really isn’t all that bad in comparison to how many lines and/or how many files you have to tweak for certain pieces of software.

Aside from the usual database credentials, there are very few variables even designers and developers may tweak.

Still, it is a file that needs to be edited to I wanted to mention it.

Unfortunately, I’ve found `functions.php` to be a completely different beast. Over time, this file becomes a bit of bit of a wasteland of functions all of which served a purpose at some point in time.

Generally speaking, I think that we – as theme authors – aim to keep the file as lean as possible focusing only on the functions that are needed for our theme; however, as themes or applications grow (and they do), the file begins to collect a variety of functions that are suitable for whichever release.

Then, as is with a lot of refactoring efforts (or lack thereof, really), the file begins to collect a lot of logic that’s no longer needed, or that could be cleaned up to lean out the file for easier maintenance, readability, and performance.

That said, I’m still a fan of the `functions.php` model – but I think that the structure of themes and/or applications that use it heavily can more effectively employ some type of helper files that aim to keep code organized, and to help us define “a place for everything, and everything in its place.”

Core Functions, Specialized Functions, Helpers, and More

For example, in a couple of projects that I’m working on right now, I am only using `functions.php` to define logic related to core WordPress theme functionality. This includes (but isn’t limited to):

  • Post Formats
  • Content Width
  • Automatic Feed Links
  • Navigation Menus
  • Stylesheets and JavaScript sources
  • …and things like that.

But when it comes to other more coherent ideas, I’ve been keeping them in their own files.

Specifically, I define an `includes` directory that may, ahem, include files like this:

  • `class-theme-nav-walker.php`
  • `theme-customizer.php`
  • `helpers.php`

The Navigation Walker class a subclass of the default WordPress Navigation Walker and includes all of the logic necessary to customize WordPress menus within the context of my project.

`theme-customize.php` contains all logic required to integrate the theme customizer into a theme as well as where to define sections, settings, and controls.

And finally, `helpers.php` contains small functions that help to enhance basic theme functionality. For example, some of the function names that I have in the file for Mayer include the following:

  • `mayer_add_post_class_to_single_post`
  • `mayer_is_paginated_post`
  • `mayer_custom_password_form`
  • `mayer_add_more_link_class`
  • ..and so on.

But how do we continue to decide what goes where?

It’s a Matter of Cohesion

One of the concepts that we hear about all of the time in software development is the idea of cohesion. As with most of other things in computing, it’s a big word for a relatively simple idea.

In short, cohesion is about to level of which functions or pieces of code are related to one another. So, to that end, I believe that our file organization should reflect this.

This means that functions that are all related to the, say, Theme Customizer, should belong in `theme-customizer.php`. When it comes to general utility functions, the code belongs in `helpers.php`.

You get the idea.

This goes completely against the typical method of dropping everything in `functions.php` because if every type of function is contained in a single file, then the file has no real identity.

And for the sake of maintenance, readability, and even some performance improvements, I think it’s important to group our functions in a logically consistent way.

Then again, this is nothing new to any given programming paradigm, but it’s something that we fail to practice as much as we preach.


  1. Nate Wright

    As a developer, I strongly agree with the principles behind this post. functions.php is a nightmare to work with when everything has been thrown in there and I much prefer a solid separation of concerns.

    However, as a stock theme author, I worry about discoverability. This is one of WordPress’s greatest strengths, both within its system and within the broader ecosystem. Someone who knows very little about WordPress can learn about the structure of a theme and make minor changes to template files, style.css and functions.php very easily. And when they run into problems, the internet is packed with tutorials, q/a’s and advice on how to find the right template file, where to locate functions, etc.

    Most of the clients of a stock theme are going to be non-developers or novices at best. I worry that by following best practices in terms of organizing the code from a developer’s perspective, I risk abstracting away from the core WordPress setup in a way that makes it more difficult for these non-developers and novices to access and interact with the underlying code. I realize that, to us, tracking code through a simple require_once() call is trivial. But for many people, they won’t know how to run text searches across an entire directory. They’ll just be scanning a template file or functions.php for something they recognize in the output.

    I’m not saying there is a good solution to this problem. I have broken off code before into separate files when I think it’s necessary (or I get too fed up with just functions.php). But I raise this point because I’m genuinely curious to hear what other people think about this trade-off for stock themes. What is a best practice in this case from the client’s perspective?

    • Jason Bradley

      Great thoughts Nate. I wonder if making so of those functions you may think or get feedback on that your users are modifying should be able to be overriden in a child theme. That way you could potential enable your users to customize and also protect them from the things they probably shouldn’t be changing. Just my thoughts :)

    • Tom McFarlin

      However, as a stock theme author, I worry about discoverability.

      I completely get that. This is why I think providing a good file organization scheme, and really clear code comments in addition to DocBlocks is important.

      And when they run into problems, the internet is packed with tutorials, q/a’s and advice on how to find the right template file, where to locate functions, etc.

      Yes! Some of it’s good, some of it’s not. That’s where it starts to get dangerous for beginners (and why I’m a fan of limited resources as it relates to WordPress documentation, but that’s a whole other post for another time).

      What is a best practice in this case from the client’s perspective?

      I think this is a great question – it’s certainly about getting into the mind of those who end up using the code.

      But I’ve no answer :).

      • Nate Wright

        Thanks for the response. And you’re right. Good file organization can help alot.

        I’ve been thinking about “best practice” for this a bit more since you’re post. I’m thinking in the future I’ll keep all functions used in the front-end template files in functions.php, so novice users can find the code powering the most common tweaks (front-end adjustments) in the two locations they’d expect them. But I’ll split off all functions that handle backend features — theme customizer and plugin options, custom post types, admin notices… I figure once all that is out of the functions.php file it ought to be pretty clean, actually. And hopefully the average end-user won’t need to fiddle with that stuff.

      • Ulrich

        _s just has the basic theme setup, widgets and enqueueing of scripts and styles in the functions.php.

        What do you think of using the same folder structure as the WordPress Plugin Boilerplate uses for organising the code?

    • James Huckabone

      I remember when I first started trying to really learn programming, I would rage at any tutorials that were articulated in an exclusive way, abstracted by the overuse of native terms. Thanks for this post.

  2. Jason Bradley

    Im a big fan of breaking up your functions.php file into separate files. It has been easier for me to pinpoint where I may need to make a code change and I feel a lot more comfortable making a change to a smaller file instead of a huge file.

    Another great reason to do this is for writing tests for that code if you are test driving your theme. I haven’t done much test driving with WordPress, but know with other code bases this is essential to eliminate and help you identify cohesion like you mentioned.

  3. Adan Caverly

    Four ranking and seven minutes ago, I just study a lovely material. Lol thanks

Leave a Reply

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑