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

> Avant le premier hook connu, plusieurs fichiers d'un thème hybride s'exécutent déjà dans un ordre précis. Le connaître évite bien des hooks placés au mauvais moment.

- Auteur : WordPress Développement
- Publié le : 2023-07-11
- Mis à jour le : 2023-07-11
- Catégorie : Éditeur de site (FSE)
- URL : https://www.wpmoderne.fr/fse/cycle-chargement-theme-hybride-fichier-premier/

## L’essentiel

- functions.php se charge avant que le type de template soit déterminé
- theme.json est lu tôt, mais appliqué plus tard dans le rendu
- Un hook mal placé s'exécute avant que ses dépendances existent

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

> L'essentiel à retenir : functions.php se charge avant que le type de template soit déterminé ; theme.json est lu tôt, mais appliqué plus tard dans le rendu ; Un hook mal placé s'exécute avant que ses dépendances existent

`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.