The Ultimate Guide to the WordPress functions.php File
If you’ve started building your own theme, or maybe even creating a child theme to customize another theme, then you’ll have learned all about template files and the theme template hierarchy. But what about the theme functions.php file?
The functions file is where you put all of the functionality your theme needs that doesn’t relate just to one template, so it isn’t code that outputs just one type of content or content in just one place in the page such as the sidebar or footer.
The WordPress Codex defines the functions file like this:
The functions file behaves like a WordPress Plugin, adding features and functionality to a WordPress site. You can use it to call functions, both PHP and built-in WordPress, and to define your own functions. You can produce the same results by adding code to a WordPress Plugin or through the WordPress Theme functions file.
It’s important to note the similarity between the functions file and a plugin file. You use the functions file for the same kind of code you would add to a plugin; indeed if you wanted to, you could have a huge functions file and no plugins in your site at all.
But that wouldn’t be a very good idea.
If you have a lot of functional code you need to use in your site, or you want that code to still work if you change themes, then you should put that in a plugin. But if that code is theme-dependant, then functions.php is the right place to put it. The general rule is:
Use functions.php when you need to add simple functionality related to the way your content is displayed (i.e. it won’t work without your theme activated). This might include adding extra fonts, for example.
Write a plugin when the functionality is more complex or when the extra functionality isn’t dependent on the theme. An example is registering post types – you don’t want to lose your post types if you change themes in the future.
In this post, I’ll take you through some of the uses of functions.php, and show you how to add code to it and how to activate that code. I’ll also show you how to use functions.php in a child theme to override or add functionality to a parent theme.
We’ll cover:
Common Uses for the Functions File
Adding Code to the Functions File and Activating It
Creating a Functions File
Adding Commonly Used Code to functions.php
Adding Theme Support
Adding a Translation File
Registering Navigation Menus
Pulling it All Together
Including Files
Working with Parent and Child Themes
Pluggable Functions
Deactivating Functions
Using Function Priority
The Functions File is Your Friend
Common Uses for the Functions File
Bearing in mind that the functions file is for code that’s theme-dependent (i.e. that will be lost if you switch themes), there are some specific examples when adding code to it is particularly useful. These include:
Adding theme support, for example for featured images, post formats and RSS links
Telling WordPress where the theme’s translation file is
Registering locations for navigation menus, so that users can add menus via the menus admin screen
Adding, removing or overriding functionality from a parent theme, using a child theme.
In this post, I’ll show you how to do each these things.
Adding Code to the Functions File and Activating It
You add code to the functions file and tell WordPress to activate it in exactly the same way as you would with a plugin. Methods include:
Writing a function which you then call in your theme template files – this is useful when you have a block of code you want to use in multiple places on your theme but it won’t work in a template part.
Hooking your function to an action or filter hook. This runs the function when WordPress encounters that hook. WordPress itself provides hundreds of hooks, and you might also find some in your theme and plugins that you can use. Remember, if you’re writing something in functions.php that you want to activate via a hook in a theme you’ve bought or downloaded from the WordPress plugin directory, then you’ll need to create a child theme to do that. If you don’t your functions file will be overwritten next time you update the theme.
Creating a shortcode that you then add to your content. I wouldn’t recommend adding a shortcode via the functions file – it’s better to do it using a plugin, so that the content output by that shortcode isn’t lost if you switch themes in future., It also means you can use that plugin on other sites, giving you access to your shortcode again and again.
Creating a widget. It’s bad practice to do this in the functions file; if you want to build a widget, create a plugin for it.
You can find out how to do each of these in our guide to creating a plugin.
So let’s look at how you work with functions.php, and how you add some of the most common functionality to it.
Creating a Functions File
If your theme doesn’t already have a functions file, you’ll need to create one. Create a new file in the theme’s main directory and call it functions.php.
You’ll have to add an opening PHP tag to the file but you don’t need a closing one:
Your functions file is now ready for you to add your code. I tend to add large blocks of commented out text before each section, so I can easily find my code again. Something like this:
That way, when I’m scanning my file, I can easily find each block of code.
Adding Commonly Used Code to functions.php
Let’s take a look at some of the most common uses for the functions file, and how to code them.
Adding Theme Support
There are certain features in WordPress that you must add theme support for for your theme to be able to take advantage of them. These are:
Post formats – tumblr-like formats such as standard, video, quote and aside
Post thumbnails – also known as featured images. If you want to display these in your theme you’ll also have to add the code to output them to your template files, but they won’t be available in the admin screens unless you add theme support for them
A custom background – lets you (or others using your theme) customize the background image and colors via the customizer
A custom header – which works in a similar way to the custom background
Automatic feed links – for RSS feeds
HTML5 – for search forms, comments, gallery etc. This doesn’t affect your ability to code your theme using HTML5, but relates to code generated by WordPress
Title tag – this lets you add a title tag in the <head> of your pages for SEO and accessibility purposes. You won’t need this if you’ve got an SEO plugin doing this for you
So to add theme support for post formats, for example, you use the add_theme_support() function in your functions file:
Some of the features you add theme support for have additional parameters; for example, you can specify the post formats you want to use when adding support for them:
And for featured images, you can specify which post types you want to add support for them to:
But none of this will work unless you place your code inside a function that you then attach to the correct hook, which is the after_setup_theme action hook. You can add all of your add_theme_support() functions inside one larger function that you then hook to after_setup_theme. So if you want to add theme support for post thumbnails, post formats, HTML5 and automatic feed links, you add this to your functions file:
Note that I’ve added commented out text above each item that I’ve added theme support for, so if I or anyone else comes back to the file later on, it will be easy to see what’s going on.
Adding a Translation File
If people who don’t speak your language are likely to be working on your site or using your theme, it’s good practice to make your theme translation-ready. This doesn’t affect the front end of your site that visitors see, but the admin screens that your users will see. Translation means that any text you add to the admin screens via your theme will be translated using a translation file.
You tell WordPress where the theme’s translation file using the load_theme_textdomain() function in your functions file, like so:
This uses the get_template_directory() function to find the theme’s directory, and then looks for a file beginning with wpmu-theme in the languages subdirectory, so the path will be wp-content/themes/mytheme/languages/and the filename of the languages file will start with wpmu-theme followed by a code for the language.
If you do need to make your theme translation-ready you’ll have to do more than just load this text domain – our comprehensive guide to translating plugins also applies to themes and tells you everything you need to know.
Registering Navigation Menus
Something else you do in your functions file is register locations for navigation menus. If you’re used to working with third party themes, you’ll have seen that many of them have a Primary Navigation checkbox you can select in the Menus admin screen, letting you add the menu you create to that location in the theme. If you want users to be able to do this in your theme, then you’ll need to use the register nav menus() function:
This registers one menu location, which will de shown in the admin screen as Primary Navigation, and whose ID is primary. You then use that ID to output the menu in your theme’s header.php file.
Note that I’ve made the name of my menu translation-ready in the code above, so anyone using my theme who is working in a language other than English will have that “Primary Navigation” text translated for them using my translation file.
You can also use this function to register multiple navigation menu locations. The code below registers a primary menu, plus an additional one in the sidebar:
Again, you’d need to code the menu into your theme’s sidebar.php file, using the wp_nav_menu() function.
Pulling it All Together
The eagle-eyed among you will have spotted that all of the functions I’ve provided above are activated via the same action hook: after_setup_theme. This means that instead of writing a number of separate functions, you can add them all to one function in your functions.php file and then activate that using the action hook.
You would them have one big function:
I’ve added plenty of comments inside my function so I know what’s happening where. This will make it easier if I need to edit or override the function in future.
Including Files
Sometimes you’ll find your functions file gets larger than you can comfortably manage, and has blocks of code that you’d like to keep separately. If this happens, it’s a good idea to create separate files, called include files, for that code, and then call them from your functions file.
Create a folder in your theme called includes and then create a new php file for each block of code you want to separate out. So if I wanted to move theme setup to another file, for example, I move all of the code above into a file called theme_setup.php and then call it in my functions file:
This calls the code in the include file and runs it at the place in the functions file where I’ve added that include() function. I tend to put all of my includes at the beginning of the functions file so they’re easy for me to find, again with comments to tell me what they do.
Working with Parent and Child Themes
The functions file can be very powerful when you’re working with parent and child themes. In a child theme, you can use your functions file to override or remove functions from the parent theme or to add new ones of your own.
There are three ways to override or add functions in a child theme:
Create a new version of a pluggable function.
Deactivate a function from the parent theme.
Add your own function, using priority to override the parent theme’s function.
Let’s take a quick look at each of these in turn.
Pluggable Functions
If you’re working with a well-coded parent theme or a theme framework that’s designed to be used as a parent theme, then the chances are the functions in its functions file will be pluggable.
You can easily spot a pluggable theme, because it will be wrapped in a conditional tag to check if that function already exists, like this:
Because functions from the child theme run before those from the parent theme, this means that if you create a function with the same name in your child theme, then WordPress won’t run the one from the parent theme. So to override the parent theme, just create your own function with the same name in your child theme’s functions file.
Deactivating Functions
To deactivate a function, you unhook it from the action or filter hook it’s attached to. So if your parent theme has a function called parent_function() which is activated via the init hook, you deactivate it in your child theme like so:
This will mean that the parent function won’t run anymore. You can then write a new function if you want different functionality in your child theme – attach it to the same hook but don’t give it the same name.
Note: If the parent function has a priority parameter in the add_action() function that runs the function you want to deactivate, you must include that same priority when you’re deactivating it. I’ll come to priorities in the next section.
Using Function Priority
The final option is to create a new function with a higher priority than the function you want to override, meaning it will run after that function. You have to do this because by default WordPress will run functions from your child theme first; only by adding a priority number can you alter this.
So let’s say your parent theme has a function called parent_function(), which is activated via the init hook with priority 20:
You could write a function which overrides it and then attach that to the init hook with a higher priority, such as 30:
Note that if the parent function hasn’t had a priority assigned, then it will use the default which is 10. So you can use anything higher than 10 for your child function to make sure it runs after the parent function.
The Functions File is Your Friend
The theme functions file works in a very similar way to a plugin, but it’s specific to your theme. So you should only use it to add functionality that you don’t want to lose if you switch themes later on, or that you don’t want to use on a another site. In this post you’ve learned what the functions file is used for as well as how to implement some of those uses. Treat your functions file with care, avoid using it instead of a plugin, and it will help you with your theme development!