This article introduces one of the most important topics in WordPress development: functions.php
. The functions file is one of the complex, interesting, and powerful in the arsenal of a WordPress theme.
Key Takeaways:
functions.php
is a specially named PHP file that can be located inside any WordPress theme. WordPress knows to execute the code infunctions.php
during its normal PHP processing.functions.php
‘s job is to add custom functionality to the theme and site. It is composed of PHP functions—small bits of PHP code that add or change functionality across the site.- As
functions.php
is inside the theme, its functionality additions should all be presentational in nature. Examples include:enqueue
ing CSS stylesheets and presentational JavaScript files, enabling featured images, registering custom image sizes, and registering navigation menus and widget areas.
functions.php
is the “brain” of a WordPress theme: it’s where we dictate all kinds of presentational functionality—PHP functions that control how things display, rather than the site’s underlying data—for the theme.
In this functions.php
tutorial, we’ll cover how to work with functions.php
, and some of what it can do for your theme and site.
What functions.php
Is
functions.php
exists to provide useful presentational PHP functions: small bits of work that change how the site displays.
In a WordPress theme, functions.php
exists to provide the theme with useful presentational PHP functions: small bits of work that change how the site displays in defined ways.
KEEPING IT PRESENTATIONAL
Ask yourself: “If I changed themes, would I lose lots of data, or would things just display differently?” It should be the latter for functions inside
functions.php
.
Presentational changes don’t alter the site’s underlying data: things like post content, registered users, custom post types, taxonomies such as tags and categories, or sitewide data like “site title” or “customer discount codes.”
To know whether a function qualifies, ask yourself: “If I changed themes, would I lose data, or would things just display differently?” If you’d lose data, then you’ve strayed from the presentational role of themes.
functions.php
Autoloads, Before the Rest of the Theme
Because
functions.php
autoloads first, its functions are available anywhere in your theme.
functions.php
is a PHP file which WordPress knows to examine as part of its “factory” process. It’ll ignore most file names by default, but it knows to open up an active theme’s functions.php
, see what’s inside, and execute it.
WordPress understands that your theme’s other files may rely on functions in functions.php
. That means the PHP engine needs to load functions.php
before it loads the pages in the template hierarchy.
The autoloading of functions.php
means that its functions are available to you in any of your theme’s PHP files. As a result, it’s the place in your theme to put WordPress function calls that should always run, or be available. This is an incredibly valuable part of WordPress theme development.
Uses of functions.php
Let’s take a look at just a snippet of WPShout’s functions.php
, and see what it’s doing for us:
<?php
// Add theme support for featured images, and add a few custom image sizes
add_theme_support( 'post-thumbnails' );
add_image_size( 'featured-image-large', 640, 294, true );
add_image_size( 'featured-image-small', 200, 129, true );
add_image_size( 'featured-image-tiny', 124, 80, true );
// Enqueue theme JavaScripts and CSS styles
function wpshout_scripts( ) {
// Enqueue JS that gives the search box a default value
wp_enqueue_script(
'search-box-value',
get_stylesheet_directory_uri() . '/js/search-box-value.js',
array( 'jquery' )
);
// Enqueue JS that sets a dynamic page minimum height
wp_enqueue_script(
'page-min-height',
get_stylesheet_directory_uri() . '/js/page-min-height.js',
array( 'jquery' )
);
// Enqueue main theme stylesheet
wp_enqueue_style(
'wpshout-style',
get_stylesheet_uri()
);
}
add_action( 'wp_enqueue_scripts', 'wpshout_scripts' );
// Register main navigation menu
function wpshout_register_menu( ) {
register_nav_menu( 'main-nav', 'Main Nav' );
}
add_action( 'init', 'wpshout_register_menu' );
The remainder of the chapter will look at each piece of the code above.
CREATING GLOBALLY AVAILABLE FUNCTIONS
functions.php
is where to add functions that alter how WordPress runs on all page loads.
functions.php
is where you’ll add functions that alter how WordPress runs on every page load. We’re doing a couple of those in the snippet above:
Adding Featured Image Support and Custom Image Sizes
// Add support for featured images and image sizes
add_theme_support( 'post-thumbnails' );
add_image_size( 'featured-image-large', 640, 294, true );
add_image_size( 'featured-image-small', 200, 129, true );
add_image_size( 'featured-image-tiny', 124, 80, true );
This first block uses a WordPress function called add_theme_support()
to tell WordPress that the theme will be using featured images.
Next, the block uses another WordPress function called add_image_size()
to register three special image sizes we define: featured-image-large
, featured-image-small
, and featured-image-tiny
. Every time we upload a new image to the site, WordPress will now generate resized versions of that image with the dimensions we’ve specified: 640px wide by 294px tall, and so on.
Registering a New Navigation Menu Area
// Register main navigation menu
function wpshout_register_menu( ) {
register_nav_menu( 'main-nav', 'Main Nav' );
}
add_action( 'init', 'wpshout_register_menu' );
This block uses a WordPress function, register_nav_menu()
, to register a new navigation menu. This function call is wrapped in another function which we’ve written: wpshout_register_menu()
. To do the registering, we use the WordPress function add_action()
to hook wpshout_register_menu()
onto a WordPress action hook called init
.
Don’t worry too much about that terminology right now: we’ll explain it in WordPress Hooks, Actions, and Filters: What They Do and How They Work. What it means is that wpshout_register_menu()
will now run every time WordPress runs its init
process—which WordPress does near the beginning of every webpage load.
So we’re able to make wpshout_register_menu()
run toward the beginning of every webpage load. And what does wpshout_register_menu()
do? It uses register_nav_menu()
to register—cause WordPress to know about—a new navigation menu area titled “Main Nav.”
LOADING GLOBALLY NEEDED RESOURCES
functions.php
is where you register globally needed JavaScript files and CSS stylesheets.
In WordPress, functions.php
is also where you load in resources that you’ll need across the site. This means, most prominently, custom CSS stylesheets and JavaScript files—which you load by enqueue
-ing them.
// Scripts and styles
add_action( 'wp_enqueue_scripts', 'wpshout_scripts' );
function wpshout_scripts( ) {
// JS that gives the search box a default value
wp_enqueue_script(
'search-box-value',
get_stylesheet_directory_uri() . '/js/search-box-value.js',
array( 'jquery' )
);
// JS that sets a dynamic page minimum height
wp_enqueue_script(
'page-min-height',
get_stylesheet_directory_uri() . '/js/page-min-height.js',
array( 'jquery' )
);
// Load main stylesheet
wp_enqueue_style(
'wpshout-style',
get_stylesheet_uri()
);
}
Again, this block looks complicated if you don’t understand WordPress hooks and the wp_enqueue_()
functions, but it boils down to the following statement: “On every page, we want to load the files search-box-value.js
, page-min-height.js
, and the theme’s own style.css
,” plus instructions for how to find those files.
With this code in place, when you load a webpage on the site, all three of those files load right along with it, and their functionality will change how the webpage looks and acts.
Now You Get the Fundamentals of functions.php
We’ve covered the core principles of how functions.php
works within WordPress theme development. If you just got hit with a lot of PHP functions you didn’t understand, don’t worry: that’s exactly where we’re headed! The key point is that functions.php
adds presentational functionality of all kinds to your theme, and you now understand how.