wp_parse_args : fusionner des tableaux d’arguments sans réinventer array_merge

function wp_parse_args( $args, $defaults = array() ) : cette signature tient sur une ligne, et pourtant elle règle un problème que beaucoup de développeurs rencontrent sans le nommer clairement. Dès qu’une fonction accepte un tableau d’options facultatives, il faut décider quoi faire des clés absentes, des types inattendus et des valeurs vides envoyées volontairement.

La tentation naturelle est d’écrire array_merge( $defaults, $args ) et de passer à autre chose. Cela fonctionne dans les cas simples, mais dès que les arguments proviennent d’une chaîne de requête ou d’un tableau à clés numériques mélangées, les comportements divergent. WordPress a réglé ce problème une bonne fois pour toutes avec wp_parse_args().

Le problème d’un array_merge() nu

array_merge() réindexe les clés numériques au lieu de les fusionner par nom. Si un développeur construit une fonction acceptant des options comme 0 => 'première' par accident, ou si un argument est passé sous forme de chaîne façon largeur=200&hauteur;=100, array_merge() ne sait tout simplement pas quoi en faire. Il attend deux tableaux propres, rien de plus.

Dans une fonction publique, réutilisée par d’autres développeurs ou par soi-même six mois plus tard, ce genre de rigidité finit toujours par coûter du temps de débogage.

Ce que fait réellement wp_parse_args()

wp_parse_args() accepte un premier argument sous deux formes : un tableau associatif classique, ou une chaîne au format requête HTTP (via wp_parse_str() en interne). Elle fusionne ensuite ce résultat avec le tableau de valeurs par défaut fourni en second argument, en donnant la priorité aux valeurs explicitement transmises.

Un exemple concret : une fonction à options

Prenons une fonction qui affiche une liste d’articles récents pour un widget maison, avec des réglages personnalisables :

function afficher_articles_recents( $args = array() ) {
    $defaults = array(
        'nombre'      => 5,
        'categorie'   => '',
        'afficher_date' => true,
    );

    $args = wp_parse_args( $args, $defaults );

    $query_args = array(
        'posts_per_page' => $args['nombre'],
        'category_name'  => $args['categorie'],
    );

    $recents = new WP_Query( $query_args );
    // ... boucle d'affichage
}

afficher_articles_recents( array( 'nombre' => 3 ) );

Ici, seule la clé nombre est modifiée ; categorie et afficher_date conservent leur valeur par défaut sans qu’aucune vérification manuelle ne soit nécessaire dans le corps de la fonction.

Les pièges à éviter

• Une valeur explicitement fournie à false ou 0 reste bien prise en compte, contrairement à un test empty() mal placé plus loin dans le code.
• Si l’appelant passe un objet au lieu d’un tableau, wp_parse_args() le convertit via un cast, ce qui peut masquer une erreur de type en amont — mieux vaut documenter le format attendu.
• La fusion n’est pas récursive : un sous-tableau imbriqué dans les valeurs par défaut sera intégralement remplacé si l’appelant en fournit un, même partiel.

Quand la chaîne de requête devient utile

Le format chaîne est surtout pratique lorsqu’une fonction est appelée depuis un shortcode ou un attribut de bloc où les arguments arrivent déjà sous forme de texte. Plutôt que de parser la chaîne à la main avec des fonctions de découpage, il suffit de la transmettre telle quelle en premier argument.

Le réflexe à prendre : dès qu’une fonction dépasse deux paramètres facultatifs, remplacez-les par un unique tableau d’arguments passé à wp_parse_args(). Le code appelant reste lisible même des années plus tard.

En résumé

Écrire soi-même la logique de fusion d’arguments par défaut est un classique de la sur-ingénierie évitable. wp_parse_args() existe précisément pour ce cas, gère la chaîne de requête comme le tableau, et respecte les valeurs explicitement transmises même quand elles sont falsy. Adopter ce réflexe dès la conception d’une fonction évite de devoir tout réécrire lorsque les besoins évoluent.

La prochaine fois qu’une fonction personnalisée s’apprête à accepter un tableau d’options, ce petit détour par l’API native de WordPress fera gagner un temps disproportionné par rapport à sa simplicité apparente.