Understanding the functions.php file in WordPress

If you’re just getting started with WordPress, there’s likely a lot of new terminology being thrown at you. Beyond fundamentals like “themes” and “plugins”, you’re probably seeing “actions”, “filters”, and a ton of code snippets with instructions like “just add this snippet to your functions.php file.”

Let’s take a step back and look at WordPress’ functions.php file; what it is, where it lives, and how it works. Once we understand those points, we’ll learn how to add snippets to our WordPress sites without having them accidentally overwritten.

Dissecting the functions.php file

When a blog post tells you to “add this to your functions.php file”, they’re usually referring to one of the few required files for every WordPress theme. By default, this file will live at wp-content/themes/{your theme}/functions.php, and serves as the primary location for any custom functionality within your theme.

The functions.php file is a PHP file that’s automatically loaded on every request (when the theme is active). Unlike most other theme files, functions.php isn’t meant to be a “template” (such as header.php, index.php, and any other filenames in the WordPress template hierarchy), but rather the place where custom theme functionality is defined.

This file can also be treated as “mission control” for a theme — it’s not uncommon to see a functions.php file made up of a bunch of require_once statements. This practice helps keep code organized, but the functions.php file still acts as the lynchpin that holds it all together.

Editing an off-the-shelf theme

If you’re using an off-the-shelf WordPress theme (e.g. one you’ve downloaded from WordPress.org or any other sources that may provide updates in the future), you’ll want to avoid editing the functions.php file within the theme, as any updates released to the theme will overwrite the changes you’ve made!

To get around this, we can take advantage of WordPress child themes — themes that inherit everything from their parent unless you specify otherwise. A child theme has its own functions.php file that you may edit to your heart’s content, as WordPress will also load the parent theme’s functions.php.

At a very high-level, a child theme will require two files: style.css (which controls the theme’s meta information) and functions.php. These files will live in a subdirectory of wp-content/themes/, such as wp-content/themes/my-child-theme/.

The style.css file will look something like this, which we’ll break down shortly:

There are plenty of other parameters that you can provide, but we’ll focus on the following four:

1. Theme Name: The name of your new child theme. This can be anything you want, but is required.
2. Theme Description: A brief description of your theme. For custom child themes, I’ll often use something like “Child theme with customizations for example.com.”
3. Author: Your name, which helps this stand out as something custom.
4. Template: The slug (directory name) of the parent theme. For example, if you’re writing a child theme on top of “Twenty Fifteen”, this slug would be “twentyfifteen”.

Technically, that’s all you need to create a child theme. Unfortunately, your theme styles might not be loading the way you expect them to, since the style.css file from the parent theme won’t be loaded. If that’s the case, we get to add our first custom snippet into our child theme!

Create a new file at wp-content/themes/my-child-theme/functions.php and add the following snippet:

Remember: functions.php is a PHP file, so it should begin with the opening <?php tag! All together, our new functions.php file will look something like this:

With your child theme in place, you can switch your active theme to your new child theme (via Appearance › Themes) and everything should behave as it did before. Updates to the parent theme will automatically cascade to the child theme, but changes you make within your child theme will persist!

Adding code snippets as plugins

If you’re not keen on the idea of creating a child theme (or your theme doesn’t lend itself well to being a parent), you might also consider creating a custom plugin to hold your custom functionality.

Don’t worry if you’ve never built a plugin before, I’m going to give you a simple template right here:

If you save those contents to a file within wp-content/plugins/ (e.g. wp-content/plugins/my-plugin.php), a new plugin named “My Custom Functionality” will be available on the Plugins screen within WordPress. You may then add any number of snippets to the file, which will be untouched by core, theme, or plugin updates!

The plugin approach also gives you a few added benefits:

1. The custom functionality can be disabled any time you want. This is especially helpful if the snippet is only required for certain times of the year.
2. The plugin can typically be used regardless of your theme. If you have a tendency to change themes often, you can make sure the custom functionality sticks around.
3. If you want to ensure the functionality cannot accidentally be disabled, you may write the plugin as a “must-use” plugin, though this is beyond the scope of this post.

There are also a number of snippet plugins available in the WordPress.org plugin repo, but I would generally advise against this approach; any time you’re executing code that’s been stored in a database, it’s ripe for abuse and security vulnerabilities. If you do use a snippet manager within WordPress, do so at your own risk!