WordPress Basics: Understanding And Making the Best Use of Your functions.php File

One of the hardest things about teaching is the things that you’re blind to. There are whole things that you know, that are important for others to know, that you just kind of forget to ever explicitly teach.

Case in point: I just realized that in all my writing about WordPress I’d never tackled as fundamental a thing as what “functions.php” is and does, and I think that’s been a mistake. So I hope you’ll let me correct that: we’ll cover what it is, what it does, what it means to you, and consider a few “best practices” I think it’s useful to keep in mind while working with it.

What’s functions.php and Why Do People Always Talk About It?

To start with the basics: Like any other PHP file, functions.php is just a text file, a bunch of characters and spaces that the PHP engine will parse for you on your web server. Things between the <?php and ?> tags (which are the best and worst things in many web developers’ lives) are parsed by the engine, and things outside of them are not.

functions.php wordpressAn example functions.php file

Almost all WordPress themes contain a functions.php file. To check yourself, you can browse your site’s directory structure. You’ll see a screenshot of just one example below:

functions_php_ftpfunctions.php in a WordPress theme

A theme’s functions.php exists to provide the theme with useful PHP functions. Functions are just small bits of work that someone may want to regularly use in the theme’s other files, so packages up into units called functions. (For more about the very basic conceptual underpinnings of a PHP function, I tackled that over on the Press Up blog a while back.)

Providing useful PHP functions is why functions.php is one of the standard features of WordPress themes, and the reason that WordPress came to depend on it. Today, thought, it does have one other purpose, and that’s to tell WordPress about some of the more advanced features that a theme can do. But before I get ahead of myself, let’s cover how WordPress works with the functions.php file in a theme.

What WordPress Does With A Theme’s functions.php File, and Why It Matters

Essentially, WordPress expects that today themes will include a functions.php file. Nothing catastrophic happens if it’s not there—WordPress is nicely durable in that way—but WordPress has come it expect it, and behaves in a special way with that file.

Specifically: WordPress understands that your theme’s files may rely on functions in functions.php. For that to work, that means your functions.php needs to be loaded by the PHP engine before your pages in the template hierarchy. You could include a bunch of PHP files manually at the top of each file in your template hierarchy, but because of the way WordPress works, you don’t have to. That’s what functions.php is for.

Creating Globally Available Functions

The autoloading of functions.php means that its functions are available to you anywhere in your theme, and that it’s a great place to put WordPress function calls that should always run.

This “autoloading” of functions.php has a few other benefits. First, it means that your function definitions there will be available to you anywhere in your theme. More interesting and important, it means that functions.php is a great place to put WordPress function calls that should always run.

So functions.php is where you’ll want to do things like register_sidebar or add_image_size that fundamentally change the core of WordPress when they’ve been called by a theme or plugin. (The list is a lot longer than those two.)

Loading Globally Needed Resources

functions.php is where you register globally needed JavaScript scripts and CSS stylesheets.

functions.php is also where you call on resources that you’ll need across the site. This means, most prominently, custom CSS stylesheets and (visual/presentational) JavaScript scripts—which you load by enqueue-ing them.

For those keeping track at home, the file in a plugin that WordPress similarly “autoloads” is determined by which one has the plugin header. This similarity of behavior and loading between plugins and a theme’s functions.php underlines how similarly the two different things behave in WordPress. And it’s also the reason people will sometime’s refer to your theme’s functions.php as the “theme’s plugin.”

Some Advice About Your WordPress Theme’s functions.php File

I’ve got an array of thoughts and opinions about these basic facts unlocked by your theme’s functions.php files. Here they are, in no particular order:

  • Limit the amount of functionality you put into functions.php (and any included files). This is mostly a point about “theme creep”—which I’ve further defined and gave some advice about mitigating. In summary, display-related functions are a good thing to have in themes, useful business-of-the-site functionality is not. Put that in a standalone plugin instead.
  • A child theme’s functions.php doesn’t override its parent. Unlike all other files in a child theme—which we recommend—yours is simply additive. It actually executes before the parent theme’s functions.php, meaning that if the parent theme authors haven’t been careful (see function_exists), trying to overwrite a parent theme function will simply lead to a “duplicate function name” PHP error and break the site. The additiveness of a child theme’s functions.php is mostly for the sanity of all parties, and is largely a good thing, but it’s important to remember because it’s so different from the way most child theme files behave.
  • Treat the file(s) that contain functionality with care. One of the hardest but subtlest elements of being a good programmer is impeccable skill with naming things logicallly and placing them in their obvious places. Think clearly about what you’re putting in functions.php, why it’s going there, and what guide some future seeker will have toward finding what he or she needs there. So many people treats functions.php as an awesome dumping ground for all the 1337 hacks they’ve found on the internet, and only realize a few years later how much pain that can eventually cause.
  • Keep it small. For your sanity, that of any other developer on your team, and of any future developer who inherits your functions.php file: if your functions.php is over about 150 lines, break it into smaller files with clearer names. A basic PHP include() or require() works fine in functions.php and that coupled with well-named files the functionality is moved to can make a world of difference.

There’s plenty more opinion I could offer, but I don’t want to go to far into personal preference in an introductory tutorial. What’s important is that you know that a theme’s functions.php is the venue for its small and useful reusable units of work. And I hope you also know why people talk about functions.php a lot, and why it matters.


9 Responses

Comments

  • Dez says:

    One additional thing to add to your advice section is to make sure that there are no empty lines outside of opening and closing php tags.

    I just ran into this on one of the sites I manage. I had put an extra space between a closing and opening php call and the RSS feed ended up erroring out because of an empty line at the top of the xml file.

  • I couldn’t agree more about your point about using functions.php only for theme or display related functionality – i.e. only use it for code related to the theme.

    If you put other functionality inside functions.php then when the theme is changed at some later date (as inevitably they are) then the site will break and lose functionality until all the additional code that was in the old theme’s functions.php is copied across.

    Far better to place this additional functionality inside a custom plugin folder in the plugins folder – that way, functionality persists across theme changes.

Pingbacks