<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" /><style type="text/css"><!--
#msg dl { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fc0 solid; padding: 6px; }
#msg ul, pre { overflow: auto; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<title>[13300] trunk/wp-includes: Introduce *_user_meta() functions,
deprecate *_usermeta() family.</title>
</head>
<body>
<div id="msg">
<dl>
<dt>Revision</dt> <dd><a href="http://trac.wordpress.org/changeset/13300">13300</a></dd>
<dt>Author</dt> <dd>nacin</dd>
<dt>Date</dt> <dd>2010-02-22 18:35:35 +0000 (Mon, 22 Feb 2010)</dd>
</dl>
<h3>Log Message</h3>
<pre>Introduce *_user_meta() functions, deprecate *_usermeta() family. Fixes <a href="http://trac.wordpress.org/ticket/10837">#10837</a> props scribu, technosailor.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunkwpincludesdeprecatedphp">trunk/wp-includes/deprecated.php</a></li>
<li><a href="#trunkwpincludesuserphp">trunk/wp-includes/user.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunkwpincludesdeprecatedphp"></a>
<div class="modfile"><h4>Modified: trunk/wp-includes/deprecated.php (13299 => 13300)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/wp-includes/deprecated.php 2010-02-22 18:25:51 UTC (rev 13299)
+++ trunk/wp-includes/deprecated.php 2010-02-22 18:35:35 UTC (rev 13300)
</span><span class="lines">@@ -2266,4 +2266,66 @@
</span><span class="cx"> return wp_unregister_widget_control($id);
</span><span class="cx"> }
</span><span class="cx">
</span><del>-?>
</del><span class="cx">\ No newline at end of file
</span><ins>+/**
+ * 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 );
+}
</ins><span class="cx">\ No newline at end of file
</span></span></pre></div>
<a id="trunkwpincludesuserphp"></a>
<div class="modfile"><h4>Modified: trunk/wp-includes/user.php (13299 => 13300)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/wp-includes/user.php 2010-02-22 18:25:51 UTC (rev 13299)
+++ trunk/wp-includes/user.php 2010-02-22 18:35:35 UTC (rev 13300)
</span><span class="lines">@@ -292,150 +292,82 @@
</span><span class="cx"> return $users;
</span><span class="cx"> }
</span><span class="cx">
</span><del>-//
-// User meta functions
-//
-
</del><span class="cx"> /**
</span><del>- * Remove user meta data.
</del><ins>+ * Add meta data field to a user.
</ins><span class="cx"> *
</span><del>- * @since 2.0.0
- * @uses $wpdb WordPress database object for queries.
</del><ins>+ * Post meta data is called "Custom Fields" on the Administration Panels.
</ins><span class="cx"> *
</span><del>- * @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.
</del><ins>+ * @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.
</ins><span class="cx"> */
</span><del>-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;
</del><ins>+function add_user_meta($user_id, $meta_key, $meta_value, $unique = false) {
+ return add_metadata('user', $user_id, $meta_key, $meta_value, $unique);
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Retrieve user metadata.
</del><ins>+ * Remove metadata matching criteria from a user.
</ins><span class="cx"> *
</span><del>- * 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.
</del><ins>+ * 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.
</ins><span class="cx"> *
</span><del>- * @since 2.0.0
- * @uses $wpdb WordPress database object for queries.
</del><ins>+ * @since 3.0.0
+ * @uses delete_metadata()
+ * @link http://codex.wordpress.org/Function_Reference/delete_user_meta
</ins><span class="cx"> *
</span><del>- * @param int $user_id User ID
- * @param string $meta_key Optional. Metadata key.
- * @return mixed
</del><ins>+ * @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.
</ins><span class="cx"> */
</span><del>-function get_usermeta( $user_id, $meta_key = '') {
- global $wpdb;
- $user_id = (int) $user_id;
</del><ins>+function delete_user_meta($user_id, $meta_key, $meta_value = '') {
+ return delete_metadata('user', $user_id, $meta_key, $meta_value);
+}
</ins><span class="cx">
</span><del>- 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;
</del><ins>+/**
+ * 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);
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Update metadata of user.
</del><ins>+ * Update user meta field based on user ID.
</ins><span class="cx"> *
</span><del>- * 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.
</del><ins>+ * Use the $prev_value parameter to differentiate between meta fields with the
+ * same key and user ID.
</ins><span class="cx"> *
</span><del>- * Will remove the metadata, if the meta value is empty.
</del><ins>+ * If the meta field for the user does not exist, it will be added.
</ins><span class="cx"> *
</span><del>- * @since 2.0.0
- * @uses $wpdb WordPress database object for queries
</del><ins>+ * @since 3.0
+ * @uses update_metadata
+ * @link http://codex.wordpress.org/Function_Reference/update_user_meta
</ins><span class="cx"> *
</span><del>- * @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.
</del><ins>+ * @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.
</ins><span class="cx"> */
</span><del>-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;
</del><ins>+function update_user_meta($user_id, $meta_key, $meta_value, $prev_value = '') {
+ return update_metadata('user', $user_id, $meta_key, $meta_value, $prev_value);
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> //
</span></span></pre>
</div>
</div>
</body>
</html>