add_metadata() │ WP 2.9.0

Add metadata (an additional data) for the specified object (a post, a comment, a user etc).

This is a basic function for metadata management. All other custom fields functions work on its basis. You can also create a custom metadata table in the DB and add/remove data there with this function (see an example below).

Related functions:

update_metadata( $meta_type, $object_id, $meta_key, $meta_value, [$prev_value] )
// you can use it instead of `add_metadata()`, as it first checks if the key exists.

delete_metadata( $meta_type, $object_id, $meta_key, [$meta_value], [$delete_all] )
// removes a metadata by key.

get_metadata( $meta_type, $object_id, [$meta_key], [$single] )
// gets a metadata by key.

Default WordPress metadata tables

This function implies the existence of the necessary tables in the database, where the metadata will be added. By default, there are 4 tables in the DB for different types of objects (posts, comments, users, taxonomy items):

wp_commentmeta: Comments Metadata.
wp_postmeta: Posts Metadata. Here are stored "custom fields" of the posts.
wp_usermeta: User Metadata. Additional data about the user.
wp_termmeta: Taxonomy Metadata. Additional data for the taxonomy items. Since version 4.4.

Used By: add_term_meta(), add_user_meta(), add_comment_meta(), add_post_meta(), update_metadata()

Hooks from the function

add_(meta_type)_metadata

add_post_metadata

add_comment_metadata

add_term_metadata

add_user_metadata

add_(meta_type)_meta

added_(meta_type)_meta

Returns

Int|false. The meta ID on success, false on failure.

Usage

add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique );

$meta_type(string) (required): Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', or any other object type with an associated meta table.
$object_id(int) (required): ID of the object metadata is for.
$meta_key(string) (required): Metadata key.
$meta_value(mixed) (required): Metadata value. Arrays and objects are stored as serialized data and will be returned as the same type when retrieved. Other data types will be stored as strings in the database:

false is stored and retrieved as an empty string ('')
true is stored and retrieved as '1'
numbers (both integer and float) are stored and retrieved as strings Must be serializable if non-scalar.

$unique(true|false): Whether the specified metadata key should be unique for the object. If true, and the object already has a value for the specified metadata key, no change will be made.
Default: false

Examples

#1 Create a custom metadata table

Plugin developers may need to create such tables. Creation should occurs at the stage of plugin activation with register_activation_hook() function. Similar tables can be created by other plugins, so check if it exists before the creation of the table.

An example on how to create a term metadata table:

global $wpdb;
$result = false;
// Create a table in the DB if it doesn't exist yet
$sql = sprintf(
	'CREATE TABLE IF NOT EXISTS `%stermmeta` (
	  meta_id bigint(20) UNSIGNED NOT NULL auto_increment,
	  term_id bigint(20) UNSIGNED NOT NULL,
	  meta_key varchar(255),
	  meta_value longtext,
	  PRIMARY KEY (meta_id)
	)',
	$wpdb->prefix
);

$result = $wpdb->query( $sql );

Note! After the table has been created, it should be registered in $wpdb object in order to make it easier to work with it through the $wpdb class

For the registration, add a property $wpdb->termmeta to the object that should contain the name of the table (it's recommended to do it as early as you can — before the usage of the custom functions):

global $wpdb;
$wpdb->termmeta = $wpdb->prefix.'termmeta';

#2 Add metadata into the `term` table

Now, when the table has been created, you can add data like so:

add_metadata( 'term', $_GET['tag_ID'], 'gender', 'M' ,true );
add_metadata( 'term', $_GET['tag_ID'], 'age', '29', true );
add_metadata( 'term', $_GET['tag_ID'], 'favourite_colour', 'Green', true );

-9

#3 Add the metadata for the comment with ID 45

add_metadata( 'comment', 45, 'vocation', 'Builder', true );

Notes

Global. wpdb. $wpdb WordPress database abstraction object.

Changelog

Since 2.9.0

Introduced.

`add_metadata() add metadata` code ^{WP 6.8.3}

wp-includes/meta.php

function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique = false ) {
	global $wpdb;

	if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) ) {
		return false;
	}

	$object_id = absint( $object_id );
	if ( ! $object_id ) {
		return false;
	}

	$table = _get_meta_table( $meta_type );
	if ( ! $table ) {
		return false;
	}

	$meta_subtype = get_object_subtype( $meta_type, $object_id );

	$column = sanitize_key( $meta_type . '_id' );

	// expected_slashed ($meta_key)
	$meta_key   = wp_unslash( $meta_key );
	$meta_value = wp_unslash( $meta_value );
	$meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type, $meta_subtype );

	/**
	 * Short-circuits adding metadata of a specific type.
	 *
	 * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type
	 * (post, comment, term, user, or any other type with an associated meta table).
	 * Returning a non-null value will effectively short-circuit the function.
	 *
	 * Possible hook names include:
	 *
	 *  - `add_post_metadata`
	 *  - `add_comment_metadata`
	 *  - `add_term_metadata`
	 *  - `add_user_metadata`
	 *
	 * @since 3.1.0
	 *
	 * @param null|bool $check      Whether to allow adding metadata for the given type.
	 * @param int       $object_id  ID of the object metadata is for.
	 * @param string    $meta_key   Metadata key.
	 * @param mixed     $meta_value Metadata value. Must be serializable if non-scalar.
	 * @param bool      $unique     Whether the specified meta key should be unique for the object.
	 */
	$check = apply_filters( "add_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $unique );
	if ( null !== $check ) {
		return $check;
	}

	if ( $unique && $wpdb->get_var(
		$wpdb->prepare(
			"SELECT COUNT(*) FROM $table WHERE meta_key = %s AND $column = %d",
			$meta_key,
			$object_id
		)
	) ) {
		return false;
	}

	$_meta_value = $meta_value;
	$meta_value  = maybe_serialize( $meta_value );

	/**
	 * Fires immediately before meta of a specific type is added.
	 *
	 * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type
	 * (post, comment, term, user, or any other type with an associated meta table).
	 *
	 * Possible hook names include:
	 *
	 *  - `add_post_meta`
	 *  - `add_comment_meta`
	 *  - `add_term_meta`
	 *  - `add_user_meta`
	 *
	 * @since 3.1.0
	 *
	 * @param int    $object_id   ID of the object metadata is for.
	 * @param string $meta_key    Metadata key.
	 * @param mixed  $_meta_value Metadata value.
	 */
	do_action( "add_{$meta_type}_meta", $object_id, $meta_key, $_meta_value );

	$result = $wpdb->insert(
		$table,
		array(
			$column      => $object_id,
			'meta_key'   => $meta_key,
			'meta_value' => $meta_value,
		)
	);

	if ( ! $result ) {
		return false;
	}

	$mid = (int) $wpdb->insert_id;

	wp_cache_delete( $object_id, $meta_type . '_meta' );

	/**
	 * Fires immediately after meta of a specific type is added.
	 *
	 * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type
	 * (post, comment, term, user, or any other type with an associated meta table).
	 *
	 * Possible hook names include:
	 *
	 *  - `added_post_meta`
	 *  - `added_comment_meta`
	 *  - `added_term_meta`
	 *  - `added_user_meta`
	 *
	 * @since 2.9.0
	 *
	 * @param int    $mid         The meta ID after successful update.
	 * @param int    $object_id   ID of the object metadata is for.
	 * @param string $meta_key    Metadata key.
	 * @param mixed  $_meta_value Metadata value.
	 */
	do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value );

	return $mid;
}