Dans WordPress, un shortcode comme [gallery], [contact-form-7] ou [mon_shortcode] fonctionne très bien dans le contenu d’un article. Mais si vous le retournez directement depuis une fonction PHP, WordPress ne l’exécutera pas automatiquement.
Autrement dit, ceci ne suffit pas toujours :
return '[mon_shortcode]';Langage du code : JavaScript (javascript)Dans ce cas, vous risquez d’afficher le texte brut du shortcode au lieu de son rendu HTML. Pour demander à WordPress d’interpréter le shortcode, il faut utiliser do_shortcode() ou apply_shortcodes().
Exécuter un shortcode avec do_shortcode()
La méthode classique consiste à appeler do_shortcode() :
<?php
/**
* Return the rendered output of a WordPress shortcode.
*
* @return string Rendered shortcode output.
*/
function skyminds_render_custom_shortcode(): string {
return do_shortcode( '[mon_shortcode]' );
}Langage du code : HTML, XML (xml)La fonction do_shortcode() analyse la chaîne fournie, cherche les shortcodes enregistrés, puis exécute les callbacks correspondants.
Si le shortcode est fourni par un plugin désactivé, WordPress ne pourra pas l’exécuter. Dans ce cas, la chaîne peut rester visible telle quelle. C’est logique : WordPress ne peut pas appeler une fonction qui n’existe plus. Même lui a ses limites.
Utiliser apply_shortcodes() avec WordPress moderne
Depuis WordPress 5.4, vous pouvez aussi utiliser apply_shortcodes(). Cette fonction est un alias de do_shortcode(), mais son nom décrit mieux l’intention : appliquer les shortcodes à une chaîne de contenu.
<?php
/**
* Return the rendered output of a WordPress shortcode.
*
* @return string Rendered shortcode output.
*/
function skyminds_render_custom_shortcode(): string {
return apply_shortcodes( '[mon_shortcode]' );
}Langage du code : HTML, XML (xml)Les deux fonctions produisent le même résultat. Sur un projet moderne, apply_shortcodes() est légèrement plus explicite. Sur un vieux projet ou pour compatibilité maximale, do_shortcode() reste très courant.
Afficher un shortcode dans un template PHP
Dans un fichier de template, vous pouvez afficher directement le rendu :
<?php
echo do_shortcode( '[mon_shortcode]' );Langage du code : HTML, XML (xml)Mais dans un thème, un plugin ou un snippet propre, je préfère garder une fonction dédiée. C’est plus testable, plus lisible, et plus simple à modifier ensuite.
<?php
/**
* Render a shortcode safely from a template.
*
* @return void
*/
function skyminds_output_custom_shortcode(): void {
$output = do_shortcode( '[mon_shortcode]' );
echo wp_kses_post( $output );
}Langage du code : HTML, XML (xml)Ici, wp_kses_post() autorise le HTML normalement accepté dans le contenu WordPress, tout en filtrant les balises dangereuses. C’est souvent une bonne protection quand le shortcode produit du HTML.
Retourner un shortcode depuis une fonction
Si vous créez une fonction qui doit retourner du contenu, utilisez return plutôt que echo. C’est particulièrement important dans les callbacks de shortcodes, les hooks et les fonctions réutilisables.
<?php
/**
* Return a rendered newsletter signup form.
*
* @return string Rendered form HTML.
*/
function skyminds_get_newsletter_form(): string {
return do_shortcode( '[newsletter_form]' );
}Langage du code : HTML, XML (xml)Vous pouvez ensuite afficher cette fonction dans un template :
Marre des agences qui sous-traitent ?
Avec moi, vous parlez directement au développeur qui fait le travail. Pas d'intermédiaire, pas de promesses creuses. Juste du code propre et un interlocuteur joignable.
Travaillons directement ensemble →<?php
echo wp_kses_post( skyminds_get_newsletter_form() );Langage du code : HTML, XML (xml)La logique reste dans une fonction, et l’affichage reste dans le template. C’est propre. On respire mieux.
Exécuter un shortcode avec des attributs
Pour exécuter un shortcode avec des attributs, ajoutez-les dans la chaîne :
<?php
/**
* Render a contact form shortcode.
*
* @return string Rendered form HTML.
*/
function skyminds_render_contact_form(): string {
return do_shortcode( '[contact-form-7 id="123" title="Contact"]' );
}Langage du code : HTML, XML (xml)Si les valeurs viennent du code, construisez la chaîne avec sprintf() et échappez les attributs avec esc_attr() :
<?php
/**
* Render a shortcode with dynamic attributes.
*
* @param int $form_id Form ID.
* @param string $title Form title.
*
* @return string Rendered shortcode output.
*/
function skyminds_render_dynamic_contact_form( int $form_id, string $title ): string {
$shortcode = sprintf(
'[contact-form-7 id="%d" title="%s"]',
absint( $form_id ),
esc_attr( $title )
);
return do_shortcode( $shortcode );
}Langage du code : HTML, XML (xml)Ne concaténez pas naïvement des valeurs utilisateur dans un shortcode. Les attributs de shortcode finissent souvent par influencer du HTML, des requêtes ou des sorties dynamiques. Donc, oui, même ici, l’échappement compte.
Vérifier qu’un shortcode existe avant de l’exécuter
Si le shortcode dépend d’un plugin, vérifiez qu’il existe avant de l’appeler. Cela évite d’afficher un shortcode brut quand le plugin est désactivé.
<?php
/**
* Render a shortcode only if it is registered.
*
* @return string Rendered shortcode output, or an empty string.
*/
function skyminds_render_shortcode_if_available(): string {
if ( ! shortcode_exists( 'newsletter_form' ) ) {
return '';
}
return do_shortcode( '[newsletter_form]' );
}Langage du code : HTML, XML (xml)C’est particulièrement utile pour les formulaires, les sliders, les galeries, les produits WooCommerce ou les shortcodes fournis par des plugins tiers.
Créer un shortcode qui appelle un autre shortcode
Vous pouvez aussi créer un shortcode qui encapsule un autre shortcode. C’est utile pour simplifier un shortcode long, masquer des attributs techniques, ou centraliser un rendu.
<?php
/**
* Register custom shortcodes.
*
* @return void
*/
function skyminds_register_shortcodes(): void {
add_shortcode( 'formulaire_contact', 'skyminds_contact_form_shortcode' );
}
add_action( 'init', 'skyminds_register_shortcodes' );
/**
* Render a contact form shortcode.
*
* @param array<string, mixed> $atts Shortcode attributes.
*
* @return string Rendered shortcode output.
*/
function skyminds_contact_form_shortcode( array $atts = array() ): string {
$atts = shortcode_atts(
array(
'id' => 123,
'title' => 'Contact',
),
$atts,
'formulaire_contact'
);
$form_id = absint( $atts['id'] );
$title = sanitize_text_field( (string) $atts['title'] );
if ( ! shortcode_exists( 'contact-form-7' ) ) {
return '';
}
$shortcode = sprintf(
'[contact-form-7 id="%d" title="%s"]',
$form_id,
esc_attr( $title )
);
return do_shortcode( $shortcode );
}Langage du code : HTML, XML (xml)Vous pouvez ensuite utiliser :
[formulaire_contact id="123" title="Contact"]Langage du code : JSON / JSON avec commentaires (json)WordPress recommande shortcode_atts() pour fusionner les attributs fournis avec les valeurs par défaut. Cela permet aussi d’ignorer les attributs non supportés.
Exécuter les shortcodes dans un texte complet
do_shortcode() ne sert pas uniquement à exécuter une chaîne qui ne contient qu’un shortcode. Il peut aussi traiter un contenu complet.
<?php
/**
* Render shortcodes inside a custom content string.
*
* @param string $content Raw content.
*
* @return string Content with shortcodes rendered.
*/
function skyminds_render_shortcodes_in_content( string $content ): string {
return do_shortcode( $content );
}Langage du code : HTML, XML (xml)Exemple :
$content = 'Bienvenue sur le site. [newsletter_form] Merci pour votre visite.';
echo wp_kses_post( skyminds_render_shortcodes_in_content( $content ) );Langage du code : PHP (php)C’est utile si vous stockez du contenu personnalisé dans une option, une meta, un champ ACF ou une configuration de thème.
Ne pas exécuter des shortcodes utilisateur sans contrôle
Évitez d’exécuter aveuglément des shortcodes saisis par des utilisateurs non fiables. Un shortcode peut déclencher du rendu complexe, des requêtes, des intégrations externes ou des sorties HTML.
Si vous autorisez des shortcodes dans une option d’administration, vérifiez les capacités utilisateur avant l’enregistrement :
<?php
/**
* Save a shortcode setting only for administrators.
*
* @param string $shortcode Raw shortcode setting.
*
* @return string Sanitized shortcode setting.
*/
function skyminds_sanitize_shortcode_setting( string $shortcode ): string {
if ( ! current_user_can( 'manage_options' ) ) {
return '';
}
return sanitize_text_field( $shortcode );
}Langage du code : HTML, XML (xml)Selon le besoin, vous pouvez aussi créer une liste de shortcodes autorisés, au lieu d’accepter n’importe quelle chaîne.
Limiter les shortcodes autorisés
Voici une approche simple : on n’exécute le shortcode que s’il appartient à une liste explicitement autorisée.
<?php
/**
* Render a shortcode only if it is allowlisted.
*
* @param string $shortcode_tag Shortcode tag without brackets.
* @param string $raw_shortcode Full shortcode string.
*
* @return string Rendered shortcode output.
*/
function skyminds_render_allowed_shortcode( string $shortcode_tag, string $raw_shortcode ): string {
$allowed_shortcodes = array(
'contact-form-7',
'newsletter_form',
'gallery',
);
if ( ! in_array( $shortcode_tag, $allowed_shortcodes, true ) ) {
return '';
}
if ( ! shortcode_exists( $shortcode_tag ) ) {
return '';
}
return do_shortcode( $raw_shortcode );
}Langage du code : HTML, XML (xml)Cette méthode reste simple, mais elle évite de transformer un champ de réglage en buffet à shortcodes. C’est rarement une bonne idée.
Performance : ne pas abuser de do_shortcode()
do_shortcode() analyse une chaîne, cherche des tags de shortcode, puis déclenche les callbacks associés. Ce n’est pas catastrophique, mais ce n’est pas gratuit non plus.
Évitez donc d’appeler do_shortcode() dans une boucle lourde, par exemple sur 100 articles, si vous pouvez faire autrement. Chaque appel peut déclencher du rendu, des requêtes, des appels à des plugins ou des intégrations externes.
Si vous devez auditer des contenus massivement avec WP-CLI, préférez parfois retirer les shortcodes avec strip_shortcodes() plutôt que les exécuter. C’est le cas, par exemple, quand vous cherchez les articles courts. J’ai détaillé cette approche dans l’article sur les articles WordPress de moins de 300 mots.
Quand éviter do_shortcode()
Si vous contrôlez le code du shortcode, il vaut souvent mieux appeler directement la fonction PHP interne plutôt que repasser par une chaîne de shortcode.
Exemple moins idéal :
return do_shortcode( '[dernier_article]' );Langage du code : JavaScript (javascript)Exemple préférable si vous contrôlez la fonction :
return skyminds_render_latest_post();Langage du code : JavaScript (javascript)Le shortcode doit être une interface pratique pour l’éditeur. La fonction PHP doit rester la source réutilisable. Cela évite de parser une chaîne inutilement, et le code devient plus clair.
Architecture propre : fonction d’abord, shortcode ensuite
Voici une structure plus propre pour vos propres shortcodes : une fonction rend le contenu, puis le shortcode appelle cette fonction.
<?php
/**
* Render the latest published post link.
*
* @return string Rendered HTML.
*/
function skyminds_render_latest_post(): string {
$query = new WP_Query(
array(
'post_type' => 'post',
'post_status' => 'publish',
'posts_per_page' => 1,
'no_found_rows' => true,
'ignore_sticky_posts' => true,
'update_post_meta_cache' => false,
'update_post_term_cache' => false,
)
);
if ( ! $query->have_posts() ) {
return '';
}
$query->the_post();
$output = sprintf(
'<a href="%s">%s</a>',
esc_url( get_permalink() ),
esc_html( get_the_title() )
);
wp_reset_postdata();
return $output;
}
/**
* Register the latest post shortcode.
*
* @return void
*/
function skyminds_register_latest_post_shortcode(): void {
add_shortcode( 'dernier_article', 'skyminds_latest_post_shortcode' );
}
add_action( 'init', 'skyminds_register_latest_post_shortcode' );
/**
* Render the latest post shortcode.
*
* @return string Rendered shortcode output.
*/
function skyminds_latest_post_shortcode(): string {
return skyminds_render_latest_post();
}Langage du code : HTML, XML (xml)Avec cette architecture, vous pouvez utiliser [dernier_article] dans un article, mais aussi appeler skyminds_render_latest_post() directement dans un template. C’est plus rapide, plus propre, et moins magique.
Exécuter un shortcode dans un hook WordPress
Vous pouvez aussi afficher le rendu d’un shortcode depuis un hook. Par exemple, pour ajouter un formulaire après le contenu d’un article :
<?php
/**
* Append a newsletter form after single post content.
*
* @param string $content Post content.
*
* @return string Filtered post content.
*/
function skyminds_append_newsletter_form_to_posts( string $content ): string {
if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
return $content;
}
if ( ! shortcode_exists( 'newsletter_form' ) ) {
return $content;
}
$form = do_shortcode( '[newsletter_form]' );
return $content . wp_kses_post( $form );
}
add_filter( 'the_content', 'skyminds_append_newsletter_form_to_posts', 20 );Langage du code : HTML, XML (xml)Les conditions évitent d’ajouter le formulaire dans les archives, les widgets, les requêtes secondaires ou les contextes inattendus. C’est le genre de détail qui évite les surprises en production.
Shortcodes et Gutenberg
Gutenberg propose un bloc Shortcode natif. Si votre objectif est simplement d’insérer un shortcode dans une page, utilisez ce bloc. C’est plus propre que de forcer l’exécution depuis un template PHP.
En revanche, do_shortcode() reste utile quand le shortcode doit être injecté automatiquement par le thème, par un plugin, par un hook, ou dans une zone qui n’est pas éditable depuis l’éditeur de blocs.
Si vous refondez un ancien site, vous pouvez progressivement remplacer certains shortcodes par des blocs natifs. C’est souvent plus maintenable, surtout pour les formulaires, boutons, colonnes, encarts et contenus réutilisables.
Cas WooCommerce : utiliser les fonctions plutôt que les shortcodes
WooCommerce fournit encore des shortcodes utiles. Mais si vous développez une fonctionnalité avancée, privilégiez souvent les fonctions, hooks, templates ou blocs WooCommerce plutôt que des appels massifs à do_shortcode().
Par exemple, appeler un shortcode de produit dans une boucle custom peut être beaucoup plus lourd qu’une requête optimisée et un template maîtrisé. Pour les opérations WooCommerce côté maintenance, le guide sur la mise à jour de la base WooCommerce avec WP-CLI complète bien cette logique : utiliser l’outil natif adapté plutôt qu’un détour fragile.
Checklist rapide
- Utilisez
do_shortcode()ouapply_shortcodes()pour exécuter un shortcode dans du PHP. - Utilisez
shortcode_exists()si le shortcode dépend d’un plugin. - Échappez les attributs dynamiques avec
esc_attr(). - Filtrez la sortie HTML avec
wp_kses_post()si vous l’affichez directement. - Évitez d’exécuter des shortcodes saisis par des utilisateurs non fiables.
- Évitez
do_shortcode()dans les boucles lourdes. - Si vous contrôlez le code, appelez la fonction PHP native plutôt que le shortcode.
- Pour Gutenberg, utilisez le bloc Shortcode quand l’insertion doit rester éditoriale.
Exemples utiles à garder
Exécuter un shortcode simple :
echo do_shortcode( '[mon_shortcode]' );Langage du code : PHP (php)Version moderne équivalente :
echo apply_shortcodes( '[mon_shortcode]' );Langage du code : PHP (php)Vérifier l’existence du shortcode :
if ( shortcode_exists( 'mon_shortcode' ) ) {
echo do_shortcode( '[mon_shortcode]' );
}Langage du code : PHP (php)Retourner le rendu depuis une fonction :
function skyminds_get_shortcode_output(): string {
return do_shortcode( '[mon_shortcode]' );
}Langage du code : JavaScript (javascript)Afficher une sortie filtrée :
echo wp_kses_post( skyminds_get_shortcode_output() );Langage du code : PHP (php)Conclusion
Pour exécuter un shortcode WordPress dans une fonction PHP, utilisez simplement do_shortcode() ou apply_shortcodes() :
return do_shortcode( '[mon_shortcode]' );Langage du code : JavaScript (javascript)C’est la réponse courte. La réponse propre ajoute quelques garde-fous : vérifier que le shortcode existe, échapper les attributs dynamiques, filtrer la sortie HTML, et éviter les appels inutiles dans les boucles lourdes.
Enfin, si vous contrôlez le code derrière le shortcode, gardez la meilleure architecture : une fonction PHP réutilisable d’abord, un shortcode ensuite. Le shortcode devient alors une interface pratique pour l’éditeur, pas une béquille technique dans tout le thème.
Sources
- WordPress Developer Resources — do_shortcode()
- WordPress Developer Resources — apply_shortcodes()
- WordPress Developer Resources — Shortcode API
Un projet WordPress en tête ?
Vous avez une idée claire de ce que vous voulez, mais pas les ressources en interne pour le faire bien. Je développe des sites et extensions WordPress sur-mesure — sans délais à rallonge ni mauvaises surprises.
Décrivez-moi votre projet →
