add_metadata( string $meta_type, int $object_id, string $meta_key, mixed $meta_value, bool $unique = false ): int|false
- Since
- 2.9.0
- Source
wp-includes/meta.php:40
Description
For historical reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
Compatibility
- WordPress
- since 2.9.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$meta_typestring- Type of object metadata is for. Accepts 'blog', 'post', 'comment', 'term', 'user', or any other object type with an associated meta table.
$object_idint- ID of the object metadata is for.
$meta_keystring- Metadata key.
$meta_valuemixed- 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. $uniquebooloptional- 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.Default:false
Return value
int|false- The meta ID on success, false on failure.
Performance profile
How much work a call to add_metadata() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Heavy
- Scaling
- Constant
- Instructions
- 8–115
- Plugin surface
- 3 hooks
- Called by
- 9
Reaches the database via ->get_var().
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 121.
Third-party callbacks on 'add_{$meta_type}_metadata', 'add_{$meta_type}_meta', 'added_{$meta_type}_meta' run inside this call, and their cost is not bounded by anything here.
9 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
apply_filters()called directly - serializeserialisation
maybe_serialize()called directly - cacheobject cache
wp_cache_delete()called directly - sqldatabase query
->get_var()called directly - querycontent query
get_term()one call below add_metadata()
Further down the call graph this can also reach option and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 9 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost add_metadata() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 8–11 | none |
$object_id | 16 | absint() |
$object_id | 21 | absint(), _get_meta_table() |
$object_id && $check !== null | 60 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters() |
$object_id && $check === null && ->get_var() | 75 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), ->prepare(), ->get_var() |
$object_id && $check === null | 84 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), maybe_serialize(), do_action() |
$object_id && $check === null && !->get_var() | 98 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), ->prepare(), ->get_var(), maybe_serialize(), do_action() |
$object_id && $check === null | 101 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), maybe_serialize(), do_action(), wp_cache_delete(), do_action() |
$object_id && $check === null && !->get_var() | 115 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), ->prepare(), ->get_var(), maybe_serialize(), do_action(), wp_cache_delete(), do_action() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 121 | 8–115 | 9 | |
| 8.5 | 121 | 8–115 | 9 | |
| 8.4 | 121 | 8–115 | 9 | 2 fewer instructions than PHP 8.3 |
| 8.3 | 123 | 8–117 | 9 | |
| 8.2 | 123 | 8–117 | 9 | |
| 8.1 | 123 | 8–117 | 9 | |
| 7.4 | 123 | 8–117 | 9 |
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Hooks and filters fired · 3
3 hooks fire while add_metadata() runs, in this order:
- apply_filters( add_{$meta_type}_metadata )filterline 90 (+50 into the body)
Short-circuits adding metadata of a specific type.
- do_action( add_{$meta_type}_meta )actionline 128 (+88 into the body)
Fires immediately before meta of a specific type is added.
- do_action( added_{$meta_type}_meta )actionline 168 (+128 into the body)
Fires immediately after meta of a specific type is added.
Uses · 10
- absint()Converts a value to non-negative integer.
- _get_meta_table()Retrieves the name of the metadata table for the specified object type.
- get_object_subtype()Returns the object subtype for a given object ID of a specific type.
- sanitize_key()Sanitizes a string key.
- wp_unslash()Removes slashes from a string or recursively removes slashes from strings within an array.
- sanitize_meta()Sanitizes meta value.
- apply_filters()Calls the callback functions that have been added to a filter hook.
- maybe_serialize()Serializes data, if needed.
- do_action()Calls the callback functions that have been added to an action hook.
- wp_cache_delete()Removes the cache contents matching key and group.
Used by · 9
- WP_REST_Meta_Fields::update_multi_meta_value()Updates multiple meta values for an object.
- _wp_copy_post_meta()Copy post meta for the given key from one post to another.
- add_comment_meta()Adds meta data field to a comment.
- add_post_meta()Adds a meta field to the given post.
- add_site_meta()Adds metadata to a site.
- add_term_meta()Adds metadata to a term.
- add_user_meta()Adds meta data to a user.
- update_metadata()Updates metadata for the specified object. If no value already exists for the specified object ID and metadata key, the metadata will be added.
- wp_autosave_post_revisioned_meta_fields()Autosaves the revisioned meta fields.
Source code
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 * (blog, 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_blog_metadata` * - `add_post_metadata` * - `add_comment_metadata` * - `add_term_metadata` * - `add_user_metadata` * * @since 3.1.0 * * @param null|int|false $check Whether to allow adding metadata for the given type. Return false or a meta ID * to short-circuit the function. Return null to continue with the default behavior. * @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 * (blog, post, comment, term, user, or any other type with an associated meta table). * * Possible hook names include: * * - `add_blog_meta` * - `add_post_meta` * - `add_comment_meta` * - `add_term_meta`Changelog
Introduced in 2.9.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 7.0.4 tag, from
src/wp-includes/meta.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.