(type)_template_hierarchy │ хук-фильтр │ WP 4.7.0

Позволяет изменить список PHP-файлов иерархии шаблона для текущей страницы (текущего запроса).

Это динамический хук, в котором (type) может быть одним из:

• index — index_template_hierarchy.
• 404 — 404_template_hierarchy.
• archive — archive_template_hierarchy.
• author — author_template_hierarchy.
• category — category_template_hierarchy.
• tag — tag_template_hierarchy.
• taxonomy — taxonomy_template_hierarchy.
• date — date_template_hierarchy.
• embed — embed_template_hierarchy.
• home — home_template_hierarchy.
• frontpage — frontpage_template_hierarchy.
• privacypolicy — privacypolicy_template_hierarchy.
• page — page_template_hierarchy.
• paged — paged_template_hierarchy.
• search — search_template_hierarchy.
• single — single_template_hierarchy.
• singular — singular_template_hierarchy.
• attachment — attachment_template_hierarchy.

Использование

add_filter( '(type)_template_hierarchy', 'wp_kama_type_template_hierarchy_filter' );

/**
 * Function for `(type)_template_hierarchy` filter-hook.
 * 
 * @param string[] $templates A list of template candidates, in descending order of priority.
 *
 * @return string[]
 */
function wp_kama_type_template_hierarchy_filter( $templates ){
	// filter...
	return $templates;
}

$templates(массив)

Список файлов шаблона в порядке их использования. Будет использован первый существующий файл из списка.

Список представляет собой массив, в каждом элементе которого указан путь к файлу относительно темы. Например, для запроса к записи типа page массив будет такой:

Array(
	[0] => page-contacts.php
	[1] => page-25.php
	[2] => page.php
)

Примеры

#1 Добавим свой файл шаблона в иерархию

Допустим у нас в теме есть папка tpl в которой лежат файлы шаблона. Нам нужно для страниц с ярлыками my-page и your-page указать файл шаблона tpl/some-page.php. Для этого используем такой код:

add_filter( 'page'.'_template_hierarchy', function( $templates ){

	$cur_name = str_replace( [ 'page-', '.php' ], '', $templates[0] );

	$custom_tpls = [
		'my-page' => 'tpl/some-page.php'
		'your-page' => 'tpl/some-page.php'
	];

	if( in_array( $cur_name, array_keys( $custom_tpls ), true ) ){
		array_unshift( $templates, $custom_tpls[ $cur_name ] );
	}

	return $templates;
} );

Теперь в самом начале иерархии файлов темы для записей типа page будет находиться файл tpl/some-page.php и, если он есть в теме, он будет использоваться в качестве файла шаблона для текущей страницы.

#2 Добавим свой файл шаблона для кастомного типа записей

Допустим мы зарегистрировали тип записи book и мы хотим, чтобы файл шаблона отдельной страницы этого типа записи лежал в папке темы templates и назывался book.php. Т.е. нам нужно чтобы за вывод отвечал файл шаблона templates/book.php, если этого файла нет, то будет работать стандартная иерархия файлов темы.

add_filter( 'single'.'_template_hierarchy', function( $templates ){

	if( is_singular('book') ){
		array_unshift( $templates, 'templates/book.php' );
	}

	return $templates;
} );

#3 Перенаправим всю иерархию файлов темы в папку templates

Сделаем так, чтобы все файлы шаблона находились в папке темы templates, а не в корневой папке темы:

$types = [
	'404',
	'archive',
	'author',
	'category',
	'tag',
	'taxonomy',
	'date',
	'embed',
	'home',
	'frontpage',
	'privacypolicy',
	'paged',
	'search',
	'page',
	'single',
	'singular', // include attachments
	'attachment',
	//'index', leave /index.php as is
];

// add a prefix for all template files
foreach( $types as $type ){
	add_filter( "{$type}_template_hierarchy", 'prefix_template_hierarchy', 20 );
}

function prefix_template_hierarchy( $templates ){

	$subfolder = 'templates';

	$type = str_replace( '_template_hierarchy', '', current_filter() );

	// add `taxonomy.php` file after last `category.php` and `tag.php` element.
	if( in_array( $type, [ 'category', 'tag' ] ) ){
		$templates[] = 'taxonomy.php';
	}

	// add global prefix `self::$basedir/` ex: `tpl/`.
	foreach( $templates as $index => $relpath ){

		if( ! str_starts_with( $relpath, "$subfolder/" ) ){
			$templates[ $index ] = "$subfolder/$relpath";
		}
	}

	return $templates;
}

Исключение здесь только файл index.php - он должен быть в корне темы. Также, в качестве примера я показал, как определить текущий тип иерархии и, например, добавить в иерархию для категории и тегов файл taxonomy.php. По умолчанию его нет в иерархии файлов темы (хотя логично, чтобы он там был).