do_shortcode dans WordPress : guide complet pour maîtriser les shortcodes en PHP

Introduction

Le monde de WordPress est vaste et offre une multitude de fonctionnalités pour personnaliser vos sites web. Parmi ces fonctionnalités se trouvent les shortcodes, qui permettent d’ajouter rapidement et facilement deséléments complexes à vos contenus, sansécrire de code HTML ou PHP dans l’éditeur. Pour exécuter ces shortcodes en dehors de l’éditeur de contenu, notamment dans les fichiers PHP de votre thème ou de vos plugins, la fonction do_shortcode est l’outil clé à connaître.

Dans cet article complet et professionnel, vous allez découvrir :

• Ce qu’est un shortcode et comment il fonctionne dans WordPress ;
• Le rôle précis de la fonction do_shortcode et sa syntaxe ;
• Où et comment utiliser do_shortcode dans vos thèmes et plugins ;
• Les bonnes pratiques de performance et de sécurité ;
• Les limites des shortcodes et les alternatives modernes (blocs, fonctions dédiées) ;
• Une FAQ détaillée pour répondre aux questions les plus fréquentes.

L’objectif est que vous repartiez avec une compréhension claire et opérationnelle de do_shortcode, afin de l’utiliser efficacement dans vos projets WordPress, tout enévitant les erreurs classiques qui nuisent aux performances ou à la sécurité.

Concepts clés

Qu’est-ce qu’un shortcode ?

Un shortcode est une balise simplifiée, entourée de crochets, qui permet d’insérer du contenu dynamique ou des fonctionnalités avancées dans vos pages et articles WordPress. Au lieu d’écrire un long morceau de code HTML ou PHP, vous utilisez une syntaxe compacte du type :

[gallery ids="123,456"]

Lors de l’affichage de la page, WordPress analyse le contenu, repère cette balise, puis exécute le code associé pour générer le HTML final (ici, une galerie d’images). Les shortcodes sont très utilisés pour :

• Afficher des galeries d’images ou sliders ;
• Insérer des formulaires de contact ou d’inscription ;
• Afficher des listes de produits, d’articles ou d’événements ;
• Intégrer des vidéos, cartes, boutons, colonnes, tableaux de prix, etc.

Un exemple courant avec un plugin de formulaire de contact serait :

[contact-form-7 id="123" title="Formulaire de contact"]

Inséré dans le contenu d’une page, ce shortcode sera automatiquement traduit en formulaire HTML lors de l’affichage.

Comment un shortcode est-il enregistré ?

Techniquement, un shortcode est enregistré dans WordPress via la fonction add_shortcode. Elle associe un nom de shortcode à une fonction de rappel (callback) PHP qui génère le contenu :

Ceci est un contenu généré par un shortcode personnalisé.
';
} add_shortcode( 'mon_shortcode', 'mon_shortcode_personnalise' );
?>

Quelques bonnes pratiques pour le nom du shortcode :

• Utiliser uniquement des lettres minuscules, des chiffres et des underscores ;
• Éviter les tirets dans le nom ;
• Choisir un nom suffisamment explicite pouréviter les collisions avec d’autres plugins.

Une fois le shortcode enregistré, il peutêtre appelé dans un contenu WordPress par :

[mon_shortcode]

ou en lui passant des attributs :

[mon_shortcode couleur="rouge" taille="grand"]

Fonctionnement de do_shortcode

La fonction do_shortcode joue un rôle central lorsqu’il s’agit d’exécuter des shortcodes depuis du code PHP. Elle prend une chaîne de caractères en entrée, analyse cette chaîne, détecte les shortcodes présents et remplace chaque shortcode par le contenu HTML qui lui correspond, grâce aux callbacks enregistrés avec add_shortcode.

Syntaxe générale :

Points importants :

• Type de retour : do_shortcode retourne une chaîne de caractères contenant le texte transformé. Elle n’affiche rien par elle-même ;
• Affichage : pour voir le résultat dans la page, vous devez généralement utiliser echo ou l’insérer dans une autre chaîne ;
• Portée : seuls les shortcodes présents dans la chaîne passée en paramètre sont interprétés ;
• Shortcodes imbriqués : la fonction est capable de traiter des shortcodes imbriqués (nested shortcodes), tant qu’ils sont correctement enregistrés et bien formés.

Exemple concret : imaginons que vous ayez enregistré un shortcode [contact-form] ou que vous utilisiez un plugin de formulaire qui expose un shortcode similaire. Dans un fichier de template, vous pouvezécrire :

Lors du rendu de la page, WordPress exécutera do_shortcode, détectera [contact-form] et le remplacera par le formulaire généré par le plugin.

Définitions techniques de do_shortcode

• Fonction native WordPress : do_shortcode est une fonction intégrée au cœur de WordPress. Elle n’est pas dépréciée à ce jour et reste la méthode standard pour exécuter des shortcodes dans les fichiers PHP.
• Rôle principal : analyser une chaîne de texte à la recherche de shortcodes et les exécuter pour produire le contenu final.
• Type de retour : chaîne de caractères (string) contenant le contenu traité, prêt àêtre affiché ou manipulé.
• Paramètres :
  • $content (obligatoire) : chaîne de texte à analyser pour en extraire les shortcodes.
  • $ignore_html (optionnel) : booléen indiquant si certainséléments HTML doiventêtre ignorés lors de l’analyse. Selon la version de WordPress, ce paramètre existe mais reste peu utilisé dans les cas d’usage standards et ne doit pasêtre confondu avec une protection générale contre le HTML.
• Shortcodes imbriqués : la fonction gère de façon récursive les shortcodes imbriqués, à condition qu’ils soient correctement conçus.
• Sécurité : do_shortcode applique la logique définie par chaque shortcode. Elle n’ajoute pas automatiquement un filtrage global contre les injections. La sécurité dépend donc en grande partie du code des callbacks et de la manière dont les données sont nettoyées etéchappées.

Contrairement à ce que l’on pourrait penser, do_shortcode ne « protège » pas automatiquement contre toutes les injections de code. Elle exécute les callbacks des shortcodes enregistrés : c’est dans ces callbacks que vous devez appliquer des fonctions de nettoyage (sanitize_*) et d’échappement (esc_*).

Où et comment utiliser do_shortcode dans WordPress ?

Utilisation dans les fichiers de thème

do_shortcode peutêtre utilisée dans la plupart des fichiers PHP de votre thème :

• header.php (par exemple pour afficher un formulaire dans l’en-tête) ;
• footer.php ;
• single.php ou page.php ;
• un fichier de template personnalisé ;
• un template part inclus via get_template_part.

Exemple pour insérer un formulaire de contact dans header.php :

Avant d’ajouter ce code :

• Assurez-vous que le plugin qui fournit le shortcode est installé et activé ;
• Idéalement, travaillez dans un thème enfant pouréviter de perdre vos modifications lors des mises à jour du thème parent ;
• Effectuez une sauvegarde de vos fichiers avant toute modification.

Utilisation dans functions.php et dans vos propres fonctions

Vous pouvezégalement utiliser do_shortcode au sein de vos propres fonctions, notamment dans functions.php ou dans un plugin personnalisé. Par exemple, pour afficher un shortcode dans une zone bien précise d’un template ou d’un hook :

Vous pouvez ensuite appeler mon_contenu_avec_shortcode dans un template, un hook ou un widget personnalisé.

Utilisation dans les widgets et zones dynamiques

Dans certains contextes (widgets texte, champs personnalisés, options de thème), WordPress ne traite pas toujours automatiquement les shortcodes. Lorsque vous développez un widget ou un module personnalisé, vous pouvez explicitement appliquer do_shortcode au contenu :

De cette façon, les shortcodes placés dans le contenu de ce widget seront exécutés correctement.

Limites importantes de do_shortcode

Il est essentiel de comprendre ce que do_shortcode ne fait pas :

• Elle ne transforme pas « magiquement » tout le site : seuls les shortcodes présents dans la chaîne fournie sont interprétés.
• Elle ne remplace pas le besoin d’enregistrer les shortcodes : si aucun shortcode portant ce nom n’aété enregistré via add_shortcode (ou par un plugin), rien ne sera exécuté.
• Elle ne garantit pas la sécurité des données : la validation et la sanitation doiventêtre gérées dans les callbacks des shortcodes.
• Elle ne résout pas les problèmes de mise en page : vous devrez souvent adapter le CSS de votre thème pour intégrer le contenu généré par les shortcodes.

Performance et bonnes pratiques avec do_shortcode

Impact sur les performances

Chaque appel à do_shortcode entraîne une analyse de la chaîne fournie afin d’y détecter d’éventuels shortcodes. Sur un site de petite taille, cela est généralement négligeable. En revanche, sur des pages très longues ou sur un site à fort trafic, des appels fréquents et inutiles peuvent avoir un impact mesurable sur les performances.

Quelques recommandations pratiques :

• Limiter les appels répétés : évitez d’appeler do_shortcode dans des boucles très fréquentes si ce n’est pas indispensable.
• Préférer les fonctions PHP du plugin quand c’est possible : certains plugins exposent des fonctions PHP spécifiques pour afficher un formulaire, une liste de produits, etc. Les utiliser directement peutêtre plus performant et plus clair que de passer par un shortcode.
• Mettre en place un système de cache : sur des contenus coûteux à générer, un cache (objet, page ou fragment) permet d’éviter de recalculer le rendu à chaque requête.
• Ne pas transformer tout un modèle avec do_shortcode : appliquez-le sur la portion de texte où les shortcodes sont réellement nécessaires.

Quandéviter do_shortcode ?

Dans certains cas, il est préférable de ne pas utiliser do_shortcode :

• Pour des fonctionnalités réutilisées partout dans le thème, lorsqu’une fonction PHP du plugin est disponible ;
• Dans des tâches en arrière-plan (CRON, imports massifs) où la performance est critique ;
• Dans des zones où le design doitêtre totalement contrôlé : un shortcode peut insérer du HTML difficile à styler proprement, alors qu’un appel direct à une fonction permet un balisage plus maîtrisé.

Sécurité : risques et bonnes pratiques autour des shortcodes

Risques potentiels liés aux shortcodes

Les shortcodes eux-mêmes ne sont pas dangereux par nature, mais le code exécuté derrière peut l’être s’il est malécrit. Les principaux risques sont :

• Vulnérabilités XSS (Cross-Site Scripting) : si un shortcode affiche des données provenant d’entrées utilisateur sanséchappement correct (par exemple du JavaScript injecté dans un attribut).
• Injections SQL : si les données transmises à un shortcode sont utilisées dans des requêtes SQL sans passer par les fonctions sécurisées (préparation de requêtes, échappement, etc.).
• Fuites d’information ouélévation de privilèges : si un shortcode permet d’accéder à des données sensibles sans contrôles de capacité (capabilities) suffisants.
• Plugins vulnérables : un plugin qui enregistre des shortcodes non sécurisés peut introduire des failles sur votre site.

Rôle réel de do_shortcode dans la sécurité

Il est important de corriger une idée reçue : la fonction do_shortcode ne fournit pas à elle seule un mécanisme complet de filtrage pouréviter les injections de code. Elle applique l’API de shortcodes et exécute les callbacks que vous (ou les plugins) avez déclarés.

En pratique :

• La validation, la sanitation et l’échappement doiventêtre réalisés dans le code du shortcode lui-même ;
• do_shortcode ne doit pasêtre considérée comme une barrière de sécurité, mais comme un moteur d’exécution ;
• Les bonnes pratiques de sécurité WordPress (fonctions sanitize_*, esc_*, wp_kses, capacités, nonces, etc.) restent indispensables.

Bonnes pratiques de développement sécurisé avec les shortcodes

Pour développer en toute sécurité avec do_shortcode et l’API de shortcodes :

• Nettoyez systématiquement les attributs reçus dans les callbacks à l’aide des fonctions sanitize_text_field, sanitize_email, intval, etc., selon le type de données.
• Échappez les données avant affichage avec esc_html, esc_attr, esc_url, etc.
• Contrôlez les capacités lorsque le shortcode permet d’afficher ou de modifier des données sensibles (avec current_user_can).
• Vérifiez les plugins : n’utilisez que des plugins réputés et maintenus, et tenez-les à jour.
• Évitez de permettre aux utilisateurs non de confiance de saisir librement des shortcodes si ces derniers peuvent exécuter des actions sensibles.

En résumé, do_shortcode est neutre du point de vue de la sécurité : elle exécute ce que vous lui donnez. C’est au développeur du shortcode de garantir que le code exécuté est sûr.

Bonnes pratiques générales d’utilisation de do_shortcode

Quand utiliser do_shortcode ?

Utilisez do_shortcode principalement lorsque vous avez besoin d’exécuter un shortcode :

• dans un fichier de thème (header.php, footer.php, single.php, page.php, etc.) ;
• dans un template personnalisé ou une partie de template ;
• dans une fonction ou un hook qui doit renvoyer du contenu contenant des shortcodes ;
• dans un widget ou un module personnalisé où le contenu peut contenir des shortcodes.

À l’inverse, lorsque vousêtes dans l’éditeur de contenu WordPress (éditeur classique ouéditeur de blocs), vous n’avez généralement pas besoin de do_shortcode : il suffit d’insérer directement le shortcode dans le contenu, WordPress se charge d’en faire le rendu.

Structure et lisibilité du code

Pour un code plus lisible et plus maintenable :

• Évitez d’insérer des shortcodes directement dans de longues chaînes HTML difficiles à lire.
• Stockez les shortcodes dans des variables si vous devez les manipuler ou les filtrer avant exécution.
• Commentez clairement votre code lorsqu’un shortcode est utilisé dans une zone nonévidente du template (en-tête, pied de page, sidebar, etc.).

Exemple lisible :

Shortcodes, blocs Gutenberg et alternatives modernes

Shortcodes vs blocs

Avec l’éditeur de blocs (Gutenberg), WordPress encourage progressivement l’utilisation de blocs plutôt que de shortcodes pour la plupart des fonctionnalités. Cependant :

• Les shortcodes restent largement utilisés et pleinement supportés.
• De nombreux plugins historiques continuent de fournir des shortcodes en plus (ou à la place) de blocs.
• Dans les fichiers de thème PHP, les blocs ne remplacent pas directement les shortcodes : do_shortcode reste une solution pratique pour exécuter du contenu dynamique.

Dans un contexte moderne, il est donc pertinent :

• d’utiliser les blocs pour l’édition de contenu par les utilisateurs finaux ;
• d’utiliser les shortcodes (et do_shortcode) pour les besoins plus techniques dans les thèmes et les plugins, en complément des blocs.

Alternatives à do_shortcode

Selon le cas d’usage, d’autres approches peuventêtre plus appropriées :

• Appeler directement une fonction PHP du plugin : si le plugin fournit une fonction claire pour générer le contenu (par exemple un formulaire), préférez un appel direct dans le template.
• Utiliser des hooks : dans certains cas, un hook d’action ou de filtre permet d’injecter du contenu sans passer par un shortcode.
• Créer un bloc personnalisé : pour un site orienté Gutenberg, un bloc sur mesure peutêtre plus ergonomique pour l’éditeur de contenu.

Ces alternatives peuvent améliorer la performance, la lisibilité du code et l’expérience d’édition, tout en limitant la dépendance aux shortcodes.

FAQ sur do_shortcode et les shortcodes WordPress

1. do_shortcode est-elle obsolète ?

Non. do_shortcode n’est pas dépréciée dans les versions actuelles de WordPress. Elle reste la méthode standard pour exécuter des shortcodes dans les fichiers PHP des thèmes et plugins. Même si l’écosystème se dirige davantage vers les blocs Gutenberg pour l’édition de contenu, les shortcodes et do_shortcode restent pleinement pris en charge.

2. Puis-je utiliser do_shortcode n’importe où dans WordPress ?

Vous pouvez appeler do_shortcode dans la plupart des fichiers PHP de WordPress (thèmes, plugins, widgets personnalisés, etc.), mais cela ne signifie pas que c’est toujours une bonne idée de le faire « n’importe où » sans réflexion. Vous devez vérifier :

• que le shortcode utilisé est bien enregistré (par un plugin ou par votre code) ;
• que le contexte d’exécution est approprié (par exemple, le plugin est chargé au moment de l’appel) ;
• que vous ne créez pas de problème de performance en l’appelant trop souvent.

Utiliser do_shortcode dans functions.php, dans des templates ou dans des widgets est courant, mais cela doit rester maîtrisé.

3. Pourquoi mon shortcode ne fonctionne-t-il pas avec do_shortcode ?

Les causes les plus fréquentes sont :

• Le plugin qui enregistre le shortcode n’est pas installé ou pas activé.
• Le shortcode est malécrit (nom incorrect, guillemets mal fermés, attributs mal formés).
• L’appel à do_shortcode se fait trop tôt, avant que WordPress n’ait chargé les plugins (par exemple dans un fichier exécuté avant le chargement complet de WordPress).
• Le shortcode aété désactivé ou modifié par un autre plugin.

Une bonne méthode de diagnostic consiste à tester le même shortcode directement dans une page ou un article : s’il fonctionne dans l’éditeur mais pas via do_shortcode dans un template, le problème vient probablement du contexte ou du moment où l’appel est effectué.

4. Puis-je passer des attributs à do_shortcode ?

Oui. Les attributs se passent à l’intérieur de la chaîne du shortcode, exactement comme dans l’éditeur :

Dans la fonction callback associée à ce shortcode, vous pouvez ensuite récupérer et traiter ces attributs, par exemple via shortcode_atts.

5. do_shortcode fonctionne-t-elle avec tous les plugins ?

En principe, oui, tant que le plugin enregistre correctement ses shortcodes via l’API WordPress. Cependant, certains plugins peuvent imposer des conditions particulières (chargement de scripts, initialisation spécifique, contexte de page). Si un shortcode fonctionne dans l’éditeur mais pas dans un template, consultez la documentation du plugin pour vérifier s’il existe une fonction PHP dédiée ou des recommandations spécifiques.

6. do_shortcode affiche-t-elle directement le contenu ?

Non. do_shortcode retourne une chaîne de caractères, elle n’affiche rien par défaut. Pour afficher le résultat dans un template, vous devez utiliser echo :

Dans une fonction, vous pouvez soit retourner directement la valeur de do_shortcode, soit la stocker dans une variable pour la manipuler avant de l’afficher.

Conclusion pratique

La fonction do_shortcode est un outil essentiel pour exécuter des shortcodes dans les fichiers PHP de vos thèmes et plugins WordPress. Correctement utilisée, elle vous permet d’intégrer facilement des fonctionnalités avancées (formulaires, galeries, sliders, listes dynamiques, etc.) dans vos templates, sans alourdir le code HTML.

Pour en tirer le meilleur parti :

• Assurez-vous que les shortcodes sont correctement enregistrés et que les plugins nécessaires sont activés.
• Utilisez do_shortcode avec parcimonie et réfléchissez à son impact sur la performance.
• Appliquez les bonnes pratiques de sécurité dans les callbacks des shortcodes (sanitation, échappement, contrôles de capacité).
• Combinez intelligemment shortcodes, blocs Gutenberg et fonctions PHP pour offrir une expérience moderne, performante et maintenable.

En maîtrisant ces concepts et ces bonnes pratiques, vous pourrez exploiter pleinement la puissance de do_shortcode dans WordPress, tout en garantissant un site performant, sécurisé et facile à maintenir.