do_shortcode WordPress PHP : guide complet pour exécuter des shortcodes en PHP

Sommaire de l'article

Introduction

Les shortcodes et la fonction do_shortcode sont au cœur de nombreux développements WordPress modernes. Si vousêtes développeur, intégrateur ou propriétaire de site WordPress et que vous souhaitez appeler un shortcode directement depuis vos fichiers PHP (comme header.php, footer.php, single.php, ou un template personnalisé), comprendre do_shortcode WordPress PHP est essentiel.

Dans ce guide complet, vous allez découvrir :

ce qu’est réellement un shortcode WordPress ;
à quoi sert la fonction PHP do_shortcode et comment elle fonctionne en interne ;
comment utiliser do_shortcode dans vos templates PHP ;
comment créer vos propres shortcodes personnalisés en PHP ;
comment interpréter les shortcodes stockés en base de données (champs personnalisés, metas, options, etc.) ;
les bonnes pratiques de performance, de sécurité et de maintenance ;
des exemples concrets avec des plugins populaires (formulaires, galeries, builders, etc.).

L’objectif de cet article est de vous fournir une ressource de référence professionnelle, structurée et optimisée, afin que vous puissiez utiliser do_shortcode en PHP de manière efficace et sûre dans vos projets WordPress.

Rappel : qu’est-ce qu’un shortcode WordPress ?

Un shortcode WordPress est un petit raccourci placé entre crochets, par exemple [mon_shortcode], que vous insérez dans le contenu d’un article, d’une page, d’un widget ou d’un champ personnalisé. Lorsque WordPress affiche ce contenu, il détecte le shortcode, exécute le code PHP associé et remplace le shortcode par le résultat généré.

Quelques caractéristiques importantes des shortcodes :

Ils sont toujours entourés de crochets [ ].
Ils peuvent accepter des attributs, par exemple : [gallery id="123" columns="3"].
Ils peuventêtre autofermants ([shortcode /]) ou avec une balise fermante ([shortcode]contenu[/shortcode]).
Ils sont déclarés en PHP via la fonction add_shortcode, généralement dans functions.php ou dans un plugin.

Les shortcodes sont donc une façon très pratique d’ajouter des fonctionnalités avancées (galeries, formulaires, sliders, blocs marketing, etc.) sansécrire du code complexe à chaque fois dans l’éditeur de contenu. Toutefois, lorsque vous travaillez dans des fichiers de template PHP, vous ne pouvez pas simplementécrire [mon_shortcode] dans le code source : c’est l à que la fonction do_shortcode entre en jeu.

Présentation de la fonction PHP do_shortcode dans WordPress

do_shortcode est une fonction PHP native de WordPress. Elle est fournie par le cœur de WordPress et documentée dans la référence officielle du code. Cette fonction sert à analyser une chaîne de caractères, y rechercher tous les shortcodes enregistrés et les exécuter, pour finalement retourner la chaîne avec les shortcodes remplacés par leur sortie HTML.

Signature officielle de do_shortcode

La signature actuelle de la fonction est :

do_shortcode( string $content, bool $ignore_html = false ): string

Elle prend donc deux paramètres :

$content (obligatoire) : la chaîne à analyser, dans laquelle WordPress va chercher les shortcodes à exécuter.
$ignore_html (optionnel) : un booléen. S’il est réglé à true, WordPress n’essaiera pas de détecter les shortcodes à l’intérieur des balises HTML, ce qui peut dans certains cas améliorer les performances ouéviter des comportements inattendus.

Valeur de retour : do_shortcode renvoie toujours une chaîne de caractères qui correspond au contenu passé en paramètre, après exécution de tous les shortcodes trouvés. Elle ne modifie pas directement la base de données et ne met pas à jour vos contenus en dur : elle se contente de renvoyer une version « interprétée » du texte.

Syntaxe de base de do_shortcode en PHP

La forme la plus courante pour afficher un shortcode dans un fichier de template est :

Par exemple, pour exécuter un shortcode de formulaire de contact dans header.php, vous pouvezécrire :

Dans cet exemple, on utilise des guillemets simples autour de la chaîne passée à do_shortcode, ce qui permet d’inclure des guillemets doubles dans les attributs du shortcode sans conflit.

À quoi sert concrètement do_shortcode ?

La fonction do_shortcode en PHP est utilisée chaque fois que vous avez besoin d’exécuter un shortcode en dehors de l’éditeur de contenu classique. Elle est particulièrement utile dans les cas suivants :

appeler un shortcode dans un fichier de thème : header.php, footer.php, single.php, page.php, archive.php, etc. ;
afficher un shortcode dans un template de page personnalisée ou un template de bloc ;
exécuter des shortcodes présents dans des champs personnalisés, des metas ou des options stockées en base de données ;
interpréter des shortcodes dans un widget ou dans un hook qui reçoit une chaîne de contenu.

Le comportement interne est le suivant :

WordPress parcourt la chaîne passée à do_shortcode à la recherche des balises de shortcode déclarées via add_shortcode ;
pour chaque shortcode trouvé, WordPress appelle la fonction de rappel (callback) associée ;
les résultats de ces callbacks sont insérés dans la chaîne à la place des balises de shortcode ;
la chaîne finale, avec tous les shortcodes rendus, est renvoyée par la fonction.

Utiliser do_shortcode dans un fichier de template WordPress

Le cas d’usage le plus courant pour do_shortcode WordPress PHP est l’appel d’un shortcode dans un fichier de template de thème. Voici lesétapes générales.

Étapes générales

Identifier le shortcode exact que vous souhaitez afficher (généralement fourni par un plugin ou par votre propre code).
Ouvrir le fichier de template où vous souhaitez afficher ce shortcode (par exemple header.php pour un formulaire dans l’en-tête, single.php pour unélément sous un article, etc.).
Insérer la ligne PHP suivante à l’emplacement voulu :
Enregistrer le fichier, vider les caches le caséchéant, puis vérifier le rendu sur le site.

Exemple : insérer un formulaire de contact dans l’en-tête

Supposons que vous utilisiez un plugin de formulaire de contact qui vous fournit ce shortcode :

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

Pour l’intégrer directement dans header.php, vous pouvezécrire :

Ce code peutêtre placé juste avant la fermeture de la balise ou à tout autre endroit approprié dans votre en-tête. Vous n’êtes pas limité au header : la même approche fonctionne dans le footer, les templates d’articles, les templates de pages, les templates de produits WooCommerce, etc.

Exemple : afficher une galerie dans un template

Imaginons que vous souhaitiez afficher une galerie d’images définie via un shortcode :

[gallery id="123" columns="3"]

Dans votre template PHP, vous pouvez utiliser :

WordPress exécutera le shortcode [gallery] avec les attributs fournis, et renverra le HTML de la galerie à l’endroit exact où vous avez placé l’appel à do_shortcode.

Interpréter les shortcodes stockés en base de données

Dans de nombreux projets, les shortcodes ne sont pas seulement présents dans le contenu principal des articles et des pages. Ils peuvent aussi se trouver dans :

les champs personnalisés (custom fields) ;
les metas de post ou de terme ;
les options de thème ;
les champs d’un constructeur de pages ou d’un formulaire ;
les contenus saisis dans l’interface d’administration par les utilisateurs.

Dans ces cas, WordPress n’interprète pas automatiquement les shortcodes. Si vous récupérez une valeur qui contient potentiellement des shortcodes, vous devez explicitement appeler do_shortcode sur cette valeur.

Exemple avec un champ personnalisé

Supposons que vous ayez un champ personnalisé custom_content associé à un article, et que ce champ puisse contenir des shortcodes. Vous pouvez faire :

Dans cet exemple, tous les shortcodes présents dans $content seront exécutés et remplacés par leur sortie HTML avant d’être affichés.

Exemple avec une option de thème

Si vous avez une option de thème qui stocke un texte contenant des shortcodes (par exemple un bloc de texte pour le footer) :

L à encore, tous les shortcodes trouvés dans la variable seront exécutés.

Créer un shortcode WordPress PHP personnalisé

Pour tirer pleinement parti de do_shortcode WordPress PHP, il est souvent nécessaire de créer vos propres shortcodes. Ceux-ci vous permettront d’encapsuler des fonctionnalités personnalisées et de les appeler aussi bien dans l’éditeur que dans vos templates.

Étapes pour créer un shortcode personnalisé

Ouvrez le fichier functions.php de votre thème (de préférence un thème enfant) ou un plugin dédié.
Créez une fonction PHP qui produit le contenu de votre shortcode.
Enregistrez le shortcode auprès de WordPress avec add_shortcode.

Exemple simple de shortcode personnalisé

Voici un exemple corrigé et propre de shortcode personnalisé :

 'valeur_par_defaut', ), $atts, 'mon_shortcode' ); $parametre = $atts['parametre']; return 'Valeur du paramètre : ' . esc_html( $parametre );
}
add_shortcode( 'mon_shortcode', 'mon_shortcode' );
?>

Ce code :

déclare un shortcode nommé [mon_shortcode] ;
accepte un attribut optionnel parametre avec une valeur par défaut valeur_par_defaut ;
retourne une chaîne qui affiche la valeur de cet attribut, correctementéchappée pour la sécurité.

Utilisation dans le contenu :

[mon_shortcode parametre="exemple"]

Affichera :

Valeur du paramètre : exemple

Exécuter ce shortcode avec do_shortcode en PHP

Vous pouvez aussi appeler ce shortcode directement dans un template, par exemple dans single.php :

Ce qui affichera :

Valeur du paramètre : depuis_template

do_shortcode et plugins WordPress courants

La fonction do_shortcode est compatible avec tous les shortcodes qui ontété correctement enregistrés via add_shortcode. Vous pouvez ainsi l’utiliser avec :

des plugins de formulaires (Contact Form 7, WPForms, Gravity Forms, Fluent Forms, etc.) ;
des plugins de galerie et de portfolio ;
des plugins de sliders ou carrousels ;
des page builders qui exposent des shortcodes pour certaines fonctionnalités ;
vos propres extensions et modules personnalisés.

Exemple avec un plugin de formulaire

Shortcode fourni par le plugin :

[contact-form-7 id="44" title="Formulaire principal"]

Utilisation dans un template :

Exemple avec un builder ou module spécifique

Certains constructeurs de pages ou plugins de mise en page fournissent un shortcode pour insérer une mise en page prédéfinie ou un module particulier, par exemple :

[builder-module id="10"]

Vous pouvez le rendre dans un template via :

Dans certains cas, ces plugins proposent aussi des fonctions PHP dédiées permettant d’afficher un module sans passer par le parsing de shortcodes. Lorsque c’est possible et documenté, ces fonctions dédiées peuventêtre plus performantes qu’un appel systématique à do_shortcode.

Bonnes pratiques d’utilisation de do_shortcode

Attention aux guillemets

Lorsque vousécrivez un shortcode dans une chaîne PHP, il est recommandé d’utiliser :

des guillemets simples autour de la chaîne PHP ;
et des guillemets doubles pour les attributs du shortcode.

Par exemple :

Celaévite des problèmes de syntaxe PHP et rend le code plus lisible.

Performance : ne pas abuser de do_shortcode

Même si do_shortcode est très pratique, elle a un coût en termes de performances, car WordPress doit analyser la chaîne de texte pour trouver et interpréter les shortcodes.

Quelques recommandations :

évitez d’appeler do_shortcode à l’intérieur de boucles très lourdes (par exemple, une boucle de centaines de posts avec plusieurs shortcodes chacun) ;
si vous connaissez la fonction PHP de callback d’un shortcode et que vous n’avez pas besoin du parsing de texte, il peutêtre plus rapide d’appeler directement cette fonction ;
limitez l’usage de do_shortcode aux contextes où vous avez réellement besoin de parser du texte libre qui contient potentiellement plusieurs shortcodes ;
pour les contenus figés et répétitifs, privilégiez parfois un template ou une fonction PHP dédiée plutôt que des appels en chaîne à do_shortcode.

Sécurité et validation

Les shortcodes peuvent déclencher du code puissant : envoi d’e-mails, requêtes sur la base de données, interaction avec des services externes, etc. Lorsque vous utilisez do_shortcode sur des contenus qui peuventêtre saisis par des utilisateurs, vous devez garder à l’esprit :

quels rôles utilisateurs ont le droit d’insérer des shortcodes ;
quels shortcodes sont effectivement enregistrés sur le site ;
quels effets potentiels ces shortcodes peuvent avoir (par exemple création de contenu, envoi d’informations sensibles).

Notezégalement que :

do_shortcode ne s’occupe pas d’échapper les sorties HTML ;
c’est le callback du shortcode qui doit gérer l’échappement approprié (par exemple esc_html, esc_attr, wp_kses, etc.) ;
si vous affichez du contenu provenant de shortcodes dans des attributs HTML ou des contextes sensibles, veillez toujours àéchapper correctement la sortie.

Différence avec les filtres automatiques de contenu

Dans l’éditeur classique de WordPress et dans l’éditeur de blocs, les shortcodes sont automatiquement interprétés sur le contenu principal via les filtres appliqués à the_content. C’est pour cela que, lorsque vousécrivez simplement [mon_shortcode] dans le corps d’un article, il est exécuté sans que vous ayez à appeler do_shortcode vous-même.

En revanche :

pour les champs personnalisés, metas, blocs spécifiques, options et autres contenus personnalisés, do_shortcode n’est pas appliqué automatiquement ;
si vous souhaitez interpréter les shortcodes dans ces contenus, vous devez appeler do_shortcode( $contenu ) explicitement.

Alternatives et complémentarités à do_shortcode dans WordPress moderne

Avec l’évolution de WordPress vers les thèmes en Full Site Editing et l’éditeur de blocs, certains usages traditionnels des shortcodes peuventêtre remplacés ou complétés par des solutions plus modernes.

De nombreux plugins proposent désormais des blocs natifs (pour Gutenberg) en plus de leurs shortcodes. Dans certains cas, il est plus simple et plus clair d’utiliser un bloc dédié dans un template de bloc plutôt que de passer par do_shortcode.
Certains thèmes et plugins fournissent des fonctions PHP publiques pour afficher leurs composants (formulaires, galeries, sections mises en page). Quand c’est possible, ces fonctions offrent souvent de meilleures performances et un contrôle plus fin que le passage par un shortcode.
Les shortcodes restent cependant très utiles pour :
- assurer la compatibilité avec l’éditeur classique ;
- offrir un moyen simple d’insérer une fonctionnalité dans du contenu textuel libre ;
- faciliter la réutilisation de fonctionnalités dans différents contextes.

Erreurs fréquentes et idées reçues sur do_shortcode

Quelques malentendus reviennent régulièrement au sujet de do_shortcode WordPress PHP. Voici les clarifications essentielles :

« do_shortcode ne sert qu’en header » : faux. La fonction fonctionne sur tout contenu passé en paramètre, que vous l’appeliez dans le header, le footer, un template d’article, un widget, un hook, etc. L’important est la chaîne que vous lui transmettez, pas l’endroit où vous l’appelez.
« do_shortcode modifie la base de données » : faux. Elle ne fait qu’analyser une chaîne et retourner une nouvelle chaîne avec les shortcodes interprétés. Elle ne met pas à jour votre contenu en base.
« do_shortcode est obsolète » : faux. La fonction est toujours active, supportée et documentée dans le cœur de WordPress.
« do_shortcode est automatiquement appelée partout » : inexact. WordPress applique le moteur de shortcodes sur certains filtres, notamment sur le contenu principal des articles. Mais pour beaucoup d’autres champs ou contenus personnalisés, vous devez appeler do_shortcode vous-même pour interpréter les shortcodes.
« do_shortcode est toujours la solution la plus performante » : faux. Lorsque vous connaissez la fonction PHP de callback d’un shortcode ou que le plugin propose une API PHP dédiée, il est souvent plus rapide d’appeler directement cette fonction sans passer par le parsing de shortcodes.

Checklist pratique pour utiliser do_shortcode en PHP

Pour finir, voici une liste pratique de points à vérifier lorsque vous travaillez avec do_shortcode WordPress PHP :

Vérifiez que le shortcode que vous souhaitez utiliser est bien enregistré via add_shortcode (par le cœur, un plugin ou votre code).
Utilisez la syntaxe :
Privilégiez des guillemets simples pour la chaîne PHP, et des guillemets doubles pour les attributs du shortcode.
Pour le contenu stocké en base de données contenant des shortcodes, pensez à faire :
Évitez d’appeler do_shortcode dans des boucles massives sans nécessité.
Contrôlez les rôles et droits des utilisateurs autorisés à insérer des shortcodes dans le contenu.
Assurez-vous que les callbacks des shortcodes gèrent correctement la sécurité (validation des données, échappement de la sortie).
Lorsque disponible, envisagez l’utilisation de blocs ou de fonctions PHP dédiées comme alternatives plus modernes ou plus performantes.

En appliquant ces bonnes pratiques et en comprenant le fonctionnement interne de do_shortcode, vous serez en mesure d’intégrer des shortcodes dans vos fichiers PHP WordPress de façon propre, performante et sécurisée, tout en optimisant la structure et la qualité de vos contenus pour votre site.