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_user_meta

add_(meta_type)_meta

add_post_meta

add_comment_meta

add_term_meta

added_(meta_type)_meta

Return

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. 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.5.2}

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;
}