Is this possible to enable WordPress to read page templates on .php files that are two levels deep inside the theme folder?

Example:

theme/
    folder-1/
        child-folder-1/my-template.php

Currently it's only possible to read a template if it's nested at the same level of parent folder.

Example:

theme/
    folder-1/
    child-folder-1/my-template.php

Is this possible to enable WordPress to read page templates on .php files that are two levels deep inside the theme folder?

Example:

theme/
    folder-1/
        child-folder-1/my-template.php

Currently it's only possible to read a template if it's nested at the same level of parent folder.

Example:

theme/
    folder-1/
    child-folder-1/my-template.php

• theme-development
• themes
• templates

1 Answer 1

WordPress will only search one level deep (*See below for details) from the root directory of the theme for page (and post) templates.

However, the array of templates can be filtered using the theme_{$post_type}_templates filter, so you can add deeply nested templates on your own:

// See WP_Theme::get_page_templates 
/**
 * Filters list of page templates for a theme.
 *
 * The dynamic portion of the hook name, `$post_type`, refers to the post type.
 *
 * @since 3.9.0
 * @since 4.4.0 Converted to allow complete control over the `$page_templates` array.
 * @since 4.7.0 Added the `$post_type` parameter.
 *
 * @param array        $post_templates Array of page templates. Keys are filenames,
 *                                     values are translated names.
 * @param WP_Theme     $this           The theme object.
 * @param WP_Post|null $post           The post being edited, provided for context, or null.
 * @param string       $post_type      Post type to get the templates for.
 */

function wpse249984_add_templates( $post_templates, $wp_theme, $post, $post_type ) {
    $post_templates['folder-1/child-folder-1/my-template.php'] = 'My Template';

    return $post_templates;
}
add_filter( 'theme_page_templates', 'wpse249984_add_templates', 10, 4 );

*Details: Looking at /wp-includes/class-wp-theme.php.

The depth of 1 is hard-coded and cannot be changed. In WP_Theme::get_post_templates(), the important line is $files = (array) $this->get_files( 'php', 1 );, where 1 is the $depth argument.

/**
 * Returns the theme's post templates.
 *
 * @since 4.7.0
 * @access public
 *
 * @return array Array of page templates, keyed by filename and post type,
 *               with the value of the translated header name.
 */
public function get_post_templates() {
    // If you screw up your current theme and we invalidate your parent, most things still work. Let it slide.
    if ( $this->errors() && $this->errors()->get_error_codes() !== array( 'theme_parent_invalid' ) ) {
        return array();
    }

    $post_templates = $this->cache_get( 'post_templates' );

    if ( ! is_array( $post_templates ) ) {
        $post_templates = array();

        $files = (array) $this->get_files( 'php', 1 );

        foreach ( $files as $file => $full_path ) {
            ...

    return $post_templates;
}

...

/**
 * Return files in the theme's directory.
 * @param mixed $type Optional. Array of extensions to return. Defaults to all files (null).
 * @param int $depth Optional. How deep to search for files. Defaults to a flat scan (0 depth). -1 depth is infinite.
 * @param bool $search_parent Optional. Whether to return parent files. Defaults to false.
 * @return array Array of files, keyed by the path to the file relative to the theme's directory, with the values
 *               being absolute paths.
 */
public function get_files( $type = null, $depth = 0, $search_parent = false ) {
    ...
}