apply_filters( "update_{$meta_type}_metadata", null|bool $check, int $object_id, string $meta_key, mixed $meta_value, mixed $prev_value )

Short-circuits updating metadata of a specific type.


Description

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

Top ↑

Parameters

$check

(null|bool) Whether to allow updating metadata for the given type.

$object_id

(int) ID of the object metadata is for.

$meta_key

(string) Metadata key.

$meta_value

(mixed) Metadata value. Must be serializable if non-scalar.

$prev_value

(mixed) Previous value to check before updating. If specified, only update existing metadata entries with this value. Otherwise, update all entries.


Top ↑

More Information

  • This filter is applied before a metadata gets updated; it allows short-circuiting the updating of metadata of a specific type by returning a non-null value.
  • The dynamic portion of the hook, $meta_type, refers to the meta object type. For example, if a ‘user’ metadata gets updated, the hook would be ‘update_user_metadata‘.
  • The filter must return a null value (the value of $check) if the data is be saved to the database. If it returns anything else, the ‘update_metadata‘ function (and therefore the ‘update_{$meta_type}_metadata‘ filter) will return what the filter callbacks return.

Top ↑

Source

File: wp-includes/meta.php

View on Trac



Top ↑

Changelog

Changelog
Version Description
3.1.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    Contributed by Steven Lin

    Example migrated from Codex:

    The example below skips saving the metadata with the key ‘foo’ and an empty value. For other metadata, continue the normal execution.

    add_action( 'init', 'wpdocs_init' );
    
    function wpdocs_init() {
       add_filter( 'update_user_metadata', 'wpdocs_update_foo', 10, 4 );
    }
    
    function wpdocs_update_foo( $check, $object_id, $meta_key, $meta_value ) {
    
       if ( 'foo' == $meta_key && empty( $meta_value ) ) {
          return false; // this means: stop saving the value into the database
       }
    
       return $check; // this means: go on with the normal execution in meta.php
    }
    
  2. Skip to note 2 content
    Contributed by crstauf

    Similar to stevenlinx’s example, to skip saving empty value of foo to user metadata. Note that this could create problems if the user is attempting to clear previously entered data; an additional hook should be included that deletes the foo key from the user’s metadata if the value is empty.

    add_filter( 'update_user_metadata', function( $check, $object_id, $meta_key, $meta_value ) {
    
        // Already short-circuited; bail.
        if ( null !== $check )
            return $check;
    
        // Bail if not saving the 'foo' metadata.
        if ( 'foo' !== $meta_key )
            return null;
    
        // If meta value is not empty, then we _want_ to save it.
        if ( ! empty( $meta_value ) )
            return null;
    
        // Prevent saving empty value to user's 'foo' metadata.
        return false;
    }, 10, 4 );
    

You must log in before being able to contribute a note or feedback.