do_shortcode PHP WordPress : guide complet pour utiliser les shortcodes en PHP

Sommaire de l'article

Introduction

Le monde du développement web est en constanteévolution, et WordPress ne fait pas exception à cette règle. Avec plus de 40 % des sites web mondiaux reposant sur ce CMS, il est essentiel de maîtriser les fonctionnalités avancées qu’il propose pour créer des sites performants, flexibles et faciles à maintenir.

Parmi ces fonctionnalités, les shortcodes WordPress occupent une place centrale. Ils permettent d’ajouter des fonctionnalités dynamiques ou du contenu complexe dans vos pages, articles, widgets ou zones de template, sansécrire directement du code PHP ou HTML dans l’éditeur de contenu.

La fonction PHP do_shortcode joue un rôle clé : elle permet d’exécuter un shortcode depuis vos fichiers PHP (thèmes, plugins, gabarits personnalisés) et donc d’utiliser la puissance des shortcodes partout dans votre site, bien au-del à du seuléditeur de contenu.

Dans ce guide professionnel et détaillé, vous allez découvrir :

Ce qu’est un shortcode et comment il fonctionne dans WordPress
Comment utiliser do_shortcode en PHP dans vos thèmes et plugins
Des exemples de code concrets et modernes
Les bonnes pratiques de performance, de sécurité et de maintenance
Les erreurs courantes àéviter et des alternatives plus performantes lorsque c’est possible

Si vous souhaitez améliorer votre expertise en développement WordPress, en PHP et en SEO technique, ce guide sur do_shortcode PHP WordPress vous donnera une base solide et opérationnelle.

Concepts clés : shortcodes et do_shortcode en PHP

Qu’est-ce qu’un shortcode WordPress ?

Un shortcode est un raccourci entre crochets, par exemple [gallery] ou [contact-form-7 id="123"], que WordPress interprète pour générer du contenu dynamique ou une fonctionnalité particulière. Au lieu d’insérer un long code HTML ou PHP, l’éditeur de contenu ne contient qu’un petit bloc très lisible.

Concrètement, un shortcode est relié à une fonction PHP (callback) enregistrée via add_shortcode. Lorsque WordPress rencontre le shortcode dans le contenu, il exécute la fonction associée et remplace le shortcode par le HTML généré.

À quoi sert do_shortcode en PHP ?

La fonction do_shortcode permet de forcer l’exécution d’un shortcode à partir d’une chaîne de caractères en PHP. Elle est particulièrement utile lorsque vous voulez :

Afficher un shortcode dans un fichier de thème (par exemple header.php, footer.php, single.php, page.php…)
Utiliser un shortcode dans un template de page personnalisée
Insérer un shortcode dans un widget texte ou un hook via du code PHP
Générer dynamiquement une chaîne contenant un shortcode puis l’interpréter

La forme générale est la suivante :

WordPress scanne la chaîne pour détecter les shortcodes, exécute la ou les fonctions associées, puis retourne le résultat HTML.

Différence entre shortcode dans l’éditeur et do_shortcode en PHP

Sans do_shortcode, les shortcodes sont traités uniquement dans certains contenus filtrés par WordPress : articles, pages, champs personnalisés, widgets texte (lorsqu’autorisés), etc. En revanche, dans un fichier de template PHP, si vousécrivez simplement [mon_shortcode], WordPress ne l’interprétera pas.

En utilisant do_shortcode, vous pouvez :

Insérer un shortcode où vous le souhaitez dans la structure de votre thème
Contrôler précisément la logique d’affichage avec des conditions PHP
Réutiliser les fonctionnalités de plugins basés sur des shortcodes dans vos propres gabarits

Créer un shortcode en PHP dans WordPress

Exemple simple : afficher la date actuelle

Voici un exemple de shortcode qui affiche la date actuelle dans un format lisible :

function display_current_date { return date('j F Y'); } add_shortcode('current_date', 'display_current_date');

En ajoutant ce code dans le fichier functions.php de votre thème enfant ou dans un plugin personnalisé, vous pouvez ensuite insérer [current_date] dans vos contenus pour afficher la date du jour.

Où placer le code de vos shortcodes ?

Pour une bonne maintenance, il est recommandé de :

Utiliser un thème enfant plutôt que le thème parent, afin d’éviter de perdre vos modifications lors des mises à jour
Ou mieux encore, créer un plugin dédié à vos fonctionnalités (mu-plugin ou plugin classique) pour séparer la logique métier de la présentation

Évitez de multiplier les définitions de shortcodes dans plusieurs fichiers dispersés. Centraliser leur définition améliore la lisibilité et la maintenance.

Shortcode avec attributs (paramètres)

Les shortcodes acceptent souvent des paramètres, par exemple [bouton url="https://example.com" label="Cliquez ici"]. Au lieu d’utiliser extract (désormais déconseillé), privilégiez une approche plus claire :

function secure_shortcode_example( $atts ) { $atts = shortcode_atts( array( 'param1' => 'valeur_par_defaut', 'param2' => 'autre_valeur', ), $atts, ); $param1 = sanitize_text_field( $atts['param1'] ); $param2 = sanitize_text_field( $atts['param2'] ); return 'Résultat du shortcode avec param1 : ' . esc_html( $param1 ) . ' et param2 : ' . esc_html( $param2 ); } add_shortcode('secure_example', 'secure_shortcode_example');

Cette version est plus moderne, plus sûre et plus lisible que l’utilisation de extract.

Utiliser do_shortcode dans vos fichiers PHP WordPress

Sintaxe de base de do_shortcode

La syntaxe minimale est :

Quelques points importants :

La chaîne passée à do_shortcode doit contenir le shortcode complet, y compris les crochets [ ]
Pensez à utiliser echo si vous voulez afficher le résultat directement dans le HTML
Vous pouvez combiner du texte statique et des shortcodes dans une même chaîne, si nécessaire

Exemples concrets d’utilisation dans un thème

1. Afficher un formulaire de contact dans le footer

Supposons que vous utilisiez un plugin de formulaire qui fournit un shortcode du type [contact-form-7 id="123" title="Formulaire de contact"]. Pour l’afficher dans le footer de votre site depuis footer.php :

echo do_shortcode('[contact-form-7 id="123" title="Formulaire de contact"]'); ?>

2. Utiliser un shortcode conditionnellement

Vous pouvez conditionner l’affichage d’un shortcode à un type de contenu, une catégorie ou un rôle utilisateur, en combinant PHP et do_shortcode :

if ( is_single && has_category('tutoriels') ) { echo do_shortcode('[current_date]'); } ?>

3. Intégrer un shortcode dans un hook

Vous pouvezégalement utiliser do_shortcode dans des fonctions reliées à des hooks d’action ou de filtre :

function my_custom_banner_after_header { echo '

';

   echo do_shortcode('[secure_example param1="Bonjour" param2="Monde"]');

   echo '

';

}

add_action('wp_head', 'my_custom_banner_after_header');

Bonnes pratiques pour do_shortcode et les shortcodes

Performance : limiter l’usage abusif de do_shortcode

La fonction do_shortcode est pratique, mais elle a un coût en performances. À chaque appel, WordPress doit analyser la chaîne fournie, rechercher tous les shortcodes enregistrés et exécuter la fonction correspondante. Sur un site avec de nombreux shortcodes et plusieurs appels à do_shortcode dans un même chargement de page, cela peut pénaliser le temps de réponse.

Quelques recommandations pour optimiser la performance :

Évitez d’appeler do_shortcode à l’intérieur de boucles très fréquentes (comme la boucle principale pour chaque article d’un listing)
Ne placez pas de do_shortcode exécuté des dizaines de fois dans le header ou des zones visibles sur toutes les pages, sauf si nécessaire
Privilégiez, lorsque c’est possible, l’appel direct à la fonction PHP associée au shortcode plutôt qu’à do_shortcode
Utilisez des mécanismes de cache (transients, cache d’objets, plugins de cache) pour les shortcodes lourds qui ne changent pas souvent

Alternative performante : appeler directement la fonction PHP

Beaucoup de plugins fournissent à la fois un shortcode et une fonction PHP (ou un tag de template). Dans ce cas, il est généralement plus performant de faire appel directement à la fonction PHP au lieu de passer par do_shortcode, car celaévite tout le mécanisme de parsing des shortcodes.

Par exemple, si un shortcode est enregistré ainsi :

add_shortcode( 'cy', 'jr_cy_cy' );

Vous pouvez, dans un template, au lieu de :

echo do_shortcode('[cy]');

simplement utiliser :

echo jr_cy_cy;

Le résultat HTML sera identique, mais avec moins de traitement en arrière-plan.

Sécuriser vos shortcodes

Les shortcodes sont souvent utilisés pour afficher des données provenant de l’utilisateur (formulaires, paramètres, contenus dynamiques) ou de sources externes. Pouréviter les problèmes de sécurité (injection XSS, données non filtrées, etc.), pensez à :

Valider systématiquement les paramètres reçus dans $atts
Sanitiser les données avant traitement avec les fonctions WordPress appropriées (sanitize_text_field, esc_url_raw, etc.)
Échapper les données avant affichage avec esc_html, esc_attr, esc_url…
Éviter l’exécution de code arbitraire à partir des paramètres utilisateur

Structurer et documenter vos shortcodes

Pour que votre base de code reste maintenable, surtout sur des sites complexes ou des projets d’agence :

Regroupez vos shortcodes dans un ou plusieurs fichiers dédiés (par exemple inc/shortcodes.php)
Documentez chaque shortcode (description, paramètres, exemples d’utilisation)
Utilisez des noms de shortcodes clairs et cohérents, évitez les collisions avec d’autres plugins
Ajoutez des commentaires PHPDoc aux fonctions de callback

Exemples avancés de do_shortcode en contexte réel

Shortcode pour une liste d’articles personnalisée

Imaginons un shortcode qui affiche les trois derniers articles d’une catégorie donnée. Vous pouvez ensuite le réutiliser avec do_shortcode dans différents templates.

function latest_posts_by_category_shortcode( $atts ) { $atts = shortcode_atts( array( 'category' => '', 'posts_per_page' => 3, ), $atts, ); $category = sanitize_text_field( $atts['category'] ); $posts_per_page = (int) $atts['posts_per_page']; $query_args = array( 'posts_per_page' => $posts_per_page, 'post_status' => 'publish', ); if ( ! empty( $category ) ) { $query_args['category_name'] = $category; } $query = new WP_Query( $query_args ); if ( ! $query->have_posts ) { return '

Aucun article trouvé.

';

   }


   ob_start;

   echo '';

   while ( $query->have_posts ) {

      $query->the_post;

      echo '' . esc_html( get_the_title ) . '
';

   }

   echo '
';

   wp_reset_postdata;


   return ob_get_clean;

}


add_shortcode( 'latest_posts_by_category', 'latest_posts_by_category_shortcode' );

Vous pouvez ensuite appeler ce shortcode :

Dans l’éditeur de contenu : [latest_posts_by_category category="tutoriels" posts_per_page="5"]
Dans un template PHP :

Combiner do_shortcode et blocs Gutenberg

Sur les sites modernes qui utilisent pleinement l’éditeur de blocs, il est parfois plus judicieux de recourir à des blocs personnalisés plutôt qu’à des shortcodes. Cependant, de nombreux plugins historiques fonctionnent toujours via shortcodes. do_shortcode permet alors de :

Insérer des shortcodes dans des patterns de blocs (modèles réutilisables)
Afficher du contenu basé sur des shortcodes dans des parties de modèle (template parts) utilisées par le système de thèmes en blocs

Dans ce contexte, veillez à planifier une transition progressive vers des blocs pour les fonctionnalités les plus critiques, tout en continuant à utiliser do_shortcode pour assurer la compatibilité.

Outils et ressources utiles autour de do_shortcode et des shortcodes

Outils pour développer et déboguer vos shortcodes

Un IDE PHP moderne (PHPStorm, VS Code, etc.) : indispensable pour bénéficier de l’autocomplétion, de l’analyse statique et du refactoring, surtout lorsque vos shortcodes deviennent nombreux et complexes.
Xdebug : une extension PHP très utile pour déboguer les fonctions de callback de vos shortcodes, comprendre les performances et suivre le flux d’exécution.
Environnement de développement local : outils comme Local, DevKinsta, Wamp, Mamp ou Docker permettent de tester vos shortcodes et l’usage de do_shortcode sans impacter votre site de production.

Plugins liés aux shortcodes

De nombreux plugins majeurs utilisent des shortcodes pour exposer leurs fonctionnalités :

Contact Form 7 : fournit des shortcodes pour insérer des formulaires de contact n’importe où dans votre site, y compris via do_shortcode dans des templates.
Plugins de formulaires avancés (Gravity Forms, Ninja Forms, WPForms, etc.) : chacun propose des shortcodes pour afficher des formulaires, que vous pouvezégalement appeler via do_shortcode ou via des fonctions PHP spécifiques.
Plugins de galerie, sliders, LMS, boutiques en ligne : la plupart offrent des shortcodes pour intégrer leurs composants dans vos pages, et donc utilisables dans du code PHP.

Outils de suivi et d’optimisation

Google Search Console : permet de surveiller l’impact de vos contenus dynamiques sur le référencement, d’identifier les problèmes d’indexation et d’optimiser la visibilité globale de votre site.
Outils d’analyse de performance (PageSpeed Insights, Lighthouse, plugins de cache) : utiles pour mesurer l’impactéventuel de shortcodes complexes exécutés via do_shortcode et ajuster votre stratégie (caching, refactorisation, appel direct de fonctions).

do_shortcode, SEO et expérience utilisateur

Impact indirect sur le SEO

La fonction do_shortcode n’a pas d’impact direct sur le référencement dans les moteurs de recherche, mais elle influe sur des facteurs importants :

Temps de chargement : des shortcodes lourds ou appelés trop souvent via do_shortcode peuvent ralentir vos pages. Or, la vitesse de chargement est un critère de plus en plus important pour le SEO et l’expérience utilisateur.
Qualité du contenu : les shortcodes servent souvent à structurer ou enrichir le contenu (galeries, tableaux, formulaires, listes d’articles). Bien utilisés, ils améliorent la lisibilité et l’engagement, ce qui peut favoriser de meilleurs signaux utilisateurs.
Maintenance et cohérence : une bonne organisation de vos shortcodes et de l’usage de do_shortcode facilite la mise à jour des contenus, la correction d’erreurs et l’amélioration continue de vos pages clés.

Bonnes pratiques SEO autour de do_shortcode

Évitez les shortcodes qui génèrent du contenu très léger ou peu pertinent, uniquement pour « remplir » une page.
Veillez à ce que le HTML généré par vos shortcodes soit sémantique (titres, listes, paragraphes structurés).
Testez régulièrement vos pages importantes pour vous assurer que les shortcodes s’affichent bien et ne cassent pas la structure (erreurs de balises, problèmes d’accessibilité).
Surveillez les performances de vos pages clés et, si nécessaire, remplacez des shortcodes lourds par des blocs, des fonctions PHP directes ou des solutions plus légères.

Erreurs courantes àéviter avec do_shortcode

1. Surutilisation de do_shortcode dans tout le thème

Insérer systématiquement des shortcodes via do_shortcode dans tous les templates, widgets et hooks peut rapidement rendre le site difficile à maintenir et ralentir le chargement des pages. Utilisez cette fonction lorsque cela apporte une réelle valeur (réutilisation d’un composant, meilleure flexibilité, etc.).

2. Ne pas vérifier si le shortcode existe

Si un plugin est désactivé ou supprimé, les shortcodes qu’il déclarait ne seront plus disponibles. Appeler un shortcode inexistant via do_shortcode peut produire un rendu inattendu. Vous pouvez ajouter une vérification :

if ( shortcode_exists( 'mon_shortcode' ) ) { echo do_shortcode('[mon_shortcode]'); }

3. Utiliser extract dans les callbacks

extract est encore visible dans de vieux exemples de code, mais il est déconseillé car il peut créer des variables de manière implicite et nuire à la lisibilité et à la sécurité. Préférez l’accès explicite aux clés du tableau $atts et l’utilisation de shortcode_atts comme montré plus haut.

4. Mélanger trop de logique dans le shortcode

Un shortcode doit idéalement se concentrer sur une tâche bien définie (afficher un bloc de contenu, une liste d’éléments, un formulaire, etc.). Si la fonction de callback contient une logique métier très complexe, pensez à extraire cette logique dans des fonctions PHP dédiées, puis à garder le shortcode comme une « façade » vers ces fonctions.

5. Oublier la compatibilité avec les thèmes et les blocs

Sur un site moderne, le même contenu peutêtre affiché dans différents contextes (thèmes classiques, thèmes blocs, éditeur complet du site). Veillez à ce que vos shortcodes et votre usage de do_shortcode fonctionnent correctement quelle que soit la structure du thème. Testez vos shortcodes sur plusieurs gabarits (pages, articles, archives, modèles personnalisés).

Résumé opérationnel : bien utiliser do_shortcode PHP WordPress

Pour exploiter pleinement do_shortcode PHP WordPress dans vos projets :

Créez des shortcodes clairs, sécurisés, bien documentés et centralisés dans des fichiers dédiés
Utilisez do_shortcode dans vos fichiers PHP uniquement lorsqu’il est pertinent d’exécuter un shortcode à cet endroit
Pensez performance : privilégiez l’appel direct aux fonctions PHP des plugins lorsqu’elles existent, mettez en cache les sorties lourdes etévitez les appels redondants
Assurez la sécurité en validant, nettoyant etéchappant toutes les données manipulées par vos shortcodes
Testez systématiquement l’affichage et le comportement de vos shortcodes sur les pages stratégiques de votre site

En respectant ces bonnes pratiques, do_shortcode deviendra un outil puissant pour enrichir vos thèmes et plugins WordPress, sans sacrifier ni la performance ni la qualité de l’expérience utilisateur.