The most important URL and file path functions for WordPress theme developers at a glance

As a beginner in WordPress theme development, the various functions for returning the theme folder URL or the file path can be a bit confusing at the beginning. In this post I would therefore like to give an overview of the various URL and path functions in WordPress and their use.

Difference between url and path

In WordPress there are functions for returning the absolute path to the theme folder as well as functions for outputting the theme folder URL . Both types are important for theme developers.

The absolute path can be thought of as the local storage location of the theme files on the web server (e.g. / home / user / public_html / wp-content / themes /). This is required, for example, to load PHP files in the theme and execute them internally on the server.

JavaScript, CSS and image files are usually integrated with the URL (e.g. https://domain.com/wp-content/themes/) instead of using an internal path. The reason: The files are not processed on the server like PHP files, but are loaded from the outside of the browser and used by it.

WordPress URL and path functions at a glance

WordPress has four standard functions for returning the theme URL or the theme path, which have been in the core since time immemorial (version 1.5).

get_stylesheet_directory and get_stylesheet_directory_uri

The two get_stylesheet_directory functions return the path / URL of the currently activated theme of the WordPress installation. If a child theme is used, these functions refer to the folder of the child theme .

get_stylesheet_directory ()
absolute path to the child theme folder
e.g. / home / user / public_html / wp-content / themes / child-theme

get_stylesheet_directory_uri ()
URL to the child theme folder
e.g. https://domain.com/wp-content/themes/ child-theme

get_template_directory and get_template_directory_uri

The two get_template_directory functions, however, always refer to the parent theme .

get_template_directory ()
absolute path to the parent theme folder
e.g. / home / user / public_html / wp-content / themes / parent-theme

get_template_directory_uri ()
URL to the parent theme folder
e.g. https://domain.com/wp-content/themes/ parent-theme

Note: The WordPress documentation sometimes also mentions stylesheet directory and template directory. The former refers to the child theme folder due to its functions, the latter the parent theme folder.

Common problem: Using a child theme

Without a child theme, all four functions refer to the same folder - that of the current theme. There are therefore no errors, regardless of whether get_template_directory or get_stylesheet_directory or their URL functions are used.

Often it only becomes problematic when a child theme is activated.

Then the correct functions must be used to load the files. If the wrong function is used, the wrong theme folder may be used, in which the files do not exist.

Application of the functions in the WordPress theme

When which function is used depends on the situation. In the following I would like to show the typical use cases.

Loading PHP files

The functions of a WordPress theme are located in functions.php . Most themes are a bit more extensive and divide functions into several files for better clarity.

Therefore, in many themes, additional files are loaded at the end of functions.php .

 require get_template_directory() . '/inc/template-tags.php'; require get_template_directory() . '/inc/customizer.php';

For loading PHP files we need the absolute path, not the URL.

We therefore get the correct integration of the files from the (parent) theme folder with get_template_directory () . This means that the files can still be included when users create a child theme. The function continues to search for the file in the parent theme.

If you have created a child theme and created a new PHP file there that should be loaded, you have to use get_stylesheet_directory () to return the path of the child theme folder.

 require get_stylesheet_directory() . '/child-theme-options.php';

Incidentally, it does not matter whether the functions are used in the child or parent theme. The difference between Child & Parent relates to the return value of the functions, not in which context they are executed.

Excursus: WordPress provides extra functions such as get_template_part () for loading template files , which I would like to present in a separate article soon. Therefore only function files should be integrated in the way described here.

Integration of JavaScript and CSS files

For external files that are loaded by the browser, we use the URI functions in the same way. The integration of JavaScript and CSS files are typical here.

 wp_enqueue_script( 'custom-script', get_template_directory_uri() . '/js/custom-script.js' ); wp_enqueue_style( 'genericons', get_template_directory_uri() . '/genericons/genericons.css' );

Again, we use get_template_directory_uri because the corresponding JS and CSS files are in the parent theme. A child theme often only consists of style.css , functions.php and a few template files.

If, however, new CSS and JS files are added to the child theme , the get_stylesheet_directory_uri function can be used instead.

Loading images

For the sake of completeness, I also mention the loading of static images, which I personally rarely need in my themes. Again with URL function.

 <img src="1812-images-image-png-de.html" />

Special function for the style.css

WordPress knows a special function for the integration of the style.css: get_stylesheet_uri ()

This actually only links get_stylesheet_directory () with the string /style.css. Nevertheless, the special function should always be used because it provides the stylesheet_uri filter and thus gives plugins access to loading the style.css.

 wp_enqueue_style( 'twentysixteen-style', get_stylesheet_uri() );

New features in WordPress 4.7

With WordPress 4.7, four new functions were recently introduced, which complement and partially replace the old functions. I will present this in a separate article next week.