metadata_exists()

Définition : metadata_exists() vérifie si une clé de métadonnée existe pour un objet WordPress donné. Elle distingue l’absence d’une clé de la présence d’une valeur vide ou équivalente à false.

Terminologie

Terme officiel : metadata_exists()

Autres appellations : Présence de métadonnée

À quoi cela sert

Cette distinction évite des comportements ambiguës lorsque le plugin doit savoir si une préférence a déjà été initialisée ou si son contenu est volontairement vide.

Comment cela fonctionne

La fonction reçoit le type de métadonnée, l’identifiant de l’objet et le nom de la clé. Elle renvoie true si une ligne correspondante existe, même si la valeur enregistrée est vide.

Dans quel contexte l’utiliser

À utiliser avant de créer une métadonnée initiale ou lorsqu’un champ vide possède une signification propre au métier.

Exemple concret

Un plugin doit différencier « non renseigné » de « renseigné explicitement avec une chaîne vide » pour une référence documentaire.

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;
$existe = metadata_exists( 'post', $post_id, '_atoolpha_ref' );
if ( ! $existe ) {
    // Aucune clé : l’initialisation pourra être envisagée.
    $etat = 'jamais_initialise';
} else {
    $etat = 'cle_presente'; // Même si la valeur est vide.
}

Explication pas à pas de l’exemple

1. Le type post indique une recherche dans les métadonnées de publications. 2. La clé est vérifiée pour un ID précis. 3. Le code branche sur l’existence et non sur la valeur retournée.

Résultat attendu

Le programme distingue correctement une clé absente d’une clé existante vide, ce qui évite d’écraser un choix explicite.

Mise en pratique guidée

Enregistrer volontairement une chaîne vide sous une clé de test, puis comparer metadata_exists('post', …) et get_post_meta(…, true). La première fonction doit constater la présence de la clé, alors que la seconde renvoie une valeur vide. Supprimer la clé et répéter pour constater la différence entre « vide » et « jamais enregistré ».

Précautions et limites

Ne pas employer cette fonction pour établir un droit d’accès : elle ne vérifie ni permissions, ni légitimité d’une valeur, ni statut public de la donnée.