theme_templates хук-фильтр . WP 4.9.6

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

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

add_filter( 'theme_templates', 'filter_function_name_4757', 10, 4 );
function filter_function_name_4757( $post_templates, $this, $post, $post_type ){
	// Изменяем...

	return $post_templates;
}

$post_templates(массив)

Массив файлов-шаблонов для постов. Ключ массива - это путь до файла относительно папки темы, значение - это имя файла-шаблона.

Array(
	[page-my-tpl.php] => Мой супер шаблон в корне темы
	[template/page-default.php] => Мой дефолтный шаблон в папке template
	[template/portfolio/page-full.php] => Шаблон портфолио на всю ширину в папке template -> portfolio
	[template/portfolio/page-mini.php] => Шаблон портфолио минимальный в папке template -> portfolio
)

$this(WP_Theme)

Экземпляр класса WP_Theme.

$post(WP_Post/null)

Объект записи (при редактировании) или null.

$post_type(строка)

Тип записи, для которого запрашивается список шаблонов.

Примеры

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

WordPress по умолчанию ищет шаблоны в корне темы и в папках 1 уровня. Добавим свой шаблон в более глубокой папке.

Мы добавляем шаблон без проверки на тип записи, а значит он будет доступен для всех типов постов.

add_filter( 'theme_templates', 'add_my_template_to_list', 10, 4 );

function add_my_template_to_list( $templates, $wp_theme, $post, $post_type ) {
	$templates['template/defaults/page.php'] = 'Мой дефолтный шаблон';

	return $templates;
}

#2 Добавим свой шаблон в список для страниц

Добавим в массив с шаблонами свой шаблон, только если он запрашивается для страниц: post_type=page.

add_filter( 'theme_templates', 'add_my_template_to_list', 10, 4 );

function add_my_template_to_list( $templates, $wp_theme, $post, $post_type ) {
	if ( 'page' === $post_type ) {
		$templates['template/defaults/page.php'] = 'Мой дефолтный шаблон страницы';
	}

	return $templates;
}

Если у вас другой тип записи, то page замените на нужный тип или, чтобы не делать проверку в коде, можно использовать похожий хук theme_(post_type)_templates.

#3 Добавим свой шаблон из плагина

Пусть нам нужна страница со своим индивидуальным шаблоном, который надо добавить с помощью плагина. Создадим плагин со следующей структурой:

plugin-my-tpl (папка плагина)
├── plugin-my-tpl.php (основной файл плагина)
└── templates (папка с шаблонами)
		├── page-tpl-1.php (шаблон №1)
		└── page-tpl-2.php (шаблон №2)

Файл plugin-my-tpl.php

/**
 * Plugin Name: plugin-my-tpl
 */

add_filter( 'theme_templates', 'add_my_template_to_list', 10, 4 );
add_filter( 'template_include', 'my_plugin_template_include' );

// Добавляем в список свои шаблоны для страниц
function add_my_template_to_list( $templates, $wp_theme, $post, $post_type ) {
	if ( 'page' === $post_type ) {
		// Дополняем массив шаблонов своими собственными
		$templates += my_plugin_templates();
	}

	return $templates;
}

// Формируем массив с шаблонами
function my_plugin_templates() {
	$base_path = basename( __DIR__ );

	return [
		$base_path . '/templates/page-tpl-1.php' => 'Шаблон из плагина №1',
		$base_path . '/templates/page-tpl-2.php' => 'Шаблон из плагина №2',
	];
}

// Подключает шаблон страницы из плагина
function my_plugin_template_include( $template ) {
	// Если это не страница - возвращаем что есть
	if ( ! is_page() ) {
		return $template;
	}

	// Получаем сохранённый шаблон
	$path_slug = get_post_meta( get_the_ID(), '_wp_page_template', true );

	// Если шаблон не плагина - возвращаем что есть
	if ( ! in_array( $path_slug, array_keys( my_plugin_templates() ) ) ) {
		return $template;
	}

	// Создаем полный путь к файлу
	$path_file = wp_normalize_path( WP_PLUGIN_DIR . '/' . $path_slug );

	// Проверяем, есть ли физически файл шаблона и, если да - отдаем движку
	if ( file_exists( $path_file ) ) {
		return $path_file;
	}

	return $template;
}

Решение в стиле ООП можно посмотреть в статье Add Page Templates to WordPress with a Plugin.

Список изменений

Где вызывается хук

$post_templates = (array) apply_filters( 'theme_templates', $post_templates, $this, $post, $post_type );

Где используется хук в ядре WP