shortcode_atts : fusionner un shortcode et ses valeurs par défaut, en sûreté

$atts = shortcode_atts( array( 'limite' => 5, 'categorie' => '' ), $atts, 'derniers_articles' ); — cette ligne, discrète, fait plus qu’une simple fusion de tableaux. Elle filtre aussi les attributs que l’utilisateur aurait pu ajouter en trop, et qui n’ont jamais été prévus par le shortcode.

C’est ce second comportement qui distingue shortcode_atts() d’un simple array_merge(), et qui justifie de toujours l’utiliser plutôt que de fusionner les tableaux à la main dans le rappel d’un shortcode.

La signature et son fonctionnement

shortcode_atts( array $pairs, array $atts, string $shortcode = '' ) prend trois arguments : les paires clé/valeur par défaut, les attributs réellement fournis par l’utilisateur dans le contenu, et en option le nom du shortcode. Le résultat est un tableau qui ne contient que les clés définies dans $pairs : toute clé présente dans $atts mais absente des valeurs par défaut est simplement écartée.

Ce comportement protège le code qui suit contre un utilisateur qui écrirait, par exemple, [derniers_articles limite="5" requete_sql="DROP TABLE"] : l’attribut requete_sql disparaît dès la fusion, avant même d’atteindre la logique du shortcode. Ce n’est pas un mécanisme d’échappement de données à proprement parler, mais un filtrage de forme qui réduit la surface d’attributs à traiter.

Un shortcode « derniers articles » bien construit

function shortcode_derniers_articles( $atts ) {
    $atts = shortcode_atts( array(
        'limite'    => 5,
        'categorie' => '',
    ), $atts, 'derniers_articles' );

    $args = array(
        'posts_per_page' => (int) $atts['limite'],
    );

    if ( ! empty( $atts['categorie'] ) ) {
        $args['category_name'] = sanitize_title( $atts['categorie'] );
    }

    $requete = new WP_Query( $args );

    // Construction du rendu à partir de $requete…

    return $sortie;
}

Le troisième paramètre, 'derniers_articles', mérite d’être toujours renseigné : il ouvre le filtre shortcode_atts_{$shortcode}, propre à ce shortcode précis, plutôt que le filtre générique shortcode_atts_ qui s’appliquerait indistinctement à tous les shortcodes du site.

Le filtre par shortcode, un point d’extension sous-utilisé

Grâce à ce troisième paramètre, une autre extension — ou un thème enfant — peut ajuster les valeurs par défaut d’un shortcode sans toucher au code source original :

add_filter( 'shortcode_atts_derniers_articles', function ( $out, $pairs, $atts ) {
    // Forcer une limite maximale, quelle que soit la valeur demandée.
    $out['limite'] = min( (int) $out['limite'], 20 );

    return $out;
}, 10, 3 );

Cette possibilité passe souvent inaperçue parce qu’elle dépend entièrement du troisième argument de shortcode_atts() : un développeur qui omet ce paramètre prive son shortcode de ce point d’extension, sans le savoir.

Ce que shortcode_atts ne garantit pas

• Les valeurs des attributs conservés ne sont ni échappées ni validées : un attribut categorie reste une chaîne brute qu’il faut nettoyer avec sanitize_title() ou une fonction équivalente avant usage.
• La fonction ne vérifie pas les types : un attribut numérique reste une chaîne tant qu’un cast explicite n’est pas appliqué.
• Elle ne remplace pas l’enregistrement du shortcode lui-même via add_shortcode(), qui reste une étape distincte et préalable.

Toujours nommer le troisième paramètre de shortcode_atts() avec le nom exact du shortcode : c’est ce qui ouvre un filtre ciblé, réutilisable plus tard sans toucher au code d’origine.

Un dernier repère : la casse des clés

Un détail passe parfois inaperçu : les clés du tableau $atts transmis à shortcode_atts() arrivent déjà en minuscules, car WordPress applique cette normalisation en amont, lors du parsing du shortcode lui-même. Il est donc inutile d’écrire une gestion de casse défensive dans les valeurs par défaut : une clé Limite définie en majuscule ne correspondra tout simplement jamais à un attribut fourni par l’utilisateur, quelle que soit la façon dont ce dernier l’a saisi dans le contenu.

En résumé

shortcode_atts() mérite sa place dans chaque rappel de shortcode, pour deux raisons distinctes : elle fusionne proprement attributs fournis et valeurs par défaut, et elle écarte silencieusement tout attribut non prévu, réduisant ainsi ce que le reste du code a besoin de traiter. Ajouter le troisième paramètre, celui du nom du shortcode, coûte peu et ouvre un point d’extension précieux pour la suite du projet.