add_post_meta()

Définition : add_post_meta() ajoute une valeur de métadonnée à une publication WordPress. Elle peut autoriser plusieurs valeurs portant la même clé, ou demander l’unicité de cette clé pour le contenu concerné.

Terminologie

Terme officiel : add_post_meta()

Autres appellations : Ajout de champ personnalisé

À quoi cela sert

Elle sert lorsque l’on souhaite créer explicitement une donnée supplémentaire sans supposer qu’une autre valeur doit être écrasée.

Comment cela fonctionne

La fonction accepte un identifiant de post, une clé, une valeur et un paramètre unique facultatif. Lorsqu’il vaut true, elle refuse l’ajout si une valeur existe déjà sous la même clé pour ce post.

Dans quel contexte l’utiliser

À utiliser pour initialiser une clé de métadonnée dans un flux contrôlé ou pour enregistrer plusieurs valeurs distinctes d’une même nature.

Exemple concret

Une fiche reçoit sa référence initiale et le plugin ne doit pas la remplacer par accident si elle existe déjà.

Exemple de code commenté

Extrait pédagogique PHP pour extension WordPress : adapter au contexte et tester sur un environnement de développement avant tout usage.

<?php
$post_id = 123; // Contexte de traitement autorisé.
if ( current_user_can( 'edit_post', $post_id ) ) {
    $ajoute = add_post_meta(
        $post_id, '_atoolpha_reference', 'REF-001', true
    );
    // $ajoute peut être false si cette clé existait déjà.
}

Explication pas à pas de l’exemple

1. Le droit de modifier la publication est testé. 2. La clé est préfixée pour éviter les collisions. 3. true exige son unicité sur cet article. 4. Le retour indique si l’ajout a été effectué.

Résultat attendu

La référence initiale est enregistrée si elle n’existait pas ; une valeur déjà présente n’est pas écrasée.

Mise en pratique guidée

Sur un article de test, lancer une première insertion avec unique=true, puis répéter exactement la même insertion. Le premier appel peut créer la valeur ; le second ne doit pas l’écraser. Réaliser ensuite une variante avec unique=false pour observer que WordPress permet plusieurs entrées d’une même clé.

Précautions et limites

En cas d’entrée venant d’un formulaire, ajouter vérification nonce et validation stricte. L’unicité concerne une clé pour un post donné, pas l’ensemble du site.