Avril 2024 : sortie de WordPress 6.5. Quatre mois plus tard, la montée de version est enfin planifiée sur un site resté prudemment sur WordPress 6.4 — et l’écran devient intégralement blanc à peine la mise à jour terminée, avec au journal d’erreurs la ligne Fatal error: Uncaught TypeError: wp_trim_words(): Argument #1 ($text) must be of type string, WP_Post given, called in wp-content/themes/mon-theme/functions.php on line 156. Une seule ligne de functions.php, écrite plusieurs années auparavant et jamais retouchée depuis, en est la cause exacte.
Ce diagnostic couvre précisément ce type d’erreur fatale liée à un typage plus strict introduit dans WordPress 6.5 ; il ne traite ni les autres nouveautés de cette version ni la migration des extensions tierces installées sur le même site.
Le code fautif, identifié en une ligne
La fonction en cause dans functions.php générait un extrait personnalisé pour les articles liés, en passant directement l’objet WP_Post à wp_trim_words() plutôt que son contenu textuel :
// Ligne 156 de functions.php, code fautif
function mon_theme_extrait_personnalise( $post ) {
return wp_trim_words( $post, 20, '…' );
}Ce code fonctionnait sans erreur sur les versions antérieures de WordPress, car wp_trim_words(), en interne, appliquait une conversion de type implicite avant de traiter la valeur reçue, sans vérification stricte du type déclaré. WordPress 6.5 a resserré la signature de plusieurs fonctions internes historiquement permissives, dont celle-ci, en leur ajoutant une déclaration de type stricte sur leurs paramètres — un objet WP_Post transmis là où une chaîne de caractères est attendue provoque désormais une erreur fatale immédiate, plutôt qu’un comportement dégradé silencieux.
Diagnostic : comprendre pourquoi ça marchait « avant »
Le point important à comprendre ici n’est pas que le code était historiquement correct et que WordPress aurait introduit une régression : le code était déjà erroné dans son intention (passer un objet là où un texte est attendu), simplement toléré par un typage plus permissif des versions précédentes. Le message d’erreur de WordPress 6.5 rend visible une erreur qui existait silencieusement depuis l’écriture initiale de cette fonction.
Trois questions permettent de confirmer ce diagnostic avant de corriger :
- La fonction citée dans l’erreur (
wp_trim_words()) a-t-elle vu sa signature évoluer dans le journal des modifications de WordPress 6.5 ? - Le paramètre réellement transmis correspond-il bien à ce que le message d’erreur indique (ici, un objet
WP_Postcomplet plutôt qu’une chaîne) ? - Cette même fonction est-elle appelée ailleurs dans le thème avec le même défaut, qui n’aurait pas encore déclenché d’erreur faute d’avoir été exécuté depuis la montée de version ?
Sur ce projet, une recherche complémentaire dans le thème a révélé un second appel similaire, dans un widget de blog moins fréquemment affiché, qui n’avait simplement pas encore été sollicité depuis la montée de version au moment du premier signalement.
Correctif
La correction extrait le contenu textuel de l’article avant de le transmettre à wp_trim_words(), en utilisant les fonctions prévues à cet effet plutôt qu’en contournant la vérification de type par un transtypage forcé :
// Correctif : extraire le contenu texte avant de le transmettre
function mon_theme_extrait_personnalise( $post ) {
$contenu = get_the_excerpt( $post );
if ( empty( $contenu ) ) {
$contenu = wp_strip_all_tags( get_post_field( 'post_content', $post ) );
}
return wp_trim_words( $contenu, 20, '…' );
}Cette version privilégie get_the_excerpt(), qui accepte directement un objet WP_Post ou un identifiant et renvoie systématiquement une chaîne de caractères, avec un repli sur le contenu complet nettoyé de ses balises si aucun extrait n’a été saisi manuellement pour l’article.
Ce qu’il ne fallait pas faire
Une tentation fréquente face à ce type d’erreur consiste à transtyper de force la valeur, par exemple avec (string) $post, pour faire taire l’erreur sans comprendre sa cause réelle. Ce contournement produirait ici une chaîne de caractères techniquement valide mais dénuée de sens (la représentation en chaîne d’un objet PHP n’a rien à voir avec le contenu de l’article), déplaçant le vrai problème plus loin sans jamais le résoudre.
Un TypeError qui apparaît après une montée de version WordPress signale presque toujours une erreur préexistante, révélée par un typage devenu plus strict — pas une régression du cœur lui-même.
Prévention pour les prochaines montées de version
Consulter le journal des modifications (« changelog ») et les notes de mise à jour destinées aux développeurs, publiées à chaque nouvelle version majeure de WordPress, permet d’anticiper ce type de resserrement de typage avant qu’il ne se manifeste en production. Tester la montée de version sur un environnement de recette avec le mode de débogage WordPress activé (WP_DEBUG et WP_DEBUG_LOG) fait remonter ces erreurs avant qu’elles n’atteignent les visiteurs du site en production.
En résumé
Une seule ligne de code, écrite des années auparavant avec une erreur de type restée invisible, a suffi à provoquer un écran blanc total après la montée vers WordPress 6.5. Le correctif — extraire correctement le contenu textuel avant de le transmettre à la fonction concernée — ne prend que quelques minutes une fois la cause identifiée, mais souligne l’intérêt de toujours tester une montée de version majeure sur un environnement de recette avant la production.
