WordPress.org

Make WordPress Core

Changeset 13300


Ignore:
Timestamp:
02/22/10 18:35:35 (6 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.