Changeset 13300

Timestamp:

02/22/2010 06:35:35 PM (15 years ago)

Author:

nacin

Message:

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

Location:

trunk/wp-includes

Files:

• deprecated.php (modified) (1 diff)
• user.php (modified) (1 diff)

trunk/wp-includes/deprecated.php

@@ -2267 +2267 @@
 }
 
-?>
+/**
+ * Remove user meta data.
+ *
+ * @since 2.0.0
+ * @deprecated 3.0.0
+ * @deprecated Use delete_user_meta()
+ * @see delete_user_meta()
+ *
+ * @param int $user_id User ID.
+ * @param string $meta_key Metadata key.
+ * @param mixed $meta_value Metadata value.
+ * @return bool True deletion completed and false if user_id is not a number.
+ */
+function delete_usermeta( $user_id, $meta_key, $meta_value = '' ) {
+    _deprecated_function( __FUNCTION__, '3.0', 'delete_user_meta()' );
+    return delete_user_meta( $user_id, $meta_key, $meta_value );
+}
+
+/**
+ * Retrieve user metadata.
+ *
+ * If $user_id is not a number, then the function will fail over with a 'false'
+ * boolean return value. Other returned values depend on whether there is only
+ * one item to be returned, which be that single item type. If there is more
+ * than one metadata value, then it will be list of metadata values.
+ *
+ * @since 2.0.0
+ * @deprecated 3.0.0
+ * @deprecated Use get_user_meta()
+ * @see get_user_meta()
+ *
+ * @param int $user_id User ID
+ * @param string $meta_key Optional. Metadata key.
+ * @return mixed
+ */
+function get_usermeta( $user_id, $meta_key = '') {
+    _deprecated_function( __FUNCTION__, '3.0', 'get_user_meta()' );
+    return get_user_meta( $user_id, $meta_key, false );
+}
+
+/**
+ * Update metadata of user.
+ *
+ * There is no need to serialize values, they will be serialized if it is
+ * needed. The metadata key can only be a string with underscores. All else will
+ * be removed.
+ *
+ * Will remove the metadata, if the meta value is empty.
+ *
+ * @since 2.0.0
+ * @deprecated 3.0.0
+ * @deprecated Use update_user_meta()
+ * @see update_user_meta()
+ *
+ * @param int $user_id User ID
+ * @param string $meta_key Metadata key.
+ * @param mixed $meta_value Metadata value.
+ * @return bool True on successful update, false on failure.
+ */
+function update_usermeta( $user_id, $meta_key, $meta_value ) {
+    _deprecated_function( __FUNCTION__, '3.0', 'update_user_meta()' );
+    return update_user_meta( $user_id, $meta_key, $meta_value );
+}

trunk/wp-includes/user.php

@@ -293 +293 @@
 }
 
-//
-// User meta functions
-//
-
-/**
- * Remove user meta data.
- *
- * @since 2.0.0
- * @uses $wpdb WordPress database object for queries.
- *
- * @param int $user_id User ID.
- * @param string $meta_key Metadata key.
- * @param mixed $meta_value Metadata value.
- * @return bool True deletion completed and false if user_id is not a number.
- */
-function delete_usermeta( $user_id, $meta_key, $meta_value = '' ) {
-    global $wpdb;
-    if ( !is_numeric( $user_id ) )
-        return false;
-    $meta_key = preg_replace('|[^a-z0-9_]|i', '', $meta_key);
-
-    if ( is_array($meta_value) || is_object($meta_value) )
-        $meta_value = serialize($meta_value);
-    $meta_value = trim( $meta_value );
-
-    $cur = $wpdb->get_row( $wpdb->prepare("SELECT * FROM $wpdb->usermeta WHERE user_id = %d AND meta_key = %s", $user_id, $meta_key) );
-
-    if ( $cur && $cur->umeta_id )
-        do_action( 'delete_usermeta', $cur->umeta_id, $user_id, $meta_key, $meta_value );
-
-    if ( ! empty($meta_value) )
-        $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) );
-    else
-        $wpdb->query( $wpdb->prepare("DELETE FROM $wpdb->usermeta WHERE user_id = %d AND meta_key = %s", $user_id, $meta_key) );
-
-    wp_cache_delete($user_id, 'users');
-
-    if ( $cur && $cur->umeta_id )
-        do_action( 'deleted_usermeta', $cur->umeta_id, $user_id, $meta_key, $meta_value );
-
-    return true;
-}
-
-/**
- * Retrieve user metadata.
- *
- * If $user_id is not a number, then the function will fail over with a 'false'
- * boolean return value. Other returned values depend on whether there is only
- * one item to be returned, which be that single item type. If there is more
- * than one metadata value, then it will be list of metadata values.
- *
- * @since 2.0.0
- * @uses $wpdb WordPress database object for queries.
- *
- * @param int $user_id User ID
- * @param string $meta_key Optional. Metadata key.
- * @return mixed
- */
-function get_usermeta( $user_id, $meta_key = '') {
-    global $wpdb;
-    $user_id = (int) $user_id;
-
-    if ( !$user_id )
-        return false;
-
-    if ( !empty($meta_key) ) {
-        $meta_key = preg_replace('|[^a-z0-9_]|i', '', $meta_key);
-        $user = wp_cache_get($user_id, 'users');
-        // Check the cached user object
-        if ( false !== $user && isset($user->$meta_key) )
-            $metas = array($user->$meta_key);
-        else
-            $metas = $wpdb->get_col( $wpdb->prepare("SELECT meta_value FROM $wpdb->usermeta WHERE user_id = %d AND meta_key = %s", $user_id, $meta_key) );
-    } else {
-        $metas = $wpdb->get_col( $wpdb->prepare("SELECT meta_value FROM $wpdb->usermeta WHERE user_id = %d", $user_id) );
-    }
-
-    if ( empty($metas) ) {
-        if ( empty($meta_key) )
-            return array();
-        else
-            return '';
-    }
-
-    $metas = array_map('maybe_unserialize', $metas);
-
-    if ( count($metas) == 1 )
-        return $metas[0];
-    else
-        return $metas;
-}
-
-/**
- * Update metadata of user.
- *
- * There is no need to serialize values, they will be serialized if it is
- * needed. The metadata key can only be a string with underscores. All else will
- * be removed.
- *
- * Will remove the metadata, if the meta value is empty.
- *
- * @since 2.0.0
- * @uses $wpdb WordPress database object for queries
- *
- * @param int $user_id User ID
- * @param string $meta_key Metadata key.
- * @param mixed $meta_value Metadata value.
- * @return bool True on successful update, false on failure.
- */
-function update_usermeta( $user_id, $meta_key, $meta_value ) {
-    global $wpdb;
-    if ( !is_numeric( $user_id ) )
-        return false;
-    $meta_key = preg_replace('|[^a-z0-9_]|i', '', $meta_key);
-
-    /** @todo Might need fix because usermeta data is assumed to be already escaped */
-    if ( is_string($meta_value) )
-        $meta_value = stripslashes($meta_value);
-    $meta_value = maybe_serialize($meta_value);
-
-    if (empty($meta_value)) {
-        return delete_usermeta($user_id, $meta_key);
-    }
-
-    $cur = $wpdb->get_row( $wpdb->prepare("SELECT * FROM $wpdb->usermeta WHERE user_id = %d AND meta_key = %s", $user_id, $meta_key) );
-
-    if ( $cur )
-        do_action( 'update_usermeta', $cur->umeta_id, $user_id, $meta_key, $meta_value );
-
-    if ( !$cur )
-        $wpdb->insert($wpdb->usermeta, compact('user_id', 'meta_key', 'meta_value') );
-    else if ( $cur->meta_value != $meta_value )
-        $wpdb->update($wpdb->usermeta, compact('meta_value'), compact('user_id', 'meta_key') );
-    else
-        return false;
-
-    wp_cache_delete($user_id, 'users');
-
-    if ( !$cur )
-        do_action( 'added_usermeta', $wpdb->insert_id, $user_id, $meta_key, $meta_value );
-    else
-        do_action( 'updated_usermeta', $cur->umeta_id, $user_id, $meta_key, $meta_value );
-
-    return true;
+/**
+ * Add meta data field to a user.
+ *
+ * Post meta data is called "Custom Fields" on the Administration Panels.
+ *
+ * @since 3.0.0
+ * @uses add_metadata()
+ * @link http://codex.wordpress.org/Function_Reference/add_user_meta
+ *
+ * @param int $user_id Post ID.
+ * @param string $key Metadata name.
+ * @param mixed $value Metadata value.
+ * @param bool $unique Optional, default is false. Whether the same key should not be added.
+ * @return bool False for failure. True for success.
+ */
+function add_user_meta($user_id, $meta_key, $meta_value, $unique = false) {
+    return add_metadata('user', $user_id, $meta_key, $meta_value, $unique);
+}
+
+/**
+ * Remove metadata matching criteria from a user.
+ *
+ * You can match based on the key, or key and value. Removing based on key and
+ * value, will keep from removing duplicate metadata with the same key. It also
+ * allows removing all metadata matching key, if needed.
+ *
+ * @since 3.0.0
+ * @uses delete_metadata()
+ * @link http://codex.wordpress.org/Function_Reference/delete_user_meta
+ *
+ * @param int $user_id user ID
+ * @param string $meta_key Metadata name.
+ * @param mixed $meta_value Optional. Metadata value.
+ * @return bool False for failure. True for success.
+ */
+function delete_user_meta($user_id, $meta_key, $meta_value = '') {
+    return delete_metadata('user', $user_id, $meta_key, $meta_value);
+}
+
+/**
+ * Retrieve user meta field for a user.
+ *
+ * @since 3.0.0
+ * @uses get_metadata()
+ * @link http://codex.wordpress.org/Function_Reference/get_user_meta
+ *
+ * @param int $user_id Post ID.
+ * @param string $key The meta key to retrieve.
+ * @param bool $single Whether to return a single value.
+ * @return mixed Will be an array if $single is false. Will be value of meta data field if $single
+ *  is true.
+ */
+function get_user_meta($user_id, $key, $single = false) {
+    return get_metadata('user', $user_id, $key, $single);
+}
+
+/**
+ * Update user meta field based on user ID.
+ *
+ * Use the $prev_value parameter to differentiate between meta fields with the
+ * same key and user ID.
+ *
+ * If the meta field for the user does not exist, it will be added.
+ *
+ * @since 3.0
+ * @uses update_metadata
+ * @link http://codex.wordpress.org/Function_Reference/update_user_meta
+ *
+ * @param int $user_id Post ID.
+ * @param string $key Metadata key.
+ * @param mixed $value Metadata value.
+ * @param mixed $prev_value Optional. Previous value to check before removing.
+ * @return bool False on failure, true if success.
+ */
+function update_user_meta($user_id, $meta_key, $meta_value, $prev_value = '') {
+    return update_metadata('user', $user_id, $meta_key, $meta_value, $prev_value);
 }