add_metadata()
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).
Read also: Metadata in WordPress
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.
Hooks from the function
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 );
#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. |