WordPress.org

Make WordPress Core

Changeset 13300


Ignore:
Timestamp:
02/22/2010 06:35:35 PM (8 years ago)
Author:
nacin
Message:

Introduce *_user_meta() functions, deprecate *_usermeta() family. Fixes #10837 props scribu, technosailor.

Location:
trunk/wp-includes
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/deprecated.php

    r13299 r13300  
    22672267}
    22682268
    2269 ?>
     2269/**
     2270 * Remove user meta data.
     2271 *
     2272 * @since 2.0.0
     2273 * @deprecated 3.0.0
     2274 * @deprecated Use delete_user_meta()
     2275 * @see delete_user_meta()
     2276 *
     2277 * @param int $user_id User ID.
     2278 * @param string $meta_key Metadata key.
     2279 * @param mixed $meta_value Metadata value.
     2280 * @return bool True deletion completed and false if user_id is not a number.
     2281 */
     2282function delete_usermeta( $user_id, $meta_key, $meta_value = '' ) {
     2283    _deprecated_function( __FUNCTION__, '3.0', 'delete_user_meta()' );
     2284    return delete_user_meta( $user_id, $meta_key, $meta_value );
     2285}
     2286
     2287/**
     2288 * Retrieve user metadata.
     2289 *
     2290 * If $user_id is not a number, then the function will fail over with a 'false'
     2291 * boolean return value. Other returned values depend on whether there is only
     2292 * one item to be returned, which be that single item type. If there is more
     2293 * than one metadata value, then it will be list of metadata values.
     2294 *
     2295 * @since 2.0.0
     2296 * @deprecated 3.0.0
     2297 * @deprecated Use get_user_meta()
     2298 * @see get_user_meta()
     2299 *
     2300 * @param int $user_id User ID
     2301 * @param string $meta_key Optional. Metadata key.
     2302 * @return mixed
     2303 */
     2304function get_usermeta( $user_id, $meta_key = '') {
     2305    _deprecated_function( __FUNCTION__, '3.0', 'get_user_meta()' );
     2306    return get_user_meta( $user_id, $meta_key, false );
     2307}
     2308
     2309/**
     2310 * Update metadata of user.
     2311 *
     2312 * There is no need to serialize values, they will be serialized if it is
     2313 * needed. The metadata key can only be a string with underscores. All else will
     2314 * be removed.
     2315 *
     2316 * Will remove the metadata, if the meta value is empty.
     2317 *
     2318 * @since 2.0.0
     2319 * @deprecated 3.0.0
     2320 * @deprecated Use update_user_meta()
     2321 * @see update_user_meta()
     2322 *
     2323 * @param int $user_id User ID
     2324 * @param string $meta_key Metadata key.
     2325 * @param mixed $meta_value Metadata value.
     2326 * @return bool True on successful update, false on failure.
     2327 */
     2328function update_usermeta( $user_id, $meta_key, $meta_value ) {
     2329    _deprecated_function( __FUNCTION__, '3.0', 'update_user_meta()' );
     2330    return update_user_meta( $user_id, $meta_key, $meta_value );
     2331}
  • trunk/wp-includes/user.php

    r13220 r13300  
    293293}
    294294
    295 //
    296 // User meta functions
    297 //
    298 
    299 /**
    300  * Remove user meta data.
    301  *
    302  * @since 2.0.0
    303  * @uses $wpdb WordPress database object for queries.
    304  *
    305  * @param int $user_id User ID.
    306  * @param string $meta_key Metadata key.
    307  * @param mixed $meta_value Metadata value.
    308  * @return bool True deletion completed and false if user_id is not a number.
    309  */
    310 function delete_usermeta( $user_id, $meta_key, $meta_value = '' ) {
    311     global $wpdb;
    312     if ( !is_numeric( $user_id ) )
    313         return false;
    314     $meta_key = preg_replace('|[^a-z0-9_]|i', '', $meta_key);
    315 
    316     if ( is_array($meta_value) || is_object($meta_value) )
    317         $meta_value = serialize($meta_value);
    318     $meta_value = trim( $meta_value );
    319 
    320     $cur = $wpdb->get_row( $wpdb->prepare("SELECT * FROM $wpdb->usermeta WHERE user_id = %d AND meta_key = %s", $user_id, $meta_key) );
    321 
    322     if ( $cur && $cur->umeta_id )
    323         do_action( 'delete_usermeta', $cur->umeta_id, $user_id, $meta_key, $meta_value );
    324 
    325     if ( ! empty($meta_value) )
    326         $wpdb->query( $wpdb->prepare("DELETE FROM $wpdb->usermeta WHERE user_id = %d AND meta_key = %s AND meta_value = %s", $user_id, $meta_key, $meta_value) );
    327     else
    328         $wpdb->query( $wpdb->prepare("DELETE FROM $wpdb->usermeta WHERE user_id = %d AND meta_key = %s", $user_id, $meta_key) );
    329 
    330     wp_cache_delete($user_id, 'users');
    331 
    332     if ( $cur && $cur->umeta_id )
    333         do_action( 'deleted_usermeta', $cur->umeta_id, $user_id, $meta_key, $meta_value );
    334 
    335     return true;
    336 }
    337 
    338 /**
    339  * Retrieve user metadata.
    340  *
    341  * If $user_id is not a number, then the function will fail over with a 'false'
    342  * boolean return value. Other returned values depend on whether there is only
    343  * one item to be returned, which be that single item type. If there is more
    344  * than one metadata value, then it will be list of metadata values.
    345  *
    346  * @since 2.0.0
    347  * @uses $wpdb WordPress database object for queries.
    348  *
    349  * @param int $user_id User ID
    350  * @param string $meta_key Optional. Metadata key.
    351  * @return mixed
    352  */
    353 function get_usermeta( $user_id, $meta_key = '') {
    354     global $wpdb;
    355     $user_id = (int) $user_id;
    356 
    357     if ( !$user_id )
    358         return false;
    359 
    360     if ( !empty($meta_key) ) {
    361         $meta_key = preg_replace('|[^a-z0-9_]|i', '', $meta_key);
    362         $user = wp_cache_get($user_id, 'users');
    363         // Check the cached user object
    364         if ( false !== $user && isset($user->$meta_key) )
    365             $metas = array($user->$meta_key);
    366         else
    367             $metas = $wpdb->get_col( $wpdb->prepare("SELECT meta_value FROM $wpdb->usermeta WHERE user_id = %d AND meta_key = %s", $user_id, $meta_key) );
    368     } else {
    369         $metas = $wpdb->get_col( $wpdb->prepare("SELECT meta_value FROM $wpdb->usermeta WHERE user_id = %d", $user_id) );
    370     }
    371 
    372     if ( empty($metas) ) {
    373         if ( empty($meta_key) )
    374             return array();
    375         else
    376             return '';
    377     }
    378 
    379     $metas = array_map('maybe_unserialize', $metas);
    380 
    381     if ( count($metas) == 1 )
    382         return $metas[0];
    383     else
    384         return $metas;
    385 }
    386 
    387 /**
    388  * Update metadata of user.
    389  *
    390  * There is no need to serialize values, they will be serialized if it is
    391  * needed. The metadata key can only be a string with underscores. All else will
    392  * be removed.
    393  *
    394  * Will remove the metadata, if the meta value is empty.
    395  *
    396  * @since 2.0.0
    397  * @uses $wpdb WordPress database object for queries
    398  *
    399  * @param int $user_id User ID
    400  * @param string $meta_key Metadata key.
    401  * @param mixed $meta_value Metadata value.
    402  * @return bool True on successful update, false on failure.
    403  */
    404 function update_usermeta( $user_id, $meta_key, $meta_value ) {
    405     global $wpdb;
    406     if ( !is_numeric( $user_id ) )
    407         return false;
    408     $meta_key = preg_replace('|[^a-z0-9_]|i', '', $meta_key);
    409 
    410     /** @todo Might need fix because usermeta data is assumed to be already escaped */
    411     if ( is_string($meta_value) )
    412         $meta_value = stripslashes($meta_value);
    413     $meta_value = maybe_serialize($meta_value);
    414 
    415     if (empty($meta_value)) {
    416         return delete_usermeta($user_id, $meta_key);
    417     }
    418 
    419     $cur = $wpdb->get_row( $wpdb->prepare("SELECT * FROM $wpdb->usermeta WHERE user_id = %d AND meta_key = %s", $user_id, $meta_key) );
    420 
    421     if ( $cur )
    422         do_action( 'update_usermeta', $cur->umeta_id, $user_id, $meta_key, $meta_value );
    423 
    424     if ( !$cur )
    425         $wpdb->insert($wpdb->usermeta, compact('user_id', 'meta_key', 'meta_value') );
    426     else if ( $cur->meta_value != $meta_value )
    427         $wpdb->update($wpdb->usermeta, compact('meta_value'), compact('user_id', 'meta_key') );
    428     else
    429         return false;
    430 
    431     wp_cache_delete($user_id, 'users');
    432 
    433     if ( !$cur )
    434         do_action( 'added_usermeta', $wpdb->insert_id, $user_id, $meta_key, $meta_value );
    435     else
    436         do_action( 'updated_usermeta', $cur->umeta_id, $user_id, $meta_key, $meta_value );
    437 
    438     return true;
     295/**
     296 * Add meta data field to a user.
     297 *
     298 * Post meta data is called "Custom Fields" on the Administration Panels.
     299 *
     300 * @since 3.0.0
     301 * @uses add_metadata()
     302 * @link http://codex.wordpress.org/Function_Reference/add_user_meta
     303 *
     304 * @param int $user_id Post ID.
     305 * @param string $key Metadata name.
     306 * @param mixed $value Metadata value.
     307 * @param bool $unique Optional, default is false. Whether the same key should not be added.
     308 * @return bool False for failure. True for success.
     309 */
     310function add_user_meta($user_id, $meta_key, $meta_value, $unique = false) {
     311    return add_metadata('user', $user_id, $meta_key, $meta_value, $unique);
     312}
     313
     314/**
     315 * Remove metadata matching criteria from a user.
     316 *
     317 * You can match based on the key, or key and value. Removing based on key and
     318 * value, will keep from removing duplicate metadata with the same key. It also
     319 * allows removing all metadata matching key, if needed.
     320 *
     321 * @since 3.0.0
     322 * @uses delete_metadata()
     323 * @link http://codex.wordpress.org/Function_Reference/delete_user_meta
     324 *
     325 * @param int $user_id user ID
     326 * @param string $meta_key Metadata name.
     327 * @param mixed $meta_value Optional. Metadata value.
     328 * @return bool False for failure. True for success.
     329 */
     330function delete_user_meta($user_id, $meta_key, $meta_value = '') {
     331    return delete_metadata('user', $user_id, $meta_key, $meta_value);
     332}
     333
     334/**
     335 * Retrieve user meta field for a user.
     336 *
     337 * @since 3.0.0
     338 * @uses get_metadata()
     339 * @link http://codex.wordpress.org/Function_Reference/get_user_meta
     340 *
     341 * @param int $user_id Post ID.
     342 * @param string $key The meta key to retrieve.
     343 * @param bool $single Whether to return a single value.
     344 * @return mixed Will be an array if $single is false. Will be value of meta data field if $single
     345 *  is true.
     346 */
     347function get_user_meta($user_id, $key, $single = false) {
     348    return get_metadata('user', $user_id, $key, $single);
     349}
     350
     351/**
     352 * Update user meta field based on user ID.
     353 *
     354 * Use the $prev_value parameter to differentiate between meta fields with the
     355 * same key and user ID.
     356 *
     357 * If the meta field for the user does not exist, it will be added.
     358 *
     359 * @since 3.0
     360 * @uses update_metadata
     361 * @link http://codex.wordpress.org/Function_Reference/update_user_meta
     362 *
     363 * @param int $user_id Post ID.
     364 * @param string $key Metadata key.
     365 * @param mixed $value Metadata value.
     366 * @param mixed $prev_value Optional. Previous value to check before removing.
     367 * @return bool False on failure, true if success.
     368 */
     369function update_user_meta($user_id, $meta_key, $meta_value, $prev_value = '') {
     370    return update_metadata('user', $user_id, $meta_key, $meta_value, $prev_value);
    439371}
    440372
Note: See TracChangeset for help on using the changeset viewer.