Cycle de chargement d’un thème hybride : quel fichier s’exécute en premier

Un thème classique a longtemps habitué les développeurs à un repère simple : header.php se charge, puis le contenu, puis footer.php. Un thème hybride ne fonctionne pas ainsi, et savoir précisément quel fichier s’exécute en premier devient nécessaire dès qu’il faut accrocher du code au bon moment, ni trop tôt, ni trop tard.

Cette notion revient régulièrement chez les développeurs qui migrent d’un thème classique : ils cherchent l’équivalent d’un header.php à modifier, alors que la question à se poser est différente — à quelle étape du cycle de chargement leur code doit-il intervenir ?

Définition : trois phases avant le premier bloc rendu

Le chargement d’un thème hybride se déroule en trois grandes phases. D’abord, WordPress charge functions.php comme pour tout thème, au hook after_setup_theme puis init. Ensuite, il détermine la hiérarchie de template à utiliser pour la requête en cours — page d’accueil, article simple, archive — en cherchant un fichier .html correspondant dans le dossier templates. Enfin, il assemble ce template avec les template parts qu’il référence, en appliquant les réglages de theme.json sous forme de variables CSS injectées dans l’en-tête du document.

Fonctionnement interne : ce qui se passe entre les deux

functions.php s’exécute systématiquement en premier, avant même que WordPress sache quel template sera utilisé pour la requête. C’est là que doivent vivre les déclarations de support de thème, l’enregistrement des tailles d’image ou des patterns : ces éléments doivent exister avant que la résolution de template ne commence, sans quoi certains d’entre eux ne seraient tout simplement pas disponibles au moment du rendu.

theme.json est lu très tôt lui aussi, dès l’initialisation du thème, pour construire l’ensemble des réglages et des styles disponibles dans l’éditeur. Mais son application concrète — l’injection des variables CSS personnalisées dans la page rendue — n’intervient que plus tard, au moment du rendu final du template, via la fonction interne qui génère la feuille de style globale.

Où se situe le hook template_include

Le filtre template_include, familier des développeurs de thèmes classiques, existe toujours dans un thème hybride, mais il intervient après que WordPress a déjà décidé d’utiliser son propre mécanisme de résolution de template basé sur les fichiers .html. Un hook accroché à ce filtre peut inspecter la décision prise, mais il arrive trop tard pour influencer le choix des template parts qui composent ce template.

Cas d’usage : où accrocher un traitement personnalisé

Pour un traitement qui doit s’exécuter avant que le contenu ne soit assemblé — par exemple, rediriger certaines requêtes avant qu’elles n’atteignent le rendu — le hook template_redirect reste le bon endroit, comme dans un thème classique : il s’exécute après la résolution de la requête principale mais avant la génération de la sortie. Pour enrichir les données disponibles dans un bloc personnalisé, en revanche, il faut intervenir plus tôt, typiquement via init, pour que les données soient prêtes au moment où l’éditeur ou le rendu de bloc les demande.

add_action( 'init', function () {
    register_block_pattern( 'mon-theme/bandeau-promo', array(
        'title'   => __( 'Bandeau promo', 'mon-theme' ),
        'content' => '<!-- wp:paragraph --><p>Offre du mois</p><!-- /wp:paragraph -->',
    ) );
} );

Pièges les plus fréquents

• enregistrer un pattern ou une taille d’image dans un hook trop tardif, comme wp_loaded, alors que l’éditeur les demande dès init ;
• croire que modifier theme.json à l’exécution, via le filtre wp_theme_json_data_theme, produit un effet identique à une modification du fichier lui-même — c’est vrai pour le rendu, mais l’éditeur garde parfois en cache la version lue au chargement de la page ;
• oublier qu’un template part référencé dans un template .html doit exister au moment de l’assemblage : un fichier manquant ne déclenche pas d’erreur PHP visible, la zone reste simplement vide.

Quand un comportement semble incohérent dans un thème hybride, nous vérifions d’abord à quelle phase du cycle appartient le code en cause, avant de chercher un bug ailleurs : la moitié des cas se résolvent en déplaçant simplement un hook.

Ce qu’il faut retenir

Un thème hybride ne remplace pas le cycle de chargement de WordPress, il lui ajoute une étape de résolution de template basée sur des fichiers HTML plutôt que sur une simple hiérarchie de noms de fichiers PHP. Comprendre à quel moment chaque source d’information — fonctions, gabarits, styles globaux — devient disponible évite de chercher un bug là où il n’y en a pas : au mauvais endroit du cycle, un code parfaitement correct peut sembler ne jamais s’exécuter.