add_post_meta( int $post_id, string $meta_key, mixed $meta_value, bool $unique = false )

Ajoute un champ de méta-donné à un post donné.

Paramètres

$post_id(int)requis

Id du poste.

$meta_key(string)requis

Nom de la méta-donnée.

$meta_value(mixed)requis

Valeur de la méta-donnée. Doit être sérialisable si non scalaire.

$unique(bool)optionnel

False pour qu'une clé identique ne soit pas ajoutée à un poste déjà lié à une méta-donnée qui possède la même clé.

Valeur par défaut : false

Description / Informations supplémentaires

Les champs de méta-donné de poste sont appelés "champs personnalisés" dans l"administration WordPress.

Si vous voulez mettre à jour une méta-donnée, utilisez update_post_meta(). Cette fonction peut aussi être utilisée pour ajouter un champ de méta-donné si sa clé n'existe pas.

Comme les valeurs de méta sont passées à la fonction stripslashes() il faut faire attention au contenu échappé avec des caractères \ (anti-slashes). Pour en savoir plus sur ce comportement et sur un exemple de contournement, voir la documentation de update_post_meta().

Il est intéressant de noter que WordPress ne montrera pas les champs personnalisés dont la clé commence par un underscore '_' dans la liste des champs personnalisés dans l'écran d'édition d'un poste (dans l'administration) ni avec la fonction the_meta().

Il faut aussi noter que si $meta_value est un tableau elle n'apparaîtra pas non plus dans la liste des champs personnalisés.

Retourne

(int|false) Id de la méta-donnée si succès, false autrement.

Déclaration et structure de la fonction add_post_meta()

function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) {
    // Make sure meta is added to the post, not a revision.
    $the_post = wp_is_post_revision( $post_id );
    if ( $the_post ) {
        $post_id = $the_post;
    }

    return add_metadata( 'post', $post_id, $meta_key, $meta_value, $unique );
}
wp_is_post_revision()

Détermine si un poste spécifié est une révision.

add_metadata()

Ajoute une méta-donnée pour un objet spécifié.

Où est utilisée la fonction add_post_meta() dans le CMS WordPress

Exemples

Usage par défaut :
add_post_meta( 68, 'my_key', 47 );
Ajouter un champ personnalisé unique qui n'apparaîtra pas dans la liste des champs personnlisés :
add_post_meta( 68, '_color', 'red', true );
Ajouter un nouveau champ personnalisé si la clé n'existe pas sinon mettre à jour :
if ( ! add_post_meta( 7, 'fruit', 'banana', true ) ) { 
   update_post_meta ( 7, 'fruit', 'banana' );
}

Sources

Codex WordPress : add_post_meta()

Autres fonctions dans le même fichier : wp-includes/post.php

Retour