update_metadata( string $meta_type, int $object_id, string $meta_key, mixed $meta_value, mixed $prev_value = '' ): int|bool
- Since
- 2.9.0
- Source
wp-includes/meta.php:188
Updates metadata for the specified object. If no value already exists for the specified object ID and metadata key, the metadata will be added.
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 '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. Must be serializable if non-scalar.
$prev_valuemixedoptional- Previous value to check before updating.
If specified, only update existing metadata entries with this value. Otherwise, update all entries. Default empty string.Default:''
Return value
int|bool- The new meta field ID if a field with the given key didn't exist and was therefore added, true on successful update, false on failure or if the value passed to the function is the same as the one that is already in the database.
Performance profile
How much work a call to update_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
- Scales with input
- Instructions
- 8–141
- Plugin surface
- 5 hooks
- Called by
- 7
Reaches the database via ->get_col().
The body loops, so the work grows with what you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 196.
Third-party callbacks on 'update_{$meta_type}_metadata', 'update_{$meta_type}_meta', 'update_postmeta' run inside this call, and their cost is not bounded by anything here.
7 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_col()called directly - querycontent query
get_term()one call below update_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 · 15 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost update_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 | 67–68 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters() |
$object_id && $check === null && empty($prev_value) && is_countable() && $meta_value === false | 84–85 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), get_metadata_raw(), is_countable() |
$object_id && $check === null && !empty($prev_value) && empty($meta_ids) | 92–93 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), ->prepare(), ->get_col(), add_metadata() |
$object_id && $check === null && empty($prev_value) && empty($meta_ids) | 102–109 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), get_metadata_raw(), is_countable(), ->prepare(), ->get_col(), add_metadata() |
$object_id && $check === null && !empty($meta_ids) | 109–111 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), ->prepare(), ->get_col(), maybe_serialize(), compact(), ->update() |
$object_id && $check === null && !empty($prev_value) && !empty($meta_ids) | 115–117 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), ->prepare(), ->get_col(), maybe_serialize(), compact(), maybe_serialize(), ->update() |
$object_id && $check === null && !empty($meta_ids) | 116–119 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), ->prepare(), ->get_col(), maybe_serialize(), compact(), ->update(), wp_cache_delete() |
$object_id && $check === null && empty($prev_value) && !empty($meta_ids) | 119–127 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), get_metadata_raw(), is_countable(), ->prepare(), ->get_col(), maybe_serialize(), compact(), ->update() |
$object_id && $check === null && !empty($prev_value) && !empty($meta_ids) | 122–125 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), ->prepare(), ->get_col(), maybe_serialize(), compact(), maybe_serialize(), ->update(), wp_cache_delete() |
3 further outcomes, up to 141 instructions
$object_id && $check === null && !empty($meta_ids) | 125–133 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), get_metadata_raw(), is_countable(), ->prepare(), ->get_col(), maybe_serialize(), compact(), maybe_serialize(), ->update() |
$object_id && $check === null && empty($prev_value) && !empty($meta_ids) | 126–135 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), get_metadata_raw(), is_countable(), ->prepare(), ->get_col(), maybe_serialize(), compact(), ->update(), wp_cache_delete() |
$object_id && $check === null && !empty($meta_ids) | 132–141 | absint(), _get_meta_table(), get_object_subtype(), sanitize_key(), wp_unslash(), wp_unslash(), sanitize_meta(), apply_filters(), get_metadata_raw(), is_countable(), ->prepare(), ->get_col(), maybe_serialize(), compact(), maybe_serialize(), ->update(), wp_cache_delete() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 196 | 8–141 | 20 | |
| 8.5 | 196 | 8–141 | 20 | |
| 8.4 | 196 | 8–141 | 20 | 2 fewer instructions than PHP 8.3 |
| 8.3 | 198 | 8–143 | 20 | |
| 8.2 | 198 | 8–143 | 20 | |
| 8.1 | 198 | 8–143 | 20 | |
| 7.4 | 198 | 8–143 | 20 |
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 · 5
5 hooks fire while update_metadata() runs, in this order:
- apply_filters( update_{$meta_type}_metadata )filterline 241 (+53 into the body)
Short-circuits updating metadata of a specific type.
- do_action( update_{$meta_type}_meta )actionline 296 (+108 into the body)
Fires immediately before updating metadata of a specific type.
- do_action( update_postmeta )actionline 310 (+122 into the body)
Fires immediately before updating a post's metadata.
- do_action( updated_{$meta_type}_meta )actionline 342 (+154 into the body)
Fires immediately after updating metadata of a specific type.
- do_action( updated_postmeta )actionline 356 (+168 into the body)
Fires immediately after updating a post's metadata.
Uses · 13
- 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.
- get_metadata_raw()Retrieves raw metadata value for the specified object.
- is_countable()Polyfill for is_countable() function added in PHP 7.3.
- add_metadata()Adds metadata for the specified object.
- maybe_serialize()Serializes data, if needed.
- do_action()Calls the callback functions that have been added to an action hook.
Show all 13
- wp_cache_delete()Removes the cache contents matching key and group.
Used by · 7
- WP_REST_Autosaves_Controller::create_post_autosave()Creates autosave for the specified post.
- WP_REST_Meta_Fields::update_meta_value()Updates a meta value for an object.
- update_comment_meta()Updates comment meta field based on comment ID.
- update_post_meta()Updates a post meta field based on the given post ID.
- update_site_meta()Updates metadata for a site.
- update_term_meta()Updates term metadata.
- update_user_meta()Updates user meta field based on user ID.
Source code
function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_value = '' ) { 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' ); $id_column = ( 'user' === $meta_type ) ? 'umeta_id' : 'meta_id'; // expected_slashed ($meta_key) $raw_meta_key = $meta_key; $meta_key = wp_unslash( $meta_key ); $passed_value = $meta_value; $meta_value = wp_unslash( $meta_value ); $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type, $meta_subtype ); /** * Short-circuits updating 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: * * - `update_post_metadata` * - `update_comment_metadata` * - `update_term_metadata` * - `update_user_metadata` * * @since 3.1.0 * * @param null|bool $check Whether to allow updating 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 mixed $prev_value Optional. Previous value to check before updating. * If specified, only update existing metadata entries with * this value. Otherwise, update all entries. */ $check = apply_filters( "update_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $prev_value ); if ( null !== $check ) { return (bool) $check; } // Compare existing value to new value if no prev value given and the key exists only once. if ( empty( $prev_value ) ) { $old_value = get_metadata_raw( $meta_type, $object_id, $meta_key ); if ( is_countable( $old_value ) && count( $old_value ) === 1 ) { if ( $old_value[0] === $meta_value ) { return false; } } } $meta_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s AND $column = %d", $meta_key, $object_id ) ); if ( empty( $meta_ids ) ) { return add_metadata( $meta_type, $object_id, $raw_meta_key, $passed_value ); } $_meta_value = $meta_value; $meta_value = maybe_serialize( $meta_value ); $data = compact( 'meta_value' ); $where = array( $column => $object_id, 'meta_key' => $meta_key,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 6.8.8 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.