Ієрархія шаблонів WordPress: Повний технічний посібник

WordPress's Template Hierarchy — це детермінована система вирішення, яку WordPress використовує для вибору PHP-файлу шаблону, що відображає певний запит сторінки. Коли відвідувач завантажує будь-який URL на вашому сайті, WordPress оцінює контекст запиту — тип запису, таксономію, slug, ID тощо — а потім проходить пріоритетний список кандидатів імен файлів, поки не знайде збіг у директорії активної теми. Якщо конкретний шаблон не існує, відбувається відкат до index.php.

Глибоке розуміння цієї системи є обов’язковим для серйозної розробки WordPress. Це основа кожного кастомного макету, кожного перевизначення теми та кожної оптимізації продуктивності, пов’язаної з кешуванням шаблонів. Незалежно від того, чи ви керуєте контентним виданням, магазином WooCommerce або headless WordPress, ієрархія визначає, який PHP виконується при кожному завантаженні сторінки.

Що насправді являє собою Template Hierarchy

По суті, Template Hierarchy — це ланцюжок пошуку, вбудований у ядро WordPress (wp-includes/class-wp-query.php та wp-includes/template.php). Коли WordPress завершує аналіз запиту та заповнення глобального об’єкта $wp_query, він внутрішньо викликає еквіваленти get_template_part() для визначення правильного шаблону. Вирішення не є випадковим — це суворий, упорядкований список імен файлів, що перевіряються в кореневій директорії вашої теми.

Ключовий архітектурний момент, який більшість посібників пропускає: WordPress не сканує директорію вашої теми. Він формує пріоритетний масив кандидатів імен файлів на основі змінних запиту, а потім перевіряє кожен файл за допомогою locate_template(). Це розрізнення важливе, коли ви налагоджуєте відсутні шаблони або створюєте програматичні генератори тем.

Ланцюжок відкату завжди завершується на index.php. Цей файл є єдиним файлом шаблону, який WordPress вимагає включати в кожну тему, відповідно до стандартів розробки тем.

Основні файли шаблонів, які повинна розуміти кожна тема

Зверніть увагу на запис singular.php — це шаблон, який багато розробників повністю ігнорують. Представлений у WordPress 4.3, він знаходиться між single.php/page.php та index.php в ієрархії, виступаючи єдиним catch-all для будь-якого перегляду одиничного контенту. Якщо ваша тема містить singular.php, він перехоплюватиме випадки, коли не існує ні single.php, ні page.php.

Повний порядок вирішення шаблонів за типом сторінки

Окремі записи блогу

Коли відвідувач запитує стандартний запис (post_type = 'post'), WordPress перевіряє в такому точному порядку:

single-post-{slug}.php (WordPress 4.4+, наприклад, single-post-hello-world.php)
single-post.php

1. single.php
2. singular.php
3. index.php

Варіант на основі slug на кроці 1 рідко документується, але надзвичайно корисний для надання одному флагманському запису повністю унікального макету без зміни будь-якого іншого шаблону.

Кастомні типи записів

Для кастомного типу запису, зареєстрованого як portfolio:

1. single-portfolio-{slug}.php
2. single-portfolio.php
3. single.php
4. singular.php
5. index.php

Для його архіву (вимагає 'has_archive' => true у register_post_type()):

1. archive-portfolio.php
2. archive.php
3. index.php

Поширена помилка: реєстрація кастомного типу запису з 'has_archive' => false (за замовчуванням) і подальше здивування, чому archive-portfolio.php ніколи не завантажується. URL архіву просто повертає 404 у такому випадку.

Статичні сторінки

1. Файл шаблону, встановлений через мета-блок атрибутів сторінки (кастомний шаблон сторінки)
2. page-{slug}.php
3. page-{ID}.php
4. page.php
5. singular.php
6. index.php

Кастомні шаблони сторінок — це PHP-файли у директорії вашої теми, що містять коментар-заголовок файлу:

<?php
/**
 * Template Name: Full Width Layout
 * Template Post Type: page
 */

Оголошення Template Post Type (WordPress 4.7+) обмежує, які типи записів можуть використовувати цей шаблон з редактора. Без нього шаблон з’являється у випадаючому списку атрибутів сторінки лише для сторінок.

Архіви категорій

1. category-{slug}.php
2. category-{ID}.php
3. category.php
4. archive.php
5. index.php

Архіви кастомних таксономій

Для таксономії, зареєстрованої як genre з slug терміна thriller:

1. taxonomy-genre-thriller.php
2. taxonomy-genre.php
3. taxonomy.php
4. archive.php
5. index.php

Архіви авторів

1. author-{user_nicename}.php
2. author-{user_ID}.php
3. author.php
4. archive.php
5. index.php

Головна сторінка (критичний граничний випадок)

Це найбільш незрозуміла частина ієрархії. WordPress розрізняє два сценарії головної сторінки:

Сценарій A — Індекс записів блогу як головна сторінка (Налаштування > Читання: «Останні записи»):

1. front-page.php
2. home.php
3. index.php

Сценарій B — Статична сторінка як головна сторінка (Налаштування > Читання: «Статична сторінка»):

1. front-page.php

page.php (якщо front-page.php не існує)
index.php

Критичний нюанс: front-page.php має пріоритет у обох сценаріях. Якщо front-page.php існує у вашій темі, він завжди відображає головну сторінку незалежно від налаштувань читання. Це дивує багатьох розробників, які створюють front-page.php для статичної головної сторінки, але забувають, що він також перевизначить індекс блогу, якщо вони пізніше змінять налаштування.

Результати пошуку та 404

Результати пошуку:

1. search.php
2. index.php

Сторінки помилки 404:

1. 404.php
2. index.php

Добре розроблена 404.php — це актив для конверсії, а не другорядна деталь. Вона повинна містити форму пошуку, посилання на популярний контент та зрозумілу навігацію — все це вимагає розуміння системи шаблонів для правильної реалізації.

Як WordPress вирішує шаблони внутрішньо

Розуміння внутрішньої механіки допомагає при налагодженні або розширенні системи. Процес вирішення в wp-includes/template.php працює наступним чином:

// Simplified representation of WordPress template resolution
function get_query_template( $type, $templates = array() ) {
    $type = preg_replace( '|[^a-z0-9-]+|', '', $type );

    if ( empty( $templates ) ) {
        $templates = array( "{$type}.php" );
    }

    // Fires before template resolution — allows plugins/themes to modify the list
    $templates = apply_filters( "_{$type}_template_hierarchy", $templates );

    $template = locate_template( $templates );

    // Fires after template is located — allows final override
    $template = apply_filters( "{$type}_template", $template, $type, $templates );

    return $template;
}

Два хуки фільтрів є критично важливими тут:

_{$type}_template_hierarchy — спрацьовує до пошуку файлу, дозволяючи вам додавати додаткових кандидатів у масив
{$type}_template — спрацьовує після знаходження файлу, дозволяючи вам повністю замінити шлях до вирішеного шаблону

Саме через ці хуки плагіни конструкторів сторінок, мережі мультисайтів та WooCommerce перевизначають шаблони без зміни файлів теми.
Програматичне перевизначення ієрархії шаблонів
Впровадження кастомного шляху до шаблону
add_filter( 'single_template_hierarchy', function( $templates ) {
    // Prepend a plugin-directory template before theme templates are checked
    if ( is_singular( 'portfolio' ) ) {
        array_unshift( $templates, plugin_dir_path( __FILE__ ) . 'templates/single-portfolio.php' );
    }
    return $templates;
} );
Перевизначення шаблону після вирішення
add_filter( 'template_include', function( $template ) {
    if ( is_singular( 'portfolio' ) && current_user_can( 'edit_posts' ) ) {
        // Load a debug template for editors
        $debug_template = get_stylesheet_directory() . '/debug/single-portfolio-debug.php';
        if ( file_exists( $debug_template ) ) {
            return $debug_template;
        }
    }
    return $template;
} );
Фільтр template_include є останнім хуком перед завантаженням файлу шаблону WordPress. Він отримує повністю вирішений шлях і повинен повертати дійсний шлях до файлу.
Частини шаблонів та функція get_template_part()
Частини шаблонів — це багаторазові PHP-фрагменти, що завантажуються через get_template_part(). Вони мають власну міні-ієрархію:
// Loads content-video.php if it exists, falls back to content.php
get_template_part( 'template-parts/content', 'video' );
WordPress 5.5 додав третій параметр для передачі даних до частин шаблонів:
get_template_part( 'template-parts/card', 'product', array(
    'post_id' => get_the_ID(),
    'show_price' => true,
) );
Всередині частини шаблону отримайте ці дані за допомогою:
$args = wp_parse_args( $args, array(
    'post_id'    => 0,
    'show_price' => false,
) );
Це усуває необхідність використання глобальних змінних для передачі даних між шаблонами — значне покращення для підтримуваності та тестованості.
Дочірні теми та система перевизначення шаблонів
Дочірні теми розширюють ієрархію, додаючи директорію дочірньої теми на початок шляху пошуку шаблонів. Коли виконується locate_template(), він перевіряє:

Директорія дочірньої теми (get_stylesheet_directory())
Директорія батьківської теми (get_template_directory())

Це означає, що ви можете перевизначити будь-який шаблон батьківської теми, створивши файл з ідентичним ім’ям у вашій дочірній темі. Вам не потрібно копіювати весь файл — лише ті частини, які ви хочете змінити — але WordPress завантажує файл як єдине ціле, тому ви повинні включити всю необхідну розмітку.
Поширена помилка дочірньої теми: Копіювання functions.php з батьківської теми до дочірньої та очікування, що він замінить функції батьківської. На відміну від інших файлів шаблонів, functions.php у дочірній темі завантажується на додаток до батьківського functions.php, а не замість нього. Обидва файли виконуються.
Щоб створити мінімальну структуру дочірньої теми:
my-child-theme/
├── style.css          (required — contains theme header comment)
├── functions.php      (optional — enqueue parent styles here)
└── single-post.php    (overrides parent's single-post.php)
Заголовок style.css повинен оголошувати батьківську тему:
/*
 Theme Name: My Child Theme
 Template: parent-theme-directory-name
*/
Налагодження активного шаблону
Метод 1: Плагін Query Monitor
Плагін Query Monitor (безкоштовний, WordPress.org) відображає вирішений файл шаблону та повну ієрархію кандидатів у панелі адміністративної панелі інструментів. Це найнадійніший інструмент налагодження та додає незначне навантаження.
Метод 2: Хук template_include
add_filter( 'template_include', function( $template ) {
    if ( current_user_can( 'manage_options' ) ) {
        echo '<!-- Template: ' . esc_html( str_replace( ABSPATH, '', $template ) ) . ' -->';
    }
    return $template;
} );
Це виводить шлях до шаблону як HTML-коментар, видимий лише адміністраторам. Видаліть його перед розгортанням у продакшн.
Метод 3: WP_DEBUG та логування
На сервері розробки увімкніть логування налагодження у wp-config.php:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
Потім додайте тимчасове логування всередині template_include:
add_filter( 'template_include', function( $template ) {
    error_log( 'Resolved template: ' . $template );
    return $template;
} );
У середовищі VPS Хостингу з root-доступом ви можете відстежувати лог налагодження в реальному часі:
tail -f /var/www/html/wp-content/debug.log
Цей підхід набагато надійніший, ніж покладатися на браузерні інструменти налагодження при усуненні проблем з вирішенням шаблонів на живому або тестовому сервері.
WooCommerce та система перевизначення шаблонів
WooCommerce постачається з власною ієрархією шаблонів, що знаходиться поверх нативної системи WordPress. Шаблони WooCommerce розміщені в wp-content/plugins/woocommerce/templates/ та завантажуються через власну функцію wc_get_template(), яка перевіряє перевизначення в:

wp-content/themes/your-theme/woocommerce/

Щоб перевизначити шаблон окремого продукту WooCommerce, скопіюйте woocommerce/templates/single-product.php до your-theme/woocommerce/single-product.php. Ніколи не редагуйте файли шаблонів плагінів безпосередньо — вони перезаписуються при кожному оновленні плагіна.

WooCommerce також підключається до хуків дій woocommerce_template_single_*, що дає вам детальний контроль над окремими секціями (ціна, вкладки, кнопка додавання до кошика) без перевизначення цілих файлів шаблонів. Це кращий підхід для незначних модифікацій.

Блокові теми та ієрархія шаблонів у Full Site Editing

WordPress 5.9 представив Full Site Editing (FSE) з блоковими темами, що змінює практичну роботу ієрархії шаблонів. Блокові теми зберігають шаблони як HTML-файли у директорії templates/ замість PHP-файлів:

my-block-theme/
├── templates/
│   ├── index.html
│   ├── single.html
│   ├── page.html
│   ├── archive.html
│   └── 404.html
├── parts/
│   ├── header.html
│   └── footer.html
└── theme.json

Логіка вирішення дотримується тих самих правил ієрархії, але WordPress тепер також перевіряє базу даних на наявність кастомізованих користувачем шаблонів, збережених через редактор сайту. Порядок пошуку стає таким:

1. Збережений користувачем шаблон у базі даних (тип запису wp_template)
2. HTML-файл у директорії templates/ теми
3. HTML-файл у директорії templates/ батьківської теми
4. Вбудовані резервні шаблони WordPress

Класичні PHP-теми та блокові теми можуть співіснувати в одній інсталяції WordPress, але ви не можете змішувати PHP-шаблони та HTML-блокові шаблони в межах однієї теми. Якщо ваша тема має директорію templates/ та дійсний theme.json, WordPress вважає її блоковою темою.

Для команд, що виконують критичні за продуктивністю навантаження на Виділених серверах, розуміння цього розрізнення є важливим при оцінці фреймворків тем — блокові теми перекладають рендеринг шаблонів на блоковий парсер, який має інші характеристики кешування порівняно з виконанням PHP-шаблонів.

Вплив ієрархії шаблонів на продуктивність

Кожне вирішення шаблону включає перевірки файлової системи через locate_template(). На сайті з великим трафіком це може додавати відчутне навантаження, якщо не кешується. Ключові оптимізації:

Кешування об’єктів: Використовуйте постійний кеш об’єктів (Redis або Memcached) для кешування результатів WP_Query та зменшення кількості запитів до бази даних, що впливають на вибір шаблону.

OPcache: Переконайтеся, що PHP OPcache увімкнений та правильно налаштований. Оскільки шаблони є PHP-файлами, OPcache компілює їх у байткод при першому завантаженні та обслуговує наступні запити з пам’яті. На правильно налаштованому VPS з cPanel, OPcache зазвичай увімкнений за замовчуванням, але може потребувати налаштування opcache.memory_consumption та opcache.max_accelerated_files для великих тем з багатьма файлами шаблонів.

Уникайте непотрібних файлів шаблонів: Кожен файл шаблону у директорії вашої теми є кандидатом, який locate_template() повинен перевірити. Теми з сотнями файлів шаблонів (поширено у роздутих комерційних темах) збільшують введення-виведення файлової системи при кожному некешованому запиті. Перевірте свою тему та видаліть невикористовувані шаблони.

Повне кешування сторінок: Інструменти на кшталт WP Rocket, W3 Total Cache або кешування на рівні сервера (Nginx FastCGI cache, Varnish) повністю обходять виконання PHP-шаблонів для анонімних користувачів. Вирішення ієрархії шаблонів виконується лише при промаху кешу.

Практичні патерни кастомізації

Патерн 1: Макет для конкретної категорії без плагіна

Створіть category-news.php у директорії вашої теми. WordPress автоматично використовує його для архіву категорії «news». Жодного плагіна, жодного хука фільтра — лише файл з правильним ім’ям.

<?php
/**
 * Template for the "news" category archive.
 * Inherits from: category.php → archive.php → index.php
 */
get_header();
?>
<main class="news-archive">
    <h1><?php single_cat_title(); ?></h1>
    <?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
        <?php get_template_part( 'template-parts/card', 'news' ); ?>
    <?php endwhile; endif; ?>
    <?php the_posts_pagination(); ?>
</main>
<?php get_footer(); ?>

Патерн 2: Макет для конкретного автора для відомих авторів

// author-jane-smith.php — loads only for the author with nicename "jane-smith"
get_header();
?>
<div class="featured-author-layout">
    <?php get_template_part( 'template-parts/author', 'featured' ); ?>
    <!-- Custom bio section, social links, etc. -->
</div>
<?php get_footer(); ?>

Патерн 3: Умовна логіка всередині index.php

Якщо ви створюєте мінімальну тему і хочете уникнути кількох файлів шаблонів, ви можете використовувати умовні теги всередині index.php:

<?php get_header(); ?>

<?php if ( is_front_page() && is_home() ) : ?>
    <?php get_template_part( 'template-parts/home', 'blog-index' ); ?>
<?php elseif ( is_front_page() ) : ?>
    <?php get_template_part( 'template-parts/home', 'static' ); ?>
<?php elseif ( is_single() ) : ?>
    <?php get_template_part( 'template-parts/content', get_post_type() ); ?>
<?php elseif ( is_archive() ) : ?>
    <?php get_template_part( 'template-parts/archive', 'default' ); ?>
<?php else : ?>
    <?php get_template_part( 'template-parts/content', 'none' ); ?>
<?php endif; ?>

<?php get_footer(); ?>

Цей патерн використовується темами на кшталт Twenty Twenty-One і є цілком допустимим. Компроміс полягає в тому, що єдиний великий index.php стає важчим для підтримки зі зростанням складності.

Мультисайт та ієрархія шаблонів

У мережі WordPress Multisite кожен сайт у мережі може використовувати різну активну тему. Ієрархія шаблонів працює однаково для кожного сайту, але плагіни, активовані на рівні мережі, можуть використовувати фільтри template_include або _{$type}_template_hierarchy для впровадження спільних шаблонів на всіх сайтах без дублювання файлів теми.

Поширений патерн мультисайту — директорія «мережевих шаблонів» поза веб-коренем, на яку посилаються через хуки фільтрів на рівні плагіна. Це дозволяє центральній команді дизайну одночасно розгортати оновлення шаблонів на всіх сайтах — значна операційна перевага для агентств, що керують десятками клієнтських сайтів на єдиному середовищі Спільного веб-хостингу або VPS.

SSL, безпека та права доступу до файлів шаблонів

Файли шаблонів є PHP і повинні розглядатися як виконуваний код. Неправильні права доступу до файлів є поширеним вектором атак. На Linux-сервері файли шаблонів теми повинні належати користувачу веб-сервера (зазвичай www-data або nginx) та мати режим 644:

find /var/www/html/wp-content/themes/your-theme -type f -name "*.php" -exec chmod 644 {} ;
find /var/www/html/wp-content/themes/your-theme -type d -exec chmod 755 {} ;

Ніколи не встановлюйте PHP-файлам права 777. Якщо файл шаблону потребує доступу на запис (незвично і загалом небажано), використовуйте 664 з правильним груповим власником.

Поєднання вашої інсталяції WordPress з дійсним SSL-сертифікатом гарантує, що контент, відображений шаблонами — включаючи динамічно згенеровані сторінки з конфіденційними даними користувачів — завжди передається через HTTPS. Це є обов’язковим для будь-якого сайту, що використовує контактні форми, облікові записи користувачів або електронну комерцію.

Довідник ієрархії шаблонів: Візуальний потік

Request URL
    |
    v
WordPress Query Resolution (WP_Query)
    |
    +-- Is it the front page?
    |       front-page.php → home.php → index.php
    |
    +-- Is it a single post?
    |       single-{type}-{slug}.php → single-{type}.php → single.php → singular.php → index.php
    |
    +-- Is it a static page?
    |       [custom template] → page-{slug}.php → page-{ID}.php → page.php → singular.php → index.php
    |
    +-- Is it a category archive?
    |       category-{slug}.php → category-{ID}.php → category.php → archive.php → index.php
    |
    +-- Is it a custom taxonomy?
    |       taxonomy-{tax}-{term}.php → taxonomy-{tax}.php → taxonomy.php → archive.php → index.php
    |
    +-- Is it an author archive?
    |       author-{nicename}.php → author-{ID}.php → author.php → archive.php → index.php
    |
    +-- Is it a date archive?
    |       date.php → archive.php → index.php
    |
    +-- Is it search results?
    |       search.php → index.php
    |
    +-- Is it a 404?
            404.php → index.php

Матриця рішень: Коли використовувати який підхід до кастомізації

Ключові технічні висновки

• index.php є обов’язковим. Кожна тема повинна його включати. Це універсальний відкат, що завершує кожен ланцюжок вирішення.
• singular.php — це недооцінений проміжний рівень. Він перехоплює будь-який окремий запис або сторінку, коли не існує ні single.php, ні page.php. Використовуйте його в мінімальних темах для зменшення кількості файлів.
• front-page.php перевизначає все для головної сторінки, незалежно від налаштувань читання. Якщо він існує, він завантажується — завжди.
• Іменування файлів є чутливим до регістру на Linux-серверах. Category-News.php не збігатиметься, коли WordPress шукає category-news.php. Це тихий збій, який важко налагодити без Query Monitor.
• Фільтр template_include є головним перевизначенням. Він спрацьовує після завершення всього вирішення ієрархії та дає вам останню можливість замінити будь-який шаблон з будь-якої причини.
• Блокові теми зберігають шаблони як HTML, а не PHP. Логіка ієрархії ідентична, але формат файлів та структура директорій принципово відрізняються від класичних тем.
• functions.php дочірньої теми завантажується на додаток до батьківського, а не замість нього. Всі інші файли шаблонів дотримуються стандартного патерну перевизначення.
• Налаштування OPcache важливе при масштабуванні. На сайтах з великим трафіком переконайтеся, що opcache.max_accelerated_files перевищує загальну кількість PHP-файлів у вашій інсталяції WordPress, включаючи всі файли шаблонів теми.
• Шаблони WooCommerce знаходяться поза ієрархією WordPress. Вони вимагають окремого робочого процесу перевизначення через піддиректорію woocommerce/ у вашій темі.
• Поєднайте роботу з кастомізацією шаблонів з правильно налаштованим доменом та Реєстрацією домену, щоб забезпечити узгодженість канонічних URL на всіх сторінках, відображених шаблонами.

FAQ

Що відбувається, якщо WordPress не може знайти жодного файлу шаблону в ієрархії?

WordPress завжди знаходить index.php, оскільки він є обов’язковим для кожної дійсної теми. Якщо index.php відсутній, WordPress видає фатальну помилку та відображає порожню сторінку або помилку сервера. Це єдиний файл шаблону, відсутність якого повністю ламає сайт.

Чи можу я використовувати ієрархію шаблонів у плагіні без зміни активної теми?

Так. Використовуйте фільтр _{$type}_template_hierarchy для додавання шляху до директорії плагіна на початок масиву кандидатів до виконання locate_template(), або використовуйте template_include для заміни вирішеного шляху до шаблону після вирішення. Саме так WooCommerce, bbPress та більшість великих плагінів впроваджують власні шаблони без необхідності змінювати теми.

Чому front-page.php перевизначає мій індекс блогу, навіть коли я встановив «Останні записи» в налаштуваннях читання?

Тому що front-page.php має безумовний пріоритет для головної сторінки у всіх конфігураціях читання. Якщо ви хочете, щоб індекс блогу використовував home.php, перейменуйте або видаліть front-page.php з вашої теми. Всередині front-page.php використовуйте is_home() для визначення того, чи є головна сторінка також індексом блогу, та відображайте відповідно.

Як дізнатися, який файл шаблону WordPress зараз використовує для конкретної сторінки?

Встановіть плагін Query Monitor. Він відображає вирішений шлях до шаблону та повну ієрархію кандидатів у панелі адміністративної панелі інструментів при кожному завантаженні сторінки. Крім того, додайте тимчасовий фільтр template_include, що виводить шлях як HTML-коментар, видимий лише адміністраторам.

Чи однаково працює ієрархія шаблонів у WordPress Multisite?

Логіка вирішення для кожного сайту є ідентичною. Кожен сайт вирішує шаблони відносно власної активної теми. Різниця полягає на рівні мережі: плагіни, активовані на рівні мережі, можуть використовувати хуки фільтрів для впровадження спільних шаблонів на всіх сайтах, а функція get_stylesheet_directory() повертає правильний шлях для активної теми кожного окремого сайту, а не спільний мережевий шлях.