Modifier directement la balise <title> dans le fichier header.php d’un thème produit le résultat voulu à court terme, mais ce changement disparaît à la prochaine mise à jour du thème si celui-ci n’est pas un thème enfant correctement structuré. Passer par le filtre prévu par le cœur pour ce besoin évite ce problème, et fonctionne quel que soit le thème actif.
La fonction concernée est wp_get_document_title(), qui a remplacé l’ancienne wp_title() depuis WordPress 4.4. Elle construit le titre de la page en assemblant plusieurs éléments — titre du contenu, nom du site, éventuellement le numéro de page — puis expose un filtre pour ajuster chacune de ces parties.
Comment le titre est assemblé
wp_get_document_title() ne prend aucun paramètre et retourne directement la chaîne finale prête à être insérée dans la balise <title>. En coulisses, elle appelle le filtre document_title_parts, qui reçoit un tableau associatif avec des clés comme title, page et site, avant de les assembler avec un séparateur configurable via le filtre document_title_separator.
Un thème compatible avec les fonctionnalités modernes du cœur n’a d’ailleurs pas besoin d’appeler explicitement cette fonction dans son gabarit : la prise en charge automatique du titre de document, activée via add_theme_support( 'title-tag' ), insère elle-même la balise complète dans <head> en s’appuyant sur ce même mécanisme.
Personnaliser le titre d’une page de résultats de recherche
Comparons deux approches pour un besoin fréquent : afficher le nombre de résultats trouvés directement dans le titre de l’onglet lors d’une recherche sur le site. La première consisterait à repérer et modifier la ligne correspondante dans header.php du thème. La seconde, plus robuste, passe par le filtre document_title_parts :
add_filter( 'document_title_parts', function ( $titre_parties ) {
if ( is_search() ) {
global $wp_query;
$nombre_resultats = (int) $wp_query->found_posts;
$titre_parties['title'] = sprintf(
/* translators: 1 : terme recherché, 2 : nombre de résultats */
__( 'Recherche « %1$s » — %2$d résultat(s)', 'recherche-personnalisee' ),
get_search_query(),
$nombre_resultats
);
}
return $titre_parties;
} );
Ce code fonctionne quel que soit le thème actif, survit à une mise à jour du thème, et reste actif même si l’administrateur du site change de thème par la suite — contrairement à une modification directe du fichier de gabarit.
Deux approches, un seul résultat durable
| Approche | Survit à une mise à jour du thème | Fonctionne après changement de thème |
|---|---|---|
| Modifier directement header.php | Non, sauf thème enfant | Non |
| Filtre document_title_parts | Oui | Oui |
Ce que ce filtre ne couvre pas
Cet article se limite volontairement au titre affiché dans l’onglet du navigateur et repris par les moteurs de recherche comme titre de résultat par défaut. Les balises meta de description, les données structurées ou les balises Open Graph relèvent d’un mécanisme entièrement différent, généralement pris en charge par une extension de référencement dédiée plutôt que par ce filtre.
document_title_partsajuste les morceaux du titre avant assemblage.document_title_separatorajuste uniquement le caractère séparateur entre les morceaux.- Aucun des deux ne touche aux balises meta présentes dans
<head>, qui restent un sujet distinct.
Tester le résultat sans se fier uniquement à l’onglet
Avant de considérer ce filtre comme validé, mieux vaut consulter le code source généré par la page plutôt que de se fier uniquement à l’intitulé affiché dans l’onglet du navigateur : certaines extensions de référencement remplacent le titre plus tard dans le cycle de requête, via leur propre filtre appliqué après document_title_parts, ce qui peut masquer un résultat pourtant correct à ce stade.
En résumé
wp_get_document_title() et son filtre document_title_parts offrent un point d’ajustement du titre de page qui ne dépend d’aucun fichier de thème particulier. Pour un besoin ponctuel — afficher un nombre de résultats, distinguer un type de contenu précis, adapter le titre selon un contexte métier — ce filtre évite une modification fragile du gabarit et reste valide même si le thème change plus tard.
