template_redirect │ хук-событие │ WP 1.5.0

Срабатывает перед тем, как WordPress определит какой файл шаблона использовать для вывода контента.

Событие удобно использовать для перенаправления, когда WordPress обработал основной запрос и установил все объекты ($wp_query, $post, условные теги), но вывод контента на экран еще не произошёл.

Это популярный хук и самое удобное место, когда для принятия решения о перенаправлении нужны все данные о текущем запросе (обрабатываемом объекте WordPress).

Заметка по неправильному использованию хука

Этот хук нельзя использовать для загрузки альтернативного файла шаблона. Пример неправильного кода:

// неправильный код, используйте хук template_include
add_action( 'template_redirect', 'my_callback' );
function my_callback() {
	if ( /* Условие */ ) {
		include( SOME_PATH . '/some-custom-file.php' );
		exit();
	}
}

Проблема этого кода в том, что во время срабатывания условия и после подключения указанного файла, работа WordPress полностью прекращается. И перед прекращением работы, не срабатывают некоторые важные фильтры и функции, которые используются плагинами в WordPress. Это чаще всего вызывает неприятные последствия. Которые не всегда заметны сразу.

Чтобы подключить альтернативный файл шаблона, нужно использовать фильтр template_include:

add_filter( 'template_include', 'my_callback' );
function my_callback( $original_template ) {
	if ( /* Условие */ )
		return SOME_PATH . '/some-custom-file.php';
	else
		return $original_template;
}

Эффект будет тот же и никаких проблем с плагинами и прочим.

Коротко это правило можно записать так:

template_redirect - для перенаправлений
template_include - для подключений

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

add_action( 'template_redirect', 'wp_kama_template_redirect_action' );

/**
 * Function for `template_redirect` action-hook.
 * 
 * @return void
 */
function wp_kama_template_redirect_action(){

	// action...
}

Примеры

#1 Перенаправление на страницу регистрации

Допустим, у нас есть страница service, вход на которую нужно открыть только авторизованным пользователям, а остальных нужно перекинуть на страницу авторизации.

Следующий код показывает как это сделать:

function my_page_template_redirect(){
	if( is_page('service') && ! is_user_logged_in() ){
		wp_redirect( home_url( '/signup/' ) );
		exit();
	}
}
add_action( 'template_redirect', 'my_page_template_redirect' );

#2 Еще примеры

Смотрите в статье: Перенаправление на случайную запись в WordPress.

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

С версии 1.5.0

Введена.

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

В файле: /wp-includes/template-loader.php

template_redirect

wp-includes/template-loader.php 13

do_action( 'template_redirect' );

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

wp-includes/customize/class-wp-customize-selective-refresh.php 147

add_action( 'template_redirect', array( $this, 'handle_render_partials_request' ) );

wp-includes/default-filters.php 325

add_action( 'template_redirect', 'rest_output_link_header', 11, 0 );

wp-includes/default-filters.php 356

add_action( 'template_redirect', 'wp_shortlink_header', 11, 0 );

wp-includes/default-filters.php 455

add_action( 'template_redirect', 'wp_old_slug_redirect' );

wp-includes/default-filters.php 639

add_action( 'template_redirect', 'redirect_canonical' );

wp-includes/default-filters.php 640

add_action( 'template_redirect', 'wp_redirect_admin_locations', 1000 );

wp-includes/default-filters.php 660

add_action( 'template_redirect', '_wp_admin_bar_init', 0 );

wp-includes/ms-default-filters.php 74

add_action( 'template_redirect', 'maybe_redirect_404' );

wp-includes/sitemaps/class-wp-sitemaps.php 69

add_action( 'template_redirect', array( $this, 'render_sitemaps' ) );