Theme Files Hierarchy

This post is about the names of the WordPress theme files. And it also investigates, which file to include for showing the content of specific site page. This is very important but simple knowledge. Everyone who works with WordPress should be able manage it. Below you will find fully covered WordPress theme files structure and the order of how these files are connected (hierarchy).

Theme files connections (theory)

Hierarchy, in this case, is a sequential check which indicates that multiple file names are suitable for output of one page on the website. The check of the file that will be used proceeds alternately (file by file). I.e. there is a list of file names, that is checking for physical existence one by one, as soon as the existing file is found the check stops and the found file is used as a template.

For example, we go to the category page "Plugins": http://site.com/category/plugins (the page has slug plugins and id 25). Then, to generate the code of this page, WordPress will start checking the existence of the following files one by one (the scan will abort on the first existing file):

• category-plugins.php
• category-25.php
• category.php
• archive.php
• index.php

The complete diagram for all kinds of pages and their files looks like this:

An interactive version of the diagram

Another diagram (old one), perhaps it is more clearer:

Page types and file names

Below is a list of pages and their theme files. In this section, explained the image of the hierarchy of theme files (which is shown above). Also, you will find a site page and its corresponding list of PHP files. Such files should be located in the folder of WordPress theme.

Posts

Archives

404 page

• 404.php
• index.php

Search page

• search.php
• index.php

Main page

• front-page.php
• ('page' post type logic if a page is selected as a front page)
• home.php
• index.php

Blog page

The blog page appears when a 'page' is selected as a front page.

• home.php
• index.php

Embeds

The embed template file is used to render a post which is being embedded with REST API. Embedding appeared in WP 4.5 and allows you to embed your posts in other sites. See get_post_embed_url().

• embed-{post-type}-{post_format}.php
• embed-{post-type}.php
• embed.php

Non-ASCII character handling

Since WordPress 4.7, any dynamic part of a template name which includes non-ASCII characters in its name actually supports both the un-encoded and the encoded form, in that order. You can choose which to use.

Let's look at the page template hierarchy for a page named Hello World 😀 with an ID of 6:

• page-hello-world-😀.php
• page-hello-world-%f0%9f%98%80.php
• page-6.php
• page.php
• singular.php

How it works

For the logic of order in which file connecting is responsible the core file wp-includes/template-loader.php. If you study it, the file explains everything. But such study is not so interesting, so I will write it in details.

First of all. template-loader.php file is connected after the whole WordPress environment is loaded. After the wp-load.php file runned and the main query is inited (see wp()). I.e. template-loader.php file is connected at the very end of the PHP script.

First runs the hook template_redirect. You can do some kind of checks in this hook and if you need redirect to another URL. You must use die() in it. I.e. if the hook changes something, then the work of template-loader.php file ends and the user 'fly' to redirection page.

Next triggers not interesting hook exit_on_http_head. It allows you to make something appear on the screen when you HTTP HEAD request...

Next there are checks on all Conditional Tags. During this checks, WordPress detects which template file is suite more for the current request. The conditional tag is checked, then another and another... As soon as one of the conditional tags is triggered, the corresponding function is called, which finds the appropriate template file and returns the path to it. All such functions are described in get_query_template().

Next - path to theme file defined! Now it runs through the filter template_include, which allows us to modify the template file for the current request.

Next, the file connects to PHP and starts the visual part of the page generation.

Filters

You can change the file hierarchy through dynamic filters:

• (type)_template_hierarchy - filters the array of filenames in the hierarchy by which to search for the desired file. From WP 4.7.

• (type)_template - filters the path to the template file that has already been defined.

All variants of type parameter you can find in the parameter $type of get_query_template() function. Here it is:

• index
• 404
• archive
• post_type_archive
• author
• category
• tag
• taxonomy
• date
• home
• front_page
• page
• paged
• search
• single
• singular
• attachment
• comments_popup

Example of using such a filter see in the answer to this question (rus).

Other theme files

The files below are also used in the theme, but they are simply includable and do not participate in the hierarchy. For example, file sidebar.php is included in any theme file through get_sidebar().

A whole list of such 'includable' files:

• functions.php - always connects automatically when theme is loaded.
• header.php - get_header()
• sidebar.php - get_sidebar()
• footer.php - get_footer()
• searchform.php - get_search_form()