wp_parse_args()

Définition : wp_parse_args() fusionne des arguments fournis sous plusieurs formes avec un tableau de valeurs par défaut. Elle aide les fonctions WordPress à accepter des options facultatives sans répéter leur normalisation partout.

Comprendre et utiliser

À quoi sert ce terme ?

Elle fournit un modèle clair pour des paramètres configurables. Un développeur peut laisser certaines options absentes tout en garantissant l’existence de clés attendues par la logique métier.

Fonctionnement technique

La fonction normalise en tableau puis combine les valeurs reçues avec des valeurs par défaut : les arguments présents ont priorité. Elle ne valide pas automatiquement les types, les permissions ou les bornes numériques.

Dans quels contextes l’utiliser ?

Employer dans une fonction utilitaire, un shortcode ou un contrôleur avant de valider chaque paramètre au regard de son utilisation réelle.

Cas concret : ATOOLPHA

Un composant ATOOLPHA de liste d’articles accepte une limite optionnelle. Si aucune limite n’est transmise, il retient une valeur modérée.

Exemple de code commenté

Extrait PHP destiné à un plugin ou à un template WordPress, dans le contexte indiqué ; pas au contenu HTML de l’article.

<?php
function atoolpha_list_options( $input ) {
    $options = wp_parse_args( $input, array(
        'limit' => 5, 'order' => 'DESC',
    ) );
    $options['limit'] = min( 20, max( 1, absint( $options['limit'] ) ) );
    if ( ! in_array( $options['order'], array( 'ASC', 'DESC' ), true ) ) {
        $options['order'] = 'DESC';
    }
    return $options;
}

Décryptage de l’exemple

La fusion intervient d’abord, puis la borne de limit et la liste autorisée pour order apportent la validation indispensable. Sans cette deuxième étape, une valeur arbitraire pourrait se propager vers la requête.

Résultat attendu

Une configuration vide produit limit=5 et order=DESC. Une valeur négative ou trop élevée est ramenée dans l’intervalle autorisé.

Exercice pratique et vérification

Tester une configuration vide, limit=500 et order=RANDOM. Consigner les valeurs retournées et expliquer la priorité des arguments fournis.

Précautions et limites

Ne pas confondre présence d’une clé et fiabilité de son contenu. Valider explicitement chaque option et documenter les cas de valeurs inattendues.

À ne pas confondre

wp_parse_args() combine des options ; sanitize_text_field() nettoie du texte ; in_array() avec comparaison stricte contrôle une liste fermée de valeurs.

Diagnostic avancé

Lorsque la valeur d’une option semble ignorée, comparer le tableau initial au tableau fusionné, puis à la validation finale plutôt que d’accuser la fonction de fusion.

Choix d’architecture et déploiement

L’API d’arguments doit définir un contrat en amont : valeurs possibles, types et valeurs par défaut. La fusion seule ne crée pas ce contrat ; elle doit être suivie par une validation qui permet ensuite des messages d’erreur utiles et des tests reproductibles.