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.
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
?> 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.
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 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.phpmeans 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.
functions.php is where you’ll want to do things like
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
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
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
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.phpis 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.phpas 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.phpfile: if your
functions.phpis over about 150 lines, break it into smaller files with clearer names. A basic PHP
require()works fine in
functions.phpand 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.