Функция locate_template() в WordPress: использование и примеры

# LOCATE_TEMPLATE() │ WP 2.7.0

Функция locate_template() позволяет найти имя файла шаблона с наивысшим приоритетом, который существует. 

Она ищет сначала в директории стилей, затем в директории шаблонов и в wp-includes/theme-compat. Это позволяет темам, которые наследуют от родительской темы, переопределять только нужный файл.

**Использует:** load_template()

**Используется в:** 
- get_query_template()
- get_sidebar()
- get_header()
- get_footer()
- get_template_part()

## Характеристики производительности

- Один вызов — 0.000039 сек (очень быстро)
- 50000 раз — 0.16 сек (очень быстро)
- Версия PHP: 7.1.2, WordPress: 4.7.3

## Возврат

Возвращает строку — имя файла шаблона, если он найден.

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

Функция locate_template() вызывается следующим образом:

```php
locate_template( $template_names, $load, $load_once, $args );

Где:

• $template_names (строка|массив) (обязательный) — Файл(ы) шаблона, которые нужно искать, в порядке приоритета.
• $load (true|false) — Если true, файл шаблона будет загружен, если будет найден. По умолчанию: false.
• $load_once (true|false) — Загрузить с помощью require_once или require. Не влияет, если $load равно false. По умолчанию: true.
• $args (массив) — Дополнительные аргументы, передаваемые в шаблон. По умолчанию: пустой массив.

Примеры

1. Проверка файла перед его подключением

Создадим возможность выводить содержимое страницы особым образом, если это необходимо. Для этого создадим файл content-SLAG_PAGE.php в теме и используем его код вместо функции the_content():

$page_name = $post->post_name;
$locate_template = locate_template( "content-$page_name.php" );

if( $locate_template ) {
    // ОК, подключаем файл шаблона
    require $locate_template;

    // Или:
    // get_template_part( 'content', $page_name );
} else {
    // Файл не найден, загружаем содержимое по умолчанию
    the_content();
}

2. Получение пути к файлу

Чтобы получить путь к шаблону, используем следующий код:

echo locate_template( 'header.php' );

Вывод: /home/example.com/public_html/wp-content/themes/pink/header.php

3. Указание подкаталога

В этой функции можно указывать не только имя файла, но и относительный путь от корня темы:

locate_template( 'inc/filename.php', true );

Этот код подключает файл filename.php, который находится в папке inc директории дочерней темы или родительской теме, если дочерней ��емы нет.

4. Учет пользовательских путей шаблона и предотвращение атак

Обратите внимание, что функция locate_template() не предотвращает атаки через переход по директориям. Если вы передаете имя шаблона, предоставленное пользователем, убедитесь, что оно находится в одной из трех подходящих директорий:

1. Директория активной темы
2. Директория родительской темы
3. Директория /wp-includes/theme-compat/

Пример:

$template = locate_template( $template_filename_from_unsanitized_user_input );

// Разрешаем только шаблоны, находящиеся в активной теме, родительской теме или в /wp-includes/theme-compat/ 
$template_in_theme_or_parent_theme_or_compat = (
    // Шаблон в директории текущей темы.
    0 === strpos( realpath( $template ), realpath( STYLESHEETPATH ) ) ||
    // Шаблон в директории текущей или родительской темы.
    0 === strpos( realpath( $template ), realpath( TEMPLATEPATH ) ) ||
    // Шаблон в директории theme-compat.
    0 === strpos( realpath( $template ), realpath( ABSPATH . WPINC . '/theme-compat/' ) )
);

if ( $template_in_theme_or_parent_theme_or_compat ) {
    require_once( $template );
}

Примечания

• Глобальная переменная: $wp_stylesheet_path — Путь к директории стилей текущей темы.
• Глобальная переменная: $wp_template_path — Путь к директории шаблонов текущей темы.

Изменения

• С 2.7.0 — Введена функция.
• С 5.5.0 — Параметр $args был добавлен.

Код функции locate_template()

function locate_template( $template_names, $load = false, $load_once = true, $args = array() ) {
    global $wp_stylesheet_path, $wp_template_path;

    if ( ! isset( $wp_stylesheet_path ) || ! isset( $wp_template_path ) ) {
        wp_set_template_globals();
    }

    $is_child_theme = is_child_theme();

    $located = '';
    foreach ( (array) $template_names as $template_name ) {
        if ( ! $template_name ) {
            continue;
        }
        if ( file_exists( $wp_stylesheet_path . '/' . $template_name ) ) {
            $located = $wp_stylesheet_path . '/' . $template_name;
            break;
        } elseif ( $is_child_theme && file_exists( $wp_template_path . '/' . $template_name ) ) {
            $located = $wp_template_path . '/' . $template_name;
            break;
        } elseif ( file_exists( ABSPATH . WPINC . '/theme-compat/' . $template_name ) ) {
            $located = ABSPATH . WPINC . '/theme-compat/' . $template_name;
            break;
        }
    }

    if ( $load && '' !== $located ) {
        load_template( $located, $load_once, $args );
    }

    return $located;
}

Связанные функции

• comments_template()
• get_footer()
• get_header()
• get_parent_theme_file_path()
• get_parent_theme_file_uri()
• get_search_form()
• get_sidebar()
• get_stylesheet_directory()
• get_stylesheet_directory_uri()
• get_stylesheet_uri()
• get_template_directory()
• get_template_directory_uri()
• get_template_part()
• get_theme_file_path()
• get_theme_file_uri()
• get_theme_root_uri()
• is_page_template()
• load_template()