解析 WordPress `wp_update_user()` 函数的源码：如何更新用户数据并触发相关钩子。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位听众，早上好！今天咱不搞那些虚头巴脑的开场白，直接进入正题：扒一扒 WordPress 里 wp_update_user() 这个函数的老底，看看它到底是怎么更新用户数据，又是怎么牵动那些钩子的。

一、初识 wp_update_user()：它的用途和基本结构

首先，wp_update_user()，顾名思义，就是用来更新用户信息的。它接收一个数组或者一个对象作为参数，里面包含了你想更新的用户信息，比如邮箱、昵称、密码等等。

基本结构如下：

/**
 * Updates an existing user row in the database.
 *
 * @since 2.0.0
 *
 * @param array|object $data {
 *     Array or object of arguments for updating user data.
 *
 *     @type int    $ID                    User ID. Required.
 *     @type string $user_login            User login name.
 *     @type string $user_pass             User password.
 *     @type string $user_nicename         User nicename.
 *     @type string $user_email            User email address.
 *     @type string $user_url              User URL.
 *     @type string $display_name          User display name.
 *     @type string $nickname              User nickname.
 *     @type string $first_name            User first name.
 *     @type string $last_name             User last name.
 *     @type string $description           User description.
 *     @type string $rich_editing          Whether to enable the rich editor. Accepts 'true', 'false'.
 *     @type string $syntax_highlighting Whether to enable syntax highlighting. Accepts 'true', 'false'.
 *     @type int    $comment_shortcuts     Whether to enable comment shortcuts. Accepts 'true' or 'false'.
 *     @type string $admin_color           Admin color scheme.
 *     @type int    $use_ssl               Whether to force SSL. Accepts 'true' or 'false'.
 *     @type string $show_admin_bar_front  Whether to show the admin bar on the front end. Accepts 'true', 'false'.
 *     @type string $user_registered       User registration date.
 *     @type string $user_activation_key   User activation key.
 *     @type string $spam                  Whether the user is marked as spam. Accepts 'true', 'false'.
 *     @type string $deleted               Whether the user is marked as deleted. Accepts 'true', 'false'.
 *     @type string $locale                User locale.
 * }
 * @return int|WP_Error WP_Error on failure, user ID on success.
 */
function wp_update_user( $data ) {
  // ... 函数主体 ...
}

看到了吧？它接收一个 $data 参数，这个参数可以是数组或者对象，里面包含了要更新的用户字段。必须包含 ID 字段，否则就不知道你要更新哪个用户了！

二、代码剖析：wp_update_user() 的内部运作

接下来，咱们深入 wp_update_user() 的源码，看看它是如何一步步完成用户更新的。

参数校验与清理

首先，函数会检查传入的 $data 参数是否合法，并进行一些清理工作。

if ( ! is_array( $data ) && ! is_object( $data ) ) {
   return new WP_Error( 'invalid_data', __( 'Invalid user data.' ) );
}

$data = (array) $data;

if ( ! isset( $data['ID'] ) ) {
   return new WP_Error( 'no_user_id', __( 'You must include a user ID.' ) );
}

$id = (int) $data['ID'];

if ( ! get_userdata( $id ) ) {
   return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) );
}

$user = get_userdata( $id );

这里，它首先判断 $data 是不是数组或者对象。然后，强制转换为数组。接着，检查是否存在 ID 字段，以及这个 ID 对应的用户是否存在。如果任何一个条件不满足，就返回一个 WP_Error 对象。

数据准备：过滤与转换

接下来，函数会根据 $data 中的字段，准备要更新的数据。这里会涉及到一些过滤和转换。

$wpdb = $GLOBALS['wpdb']; // 使用全局数据库对象

$user_data = array();
$meta = array();

$update_password = false;

if ( isset( $data['user_pass'] ) ) {
   $update_password = true;
}

$update_email = false;

if ( isset( $data['user_email'] ) && $data['user_email'] !== $user->user_email ) {
   $update_email = true;
}

$allowed_user_fields = array(
   'user_login',
   'user_pass',
   'user_nicename',
   'user_email',
   'user_url',
   'display_name',
   'user_registered',
   'user_activation_key',
   'spam',
   'deleted',
   'locale',
);

foreach ( $allowed_user_fields as $field ) {
   if ( isset( $data[ $field ] ) ) {
       $user_data[ $field ] = $data[ $field ];
   }
}

$allowed_meta_fields = array(
   'nickname',
   'first_name',
   'last_name',
   'description',
   'rich_editing',
   'syntax_highlighting',
   'comment_shortcuts',
   'admin_color',
   'use_ssl',
   'show_admin_bar_front',
);

foreach ( $allowed_meta_fields as $field ) {
   if ( isset( $data[ $field ] ) ) {
       $meta[ $field ] = $data[ $field ];
   }
}

这段代码首先定义了两个数组：$allowed_user_fields 和 $allowed_meta_fields，分别包含了允许更新的用户表字段和用户元数据字段。然后，它遍历 $data 数组，将允许更新的字段分别放入 $user_data 和 $meta 数组中。注意，这里还检查了是否需要更新密码和邮箱。

安全检查与钩子

在真正更新数据之前，WordPress 会进行一些安全检查，并触发一些钩子，允许开发者在更新前后进行一些自定义操作。

// Filter the user data before update.
$user_data = apply_filters( 'pre_user_update', $user_data, $id );

if ( $update_email ) {
   $email = sanitize_email( $user_data['user_email'] );

   if ( empty( $email ) || ! is_email( $email ) ) {
       return new WP_Error( 'invalid_email', __( 'The email address isn’t correct.' ) );
   }

   if ( email_exists( $email ) && email_exists( $email ) != $id ) {
       return new WP_Error( 'email_exists', __( 'This email is already registered, please choose another one.' ) );
   }

   $user_data['user_email'] = $email;
}

if ( ! empty( $user_data['user_login'] ) ) {
   $user_data['user_login'] = sanitize_user( $user_data['user_login'], true );
}

// Generate a new activation key if the user is being unspammed.
if ( isset( $user_data['spam'] ) && '0' == $user_data['spam'] && '1' == $user->spam ) {
   $user_data['user_activation_key'] = wp_generate_password( 20, false );
}

这里，首先触发了 pre_user_update 钩子，允许开发者在更新之前修改 $user_data 数组。然后，对邮箱和用户名进行了安全检查和清理。如果更新了邮箱，还会检查邮箱是否已经存在。如果用户从 spam 状态被移除，还会生成一个新的激活密钥。

密码处理

如果需要更新密码，这里会进行密码哈希处理。
```
if ( $update_password ) {
   $user_data['user_pass'] = wp_hash_password( $user_data['user_pass'] );
}
```
wp_hash_password() 函数会对密码进行哈希处理，保证密码的安全性。

数据更新

终于到了真正更新数据的环节了！

if ( ! empty( $user_data ) ) {
   $where = array( 'ID' => $id );
   $updated = $wpdb->update( $wpdb->users, $user_data, $where );

   if ( false === $updated ) {
       return new WP_Error( 'db_update_error', __( 'Could not update user in database.' ), $wpdb->last_error );
   }
}

这里，使用 $wpdb->update() 函数更新 wp_users 表。$user_data 包含了要更新的字段和值，$where 指定了更新的条件，即 ID 等于 $id 的用户。如果更新失败，返回一个 WP_Error 对象。

元数据更新

接下来，更新用户元数据。
```
if ( ! empty( $meta ) ) {
   foreach ( $meta as $field => $value ) {
       update_user_meta( $id, $field, $value );
   }
}
```
这里，遍历 $meta 数组，使用 update_user_meta() 函数更新每个元数据字段。
清理缓存与触发钩子

最后，清理缓存，并触发一些钩子，通知其他模块用户数据已经更新。
```
wp_cache_delete( $id, 'users' );
wp_cache_delete( 'user_email_' . $user->user_email, 'useremail' );
wp_cache_delete( 'user_login_' . $user->user_login, 'userlogins' );

clean_user_cache( $id );

do_action( 'profile_update', $id, $user->data );

return $id;
```
这里，清理了用户缓存、邮箱缓存和用户名缓存。然后，调用 clean_user_cache() 函数清理更全面的用户缓存。最后，触发了 profile_update 钩子，传递了用户 ID 和原始的用户数据。

三、钩子概览：wp_update_user() 相关的钩子

在 wp_update_user() 函数的执行过程中，涉及到了多个钩子，这些钩子允许开发者在不同的阶段介入用户更新流程。

钩子名称	触发时机	参数	用途
`pre_user_update`	在用户数据更新之前，对 `$user_data` 进行过滤	`$user_data` (array), `$id` (int)	修改即将要更新的用户数据，比如增加一些额外的字段，或者修改某些字段的值。
`profile_update`	在用户数据更新之后	`$user_id` (int), `$old_user_data` (object)	在用户数据更新后执行一些操作，比如发送邮件通知、更新其他相关数据等等。 `$old_user_data` 包含了更新之前的用户数据。

这些钩子是 WordPress 强大的可扩展性的体现，允许开发者根据自己的需求定制用户更新流程。

四、实战演练：使用 wp_update_user() 更新用户数据

光说不练假把式，咱们来写个简单的例子，演示一下如何使用 wp_update_user() 更新用户数据。

<?php
// 获取用户 ID
$user_id = 1; // 假设我们要更新 ID 为 1 的用户

// 准备要更新的数据
$user_data = array(
    'ID'           => $user_id,
    'user_email'   => '[email protected]',
    'first_name'   => '张',
    'last_name'    => '三',
    'description'  => '这是一个新的自我介绍'
);

// 更新用户数据
$result = wp_update_user( $user_data );

// 处理更新结果
if ( is_wp_error( $result ) ) {
    // 更新失败
    echo '更新失败：' . $result->get_error_message();
} else {
    // 更新成功
    echo '更新成功！用户 ID：' . $result;
}
?>

这段代码首先定义了要更新的用户 ID 和要更新的数据。然后，调用 wp_update_user() 函数更新用户数据。最后，根据返回结果判断更新是否成功，并输出相应的提示信息。

五、注意事项：使用 wp_update_user() 的一些坑

在使用 wp_update_user() 函数时，有一些坑需要注意：

必须包含 ID 字段： 否则函数会报错。
数据类型要匹配： 比如，user_id 必须是整数，user_email 必须是有效的邮箱地址。
注意安全： 在更新用户数据之前，一定要进行安全检查，防止恶意攻击。
合理使用钩子： 可以使用钩子在更新前后执行一些自定义操作，但要注意不要过度使用，以免影响性能。

六、总结：wp_update_user() 的价值

wp_update_user() 函数是 WordPress 中一个非常重要的函数，它提供了更新用户数据的便捷方式。通过深入理解它的源码，我们可以更好地掌握 WordPress 的用户管理机制，并根据自己的需求定制用户更新流程。同时，也要注意使用过程中的一些坑，避免出现问题。

好了，今天的讲座就到这里，希望对大家有所帮助！如果有什么疑问，欢迎提问。感谢各位的聆听！

发表回复 取消回复

发表回复取消回复