Home.php is Where the Heart Is: A Guide to WordPress File Path Functions
By Ryan Parlee
File paths can be confusing in WordPress. (To learn more about WordPress check out this blog.) Especially because there are nearly two dozen different functions designed to generate dynamic paths in your code. Some of them are relative, others are static. Some echo by default, others just return the value.
Understanding the nuances of when to use which function can make your development a little easier, and less error prone. So, we’ve created this list of WordPress file path functions to help you traverse file paths through WordPress like a pro.
Help with WordPress file paths
Note: Unless stated otherwise, all of the functions below return their values, so you will need to echo them out manually. They also return without a trailing slash, if not stated. This means you will need to add the slash manually.
bloginfo('stylesheet_url')
This will return the actual stylesheet for a theme. It should be used when calling the main stylesheet in header.php
get_template_part
This function is a more solid alternative to using straight include statements in your theme. The function consists of two parameters, the base file name, and the slug. If you were going to include a file called sidebar.php, your code would look like this:
get_template_part( ‘sidebar’ );
Alternatively, let’s say you were including a file called sidebar-blog.php. Your code would be:
get_template_part( ‘sidebar’, ‘blog’ );
The great thing about this function is that if sidebar-blog.php doesn’t exist, or is deleted, the function will default to sidebar.php. The reason this works is that the function works on a highest priority to lowest priority system. It will actually look for the file (with or without the appended slug) in a child theme first, then work its way up the stack to the parent theme.
locate_template
The get_template_part function inherits from locate_template, which can be used to see if a file exists before trying to call it. One of the function’s parameters can actually load the file immediately if found, but it is set to false by default.
The first parameter in the function is either the single filename to find (as a string), or an array of files to locate. An array of files works on the same priority list as get_template_part (ie: if one of them is found, locate_template returns as true).
get_stylesheet_directory
The get_stylesheet_directory function will return a full path (not a URL) to the current theme folder. The thing to watch out for with this function, is that it will return the child theme directory if you are using a child theme. This function is mainly for calling PHP files that live in the same folder as (or a relative folder to) the style sheet.
get_stylesheet_directory_uri
Same as the get_stylesheet_directory, except that it returns a url string (including http://). This should be used to call files with a proper url string (images and stylesheets basically).
get_template_directory
Like get_stylesheet_directory, get_template_directory returns a full file path, not a URL. The difference is that this function returns the parent theme, even when using a child theme. This is really useful for files that the child theme won’t be touching and great for PHP files
get_template_directory_uri
This one works just like get_template_directory, except that it returns a URL string. Use this function for stylesheets and images.
plugin_dir_path
When working with plugins instead of themes, plugin_dir_path should be used. The tricky thing with this function is that you have to pass __FILE__ into its parameter list to get the correct result (e.g., plugin_dir_path( __FILE__ ) ). This function does return a trailing slash, so adding one is not necessary
plugin_dir_url
This function does the same as plugin_dir_path and requires the same __FILE__ parameter. The different is that it returns a URL instead of a path. A trailing slash is also provided, so adding one manually is not necessary.
site_url
The site_url function returns the core site url (ex: http://example.com), based on what is defined in general settings in the WordPress dashboard. There are two accepted parameters. The first is a string to append to the url, and the second is the scheme. You can force http://, https://, and others. For a full look, see the codex page.
home_url
This function does the same as site_url, but does not use the address found in the dashboard settings panel. For networked WordPress installations, use network_home_url instead.
theme_url and plugin_url
These functions return the full theme and plugin folder respectively (as opposed to a specific theme or plugin). This is useful for pulling in asset files from other themes and plugins (this wouldn’t really be recommended unless you were working in a parent/child theme relationship). As with site_url and home_url, you can pass a path to append to the returned url.
Wrap Up
As you can see, working with files in WordPress can be complicated, but the number of functions listed above should also give you confidence in loading any file local to your WordPress installation using WordPress-approved methods. Each function above can also be found in the WordPress codex.
Top image via Flickr user Nikos Koutoulas.
