get_query_template() │ WP 1.5.0

Gets the system path to the template file for the specified request type: index, category, 404, etc.

The function is used within WordPress to find and include the corresponding template (e.g., home.php, single.php, page.php, etc.), based on the type of the current request.

It searches for the template in the child theme, then in the parent theme. See locate_template().

The function does not include the file, but only returns the path to the found template.

Can be used for custom logic for including templates.

Used within core functions such as get_home_template() or get_single_template().

get_query_template() is the basis for functions of the type get_*_template():

For more details on which file can be included for which request, read the separate article: Theme (Template) File Hierarchy

This function may be useful when using 3 ways to create a page template.

Uses: locate_template()
Used By: get_page_template()
1 time — 0.000085 sec (very fast) | 50000 times — 0.49 sec (very fast)
Hooks from the function

Returns

String. Server path to the template file. If the file could not be found, it will return an empty string.

Usage

get_query_template( $type, $templates );
$type(string) (required)

Name of the file without the extension (.php).

The name can be anything, but it must contain only: lowercase letters of the Latin alphabet, digits and - ([^a-z0-9-]) - the character _ is removed.

Predefined file types (see file hierarchy):

  • index
  • 404
  • archive (includes post_type_archive)
  • author
  • category
  • tag
  • taxonomy
  • date
  • home
  • embed
  • frontpage (not front_page)
  • page
  • paged
  • search
  • single
  • singular
  • attachment
$templates(array)

Optional list of candidates for the template file (specify the file name with the extension).

If this parameter is specified, the previous parameter $type will be ignored and it will only be used in the filter. The file name will be selected based on this parameter, using the locate_template() function.

Default: array()

Examples

1

#1 What the function outputs 

echo get_query_template( 'category' );
// get: /home/public_html/wp-content/themes/theme-name/category.php

// you can specify a custom name and if there is such a file
// in the parent/child theme, the function will return its path:
echo get_query_template( 'foo' );
// get: /home/public_html/wp-content/themes/theme-name/foo.php
0

#2 Connect the 404 template file 

if ( get_query_template( '404' ) ) {
	include( get_query_template( '404' ) );
}

// the same can be written like this:
if ( get_404_template() ) {
	include( get_404_template() );
}
0

#3 Let's try to get one of the template files

By specifying the second parameter, we simultaneously use the locate_template() function and specify the type of the resulting file to which plugins can connect through a filter:

echo get_query_template( 'category', [ 'mycat.php', 'mycat2.php' ] );

/* we get:
/home/public_html/wp-content/themes/theme-name/mycat.php
if there is no such file, the file 'mycat2.php' will be checked
/home/public_html/wp-content/themes/theme-name/mycat2.php
*/

Changelog

Since 1.5.0 Introduced.

get_query_template() code WP 6.8.3

wp-includes/template.php 
function get_query_template( $type, $templates = array() ) {
	$type = preg_replace( '|[^a-z0-9-]+|', '', $type );

	if ( empty( $templates ) ) {
		$templates = array( "{$type}.php" );
	}

	/**
	 * Filters the list of template filenames that are searched for when retrieving a template to use.
	 *
	 * The dynamic portion of the hook name, `$type`, refers to the filename -- minus the file
	 * extension and any non-alphanumeric characters delimiting words -- of the file to load.
	 * The last element in the array should always be the fallback template for this query type.
	 *
	 * Possible hook names include:
	 *
	 *  - `404_template_hierarchy`
	 *  - `archive_template_hierarchy`
	 *  - `attachment_template_hierarchy`
	 *  - `author_template_hierarchy`
	 *  - `category_template_hierarchy`
	 *  - `date_template_hierarchy`
	 *  - `embed_template_hierarchy`
	 *  - `frontpage_template_hierarchy`
	 *  - `home_template_hierarchy`
	 *  - `index_template_hierarchy`
	 *  - `page_template_hierarchy`
	 *  - `paged_template_hierarchy`
	 *  - `privacypolicy_template_hierarchy`
	 *  - `search_template_hierarchy`
	 *  - `single_template_hierarchy`
	 *  - `singular_template_hierarchy`
	 *  - `tag_template_hierarchy`
	 *  - `taxonomy_template_hierarchy`
	 *
	 * @since 4.7.0
	 *
	 * @param string[] $templates A list of template candidates, in descending order of priority.
	 */
	$templates = apply_filters( "{$type}_template_hierarchy", $templates );

	$template = locate_template( $templates );

	$template = locate_block_template( $template, $type, $templates );

	/**
	 * Filters the path of the queried template by type.
	 *
	 * The dynamic portion of the hook name, `$type`, refers to the filename -- minus the file
	 * extension and any non-alphanumeric characters delimiting words -- of the file to load.
	 * This hook also applies to various types of files loaded as part of the Template Hierarchy.
	 *
	 * Possible hook names include:
	 *
	 *  - `404_template`
	 *  - `archive_template`
	 *  - `attachment_template`
	 *  - `author_template`
	 *  - `category_template`
	 *  - `date_template`
	 *  - `embed_template`
	 *  - `frontpage_template`
	 *  - `home_template`
	 *  - `index_template`
	 *  - `page_template`
	 *  - `paged_template`
	 *  - `privacypolicy_template`
	 *  - `search_template`
	 *  - `single_template`
	 *  - `singular_template`
	 *  - `tag_template`
	 *  - `taxonomy_template`
	 *
	 * @since 1.5.0
	 * @since 4.8.0 The `$type` and `$templates` parameters were added.
	 *
	 * @param string   $template  Path to the template. See locate_template().
	 * @param string   $type      Sanitized filename without extension.
	 * @param string[] $templates A list of template candidates, in descending order of priority.
	 */
	return apply_filters( "{$type}_template", $template, $type, $templates );
}

Other Theme Functions