# « « Écran blanc » à l’activation : une boucle d’inclusion épuise la mémoire »

> Symptôme, diagnostic et correctif pour un thème qui provoque un écran blanc silencieux au moment de son activation, cause d'une boucle d'inclusion de fichiers qui épuise la mémoire allouée à PHP.

- Auteur : WordPress Développement
- Publié le : 2024-03-20
- Mis à jour le : 2024-03-20
- Catégorie : Thèmes
- URL : https://www.wpmoderne.fr/themes/ecran-blanc-activation-boucle-inclusion-memoire/

## L’essentiel

- Une boucle d'inclusion entre deux fichiers du thème consomme la mémoire sans erreur immédiate
- WP_DEBUG_LOG révèle une erreur Allowed memory size exhausted
- Un require_once mal placé est la cause la plus fréquente de ce type de boucle

« Fatal error: Allowed memory size of 268435456 bytes exhausted » : ce message, quand il apparaît, ne s'affiche pas nécessairement à l'écran du visiteur, WordPress masquant par défaut les erreurs PHP en production. Le site présente alors un simple écran blanc, sans contenu, sans message, exactement au moment où le thème vient d'être activé depuis l'administration.

Ce symptôme, presque toujours interprété à tort comme une limite de mémoire trop basse à augmenter, cache en réalité une cause plus précise dans un nombre significatif de cas : une boucle d'inclusion entre deux fichiers du thème, chacun chargeant l'autre indéfiniment jusqu'à épuiser toute la mémoire disponible pour le processus PHP.

## Symptôme : un écran blanc immédiatement après activation

Le thème s'active sans message d'erreur visible dans l'écran d'administration, mais toute tentative d'accès au site, y compris à l'administration elle-même, se solde par une page blanche. Aucune requête ne semble aboutir, et le comportement persiste même après avoir vidé un éventuel cache de page.

## Diagnostic : activer la journalisation pour révéler l'erreur masquée

La première étape consiste à activer la journalisation des erreurs sans les afficher à l'écran, ce qui permet d'obtenir le message exact sans exposer d'information technique à un visiteur :

```
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
```

Le fichier `wp-content/debug.log` révèle alors un message du type `PHP Fatal error: Allowed memory size of 268435456 bytes exhausted (tried to allocate 20480 bytes) in .../functions.php on line 42`. Le numéro de ligne indiqué correspond presque toujours à un appel `require` ou `include`, pas à une boucle `foreach` ou `while` classique.

> L'essentiel à retenir : Une boucle d'inclusion entre deux fichiers du thème consomme la mémoire sans erreur immédiate ; WP_DEBUG_LOG révèle une erreur Allowed memory size exhausted ; Un require_once mal placé est la cause la plus fréquente de ce type de boucle

## La cause fréquente : deux fichiers qui s'incluent mutuellement

Le scénario typique implique un fichier `functions.php` qui inclut un fichier `inc/personnalisations.php`, lequel, par erreur de copier-coller ou par une mauvaise résolution de chemin relatif, inclut à son tour `functions.php` :

```
// functions.php
require_once get_template_directory() . '/inc/personnalisations.php';

// inc/personnalisations.php, par erreur
require_once dirname( __DIR__ ) . '/functions.php';
```

Chaque inclusion réexécute l'ensemble du fichier concerné, qui relance à son tour l'inclusion du premier, sans jamais atteindre de condition d'arrêt. La pile d'appels grossit à chaque itération jusqu'à ce que la limite de mémoire allouée par PHP, définie par la directive `memory_limit`, soit atteinte, provoquant l'arrêt brutal du script.

## Correctif : rompre la boucle avec require_once et une vérification de constante

La solution immédiate consiste à retirer l'inclusion erronée dans le fichier secondaire. Pour se prémunir d'une récidive, même en cas d'erreur future de copier-coller, une vérification de constante déjà définie évite qu'un fichier ne se recharge lui-même :

```
// En haut de functions.php
if ( defined( 'MON_THEME_FUNCTIONS_CHARGE' ) ) {
    return;
}
define( 'MON_THEME_FUNCTIONS_CHARGE', true );
```

L'utilisation systématique de `require_once` plutôt que `require` réduit également le risque, puisque PHP ignore une seconde tentative de chargement du même fichier physique identifié par son chemin absolu résolu — un garde-fou utile, mais qui ne protège pas contre deux fichiers distincts qui s'incluent mutuellement l'un l'autre par des chemins différents.

## Prévention : structurer les inclusions dans un seul sens

La bonne pratique consiste à organiser les fichiers d'un thème selon une hiérarchie d'inclusion à sens unique, où `functions.php` inclut des fichiers spécialisés, mais où ces derniers ne rechargent jamais `functions.php` ni aucun fichier situé plus haut dans la hiérarchie. Un schéma d'inclusion en arbre, jamais en cycle, élimine structurellement ce risque.

- Vérifier chaque nouveau `require` ou `include` ajouté à un fichier déjà inclus ailleurs.
- Activer `WP_DEBUG_LOG` sur l'environnement de développement dès l'apparition d'un écran blanc.
- Documenter la hiérarchie d'inclusion prévue du thème pour éviter qu'un futur ajout ne l'inverse par erreur.

## En résumé

Un écran blanc à l'activation d'un thème, sans message visible, mérite une vérification immédiate du fichier `debug.log` avant toute hypothèse sur la mémoire allouée par l'hébergeur. Une boucle d'inclusion entre deux fichiers du thème reste l'une des causes les plus fréquentes et les plus faciles à corriger une fois identifiée, à condition de remonter jusqu'au numéro de ligne exact indiqué par le message d'erreur.