load_template() │ WP 1.5.0

Подключает указанный файл в PHP, с помощью require_once.

Используется, чтобы быть уверенным, что среда WordPress уже установлена в момент подключения файла. Функция также устанавливает глобальные переменные: $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID.

Основа для: locate_template()
Хуки из функции

Возвращает

null. Ничего не возвращает, а подключает файл в PHP.

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

load_template( $_template_file, $require_once, $args );
$_template_file(cтрока) (обязательный)
Серверный путь до файла, который нужно подключить.
$require_once(логический)

true - будет подключать файл с помощью require_once, false - с помощью require.

Если подключение файла происходит внутри цикла и этот параметр указан в true, то первый элемент цикла отобразиться корректно, а следующие элементы выведутся как копии 1 элемента.

По умолчанию: true

$args(массив) (С WP 5.5)
Дополнительные параметры для подключаемого файла. Используйте переменную $args в подключаемом файле.
По умолчанию: array()

Примеры

-1

#1 Подключение файла-шаблона в плагине, с возможностью его изменить в теме

Предположим мы создаем плагин и в нем нам нужно указать файл шаблона, который будет использоваться в теме. Логично, что для разных тем файл шаблона будет разный и нам нужно оставить возможность изменять файл шаблона из темы. Для этого мы подключим нужный там файл, только в том случае, если он не определен в теме:

if ( $overridden_template = locate_template('some-template.php') ) {
   // locate_template() вернет путь до файла, если дочер. или родит. тема имеет такой файл
   load_template( $overridden_template );
 } else {
   // если файл не найден в теме или доч. теме, загружаем файл из каталога 'templates' плагина
   load_template( dirname( __FILE__ ) . '/templates/some-template.php' );
 }

Заметки

  • Global. Массив. $posts
  • Global. WP_Post. $post Global post object.
  • Global. true|false. $wp_did_header
  • Global. WP_Query. $wp_query WordPress Query object.
  • Global. WP_Rewrite. $wp_rewrite WordPress rewrite component.
  • Global. wpdb. $wpdb WordPress database abstraction object.
  • Global. Строка. $wp_version
  • Global. WP. $wp Current WordPress environment instance.
  • Global. int. $id
  • Global. WP_Comment. $comment Global comment object.
  • Global. int. $user_ID

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

С версии 1.5.0 Введена.
С версии 5.5.0 The $args parameter was added.

Код load_template() WP 7.0.2

wp-includes/template.php 
function load_template( $_template_file, $load_once = true, $args = array() ) {
	global $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID;

	if ( is_array( $wp_query->query_vars ) ) {
		/*
		 * This use of extract() cannot be removed. There are many possible ways that
		 * templates could depend on variables that it creates existing, and no way to
		 * detect and deprecate it.
		 *
		 * Passing the EXTR_SKIP flag is the safest option, ensuring globals and
		 * function variables cannot be overwritten.
		 */
		// phpcs:ignore WordPress.PHP.DontExtract.extract_extract
		extract( $wp_query->query_vars, EXTR_SKIP );
	}

	if ( isset( $s ) ) {
		$s = esc_attr( $s ); // @phpstan-ignore variable.undefined (It's extracted from query vars.)
	}

	/**
	 * Fires before a template file is loaded.
	 *
	 * @since 6.1.0
	 *
	 * @param string $_template_file The full path to the template file.
	 * @param bool   $load_once      Whether to require_once or require.
	 * @param array  $args           Additional arguments passed to the template.
	 */
	do_action( 'wp_before_load_template', $_template_file, $load_once, $args );

	if ( $load_once ) {
		require_once $_template_file;
	} else {
		require $_template_file;
	}

	/**
	 * Fires after a template file is loaded.
	 *
	 * @since 6.1.0
	 *
	 * @param string $_template_file The full path to the template file.
	 * @param bool   $load_once      Whether to require_once or require.
	 * @param array  $args           Additional arguments passed to the template.
	 */
	do_action( 'wp_after_load_template', $_template_file, $load_once, $args );
}

Подключение файлов темы