locate_template() │ WP 2.7.0

Finds the most suitable server path to the specified template file. Takes into account the child theme. You can specify that the file is immediately included in PHP.

You can pass an array of file names to the function. It will then check the existence of files in order, and upon finding the first file, it will immediately return the path to it (the subsequent ones will not be processed). If you specify a second parameter, this file will be included in PHP. Let's consider an example:

$files = array(
	'foot.php', // does not exist
	'header.php', // exists, will be returned
	'baz.php', // will not be checked
);
$file_path = locate_template( $files );

echo $file_path;
// will output: /home/example.com/wp-content/themes/wp-kama/header.php

This code will search for files in the following order. Upon the first detection of any file, the search will stop:

foot.php in the child theme
foot.php in the parent theme
header.php in the child theme
header.php in the parent theme
baz.php in the child theme
baz.php in the parent theme

If the second parameter is set to true, the file will be included using the PHP function require_once().

Uses WordPress constants (paths): STYLESHEETPATH then TEMPLATEPATH. This means that the child theme has priority over the parent theme and can overwrite its files.

When including files, when the second parameter is true, the function load_template() is used.

Uses: load_template()

Used By: get_query_template(), get_sidebar(), get_header(), get_footer(), get_template_part()

1 time — 0.000039 sec (very fast) | 50000 times — 0.16 sec (very fast) | PHP 7.1.2, WP 4.7.3

No Hooks.

Returns

String.

The path to the file if it was found.
An empty string if the file could not be found.

Usage

locate_template( $template_names, $load, $require_once, $args );

$template_names(string/array) (required)

An array of template files to include. The files will be included in the order specified in the array.

For files, you need to specify the extension (e.g., header.php).

Instead of an array, you can specify the file name as a string.

$load(boolean)

true means that the file should be included. Otherwise, the function will not include anything and will simply return the path to the specified file.
Default: false

$require_once(boolean)

If set to true, the template file will be loaded using the PHP function require_once. If false, the require function will be used. There is no point in specifying this parameter if $load is set to false.
Default: true

$args(array) (Since WP 5.5)

Additional parameters for the included file. Use the variable $args in the included file.
Default: array()

Examples

#1 Check for a file before include it

Let's create the possibility to output page content in some special way if necessary. To do this, create a file content-SLAG_PAGE.php in the theme and use its code instead of the function the_content():

$page_name = $post->post_name;
$locate_template = locate_template( "content-$page_name.php" );

if( $locate_template ) {
	// OK, connect the template file
	require $locate_template;

	// or:
	//get_template_part( 'content', $page_name );
}
else {
	// File not found, load content by default
	the_content();
}

#2 Getting the file path

echo locate_template( 'header.php' );

//> /home/example.com/public_html/wp-content/themes/pink/header.php

#3 Specify sub-folder

In this function you can specify not only the file name, but also the relative path from the theme root:

locate_template( 'inc/filename.php', true );

This code connect the file filename.php, which is located in the folder inc in the directory of the child theme or parent theme if there is no child theme.

#4 User-provided Template path and Directory traversal attacks

Note that locate_template() does not prevent directory traversal attacks, so if you’re passing a user-provided template name to the function, be sure to verify that it’s from one of the three appropriate locations:

active theme directory
parent theme directory
/wp-includes/theme-compat/ directory

Example:

$template = locate_template( $template_filename_from_unsanitized_user_input );

// Only allow templates that are in the active theme directory, parent theme
// directory, or the /wp-includes/theme-compat/ directory (prevent directory 
// traversal attacks).
$template_in_theme_or_parent_theme_or_compat = (
	// Template is in current theme folder.
	0 === strpos( realpath( $template ), realpath( STYLESHEETPATH ) ) ||
	// Template is in current or parent theme folder.
	0 === strpos( realpath( $template ), realpath( TEMPLATEPATH ) ) ||
	// Template is in theme-compat folder.
	0 === strpos( realpath( $template ), realpath( ABSPATH . WPINC . '/theme-compat/' ) )
);

if ( $template_in_theme_or_parent_theme_or_compat ) {
	require_once( $template );
}

Notes

Global. String. $wp_stylesheet_path Path to current theme's stylesheet directory.
Global. String. $wp_template_path Path to current theme's template directory.

Changelog

Since 2.7.0	Introduced.
Since 5.5.0	The `$args` parameter was added.

`locate_template() locate template` code ^{WP 6.9}

wp-includes/template.php

function locate_template( $template_names, $load = false, $load_once = true, $args = array() ) {
	global $wp_stylesheet_path, $wp_template_path;

	if ( ! isset( $wp_stylesheet_path ) || ! isset( $wp_template_path ) ) {
		wp_set_template_globals();
	}

	$is_child_theme = is_child_theme();

	$located = '';
	foreach ( (array) $template_names as $template_name ) {
		if ( ! $template_name ) {
			continue;
		}
		if ( file_exists( $wp_stylesheet_path . '/' . $template_name ) ) {
			$located = $wp_stylesheet_path . '/' . $template_name;
			break;
		} elseif ( $is_child_theme && file_exists( $wp_template_path . '/' . $template_name ) ) {
			$located = $wp_template_path . '/' . $template_name;
			break;
		} elseif ( file_exists( ABSPATH . WPINC . '/theme-compat/' . $template_name ) ) {
			$located = ABSPATH . WPINC . '/theme-compat/' . $template_name;
			break;
		}
	}

	if ( $load && '' !== $located ) {
		load_template( $located, $load_once, $args );
	}

	return $located;
}