探究 WordPress `wp_update_term()` 函数的源码：如何更新分类术语，并处理其别名和计数。

各位朋友，大家好！今天咱们来聊聊WordPress的 wp_update_term() 函数，这可是个更新分类术语的利器。别看它名字平淡，背后的逻辑可不少，尤其是别名（slug）和计数这两个家伙，经常让人头疼。今天咱们就一层层扒开它的源码，看看它是怎么运作的，顺便也解决一下大家可能遇到的疑惑。

咱们先来个热身，简单介绍一下wp_update_term()。

wp_update_term() 概览

wp_update_term() 函数的主要作用就是更新一个分类术语的信息。比如，你想修改某个分类的名称、别名、描述，或者更改它的父级分类，都可以用它。

/**
 * Updates an existing term in the database.
 *
 * @since 3.0.0
 *
 * @param int          $term_id     ID of the term to update.
 * @param string       $taxonomy    Taxonomy to which term belongs.
 * @param array|string $args        Optional. Array or string of arguments for updating a term.
 *                                    See wp_insert_term() for information on acceptable arguments.
 * @return WP_Error|array {
 *     @type int   $term_id       The term ID.
 *     @type int   $term_taxonomy_id The term taxonomy ID.
 * } WP_Error on failure.
 */
function wp_update_term( $term_id, $taxonomy, $args = array() ) {
    // 函数体
}

它接受三个参数：

• $term_id: 要更新的术语ID，这是必须的。
• $taxonomy: 术语所属的分类法（taxonomy），比如 category、post_tag 等，也是必须的。
• $args: 一个数组，包含了要更新的字段和对应的值。这个是可选的。

返回值：成功时返回一个数组，包含 term_id 和 term_taxonomy_id。失败时返回一个 WP_Error 对象。

源码剖析：wp_update_term() 的内部逻辑

好了，热身结束，咱们正式进入源码环节。为了方便理解，我把源码简化了一下，去掉了部分错误处理和钩子，保留了核心逻辑。

function wp_update_term( $term_id, $taxonomy, $args = array() ) {
    global $wpdb;

    $term_id = (int) $term_id;

    if ( ! term_exists( $term_id, $taxonomy ) ) {
        return new WP_Error( 'invalid_term', __( 'Nonexistent term.' ) );
    }

    $defaults = array(
        'name'        => '',
        'slug'        => '',
        'term_group'  => '',
        'description' => '',
        'parent'      => 0,
    );

    $args = wp_parse_args( $args, $defaults );

    $name        = sanitize_term_field( 'name', $args['name'], $term_id, $taxonomy, 'db' );
    $slug        = sanitize_term_field( 'slug', $args['slug'], $term_id, $taxonomy, 'db' );
    $term_group  = sanitize_term_field( 'term_group', $args['term_group'], $term_id, $taxonomy, 'db' );
    $description = sanitize_term_field( 'description', $args['description'], $term_id, $taxonomy, 'db' );
    $parent      = (int) $args['parent'];

    $original_slug = get_term_field( 'slug', $term_id, $taxonomy, 'raw' );

    // 如果没有提供别名，就根据名称生成一个
    if ( empty( $slug ) ) {
        $slug = sanitize_title( $name );
    }

    // 检查别名是否重复
    $slug = wp_unique_term_slug( $slug, $term_id, $taxonomy, null );

    $tt_id = _wp_get_term_taxonomy_id( $term_id, $taxonomy );

    // 更新 wp_terms 表
    $data  = compact( 'name', 'slug', 'term_group' );
    $where = array( 'term_id' => $term_id );
    $wpdb->update( $wpdb->terms, $data, $where );

    // 更新 wp_term_taxonomy 表
    $data  = compact( 'description', 'parent' );
    $where = array( 'term_taxonomy_id' => $tt_id );
    $wpdb->update( $wpdb->term_taxonomy, $data, $where );

    // 清除缓存
    clean_term_cache( $term_id, $taxonomy );

    return array( 'term_id' => $term_id, 'term_taxonomy_id' => $tt_id );
}

咱们一行行来看：

1. 参数验证和默认值:

   • 首先，函数会将 $term_id 强制转换为整数。
   • 然后，它会检查要更新的术语是否存在，如果不存在，就返回一个 WP_Error 对象。
   • 接下来，它定义了一个默认参数数组 $defaults，包含了 name、slug、term_group、description 和 parent 这几个字段。
   • wp_parse_args() 函数会将传入的 $args 数组与 $defaults 数组合并，如果 $args 中没有某个字段，就使用 $defaults 中的值。

2. 数据清理:

   • sanitize_term_field() 函数会对传入的各个字段进行清理，防止恶意代码注入。它会根据不同的字段类型，使用不同的清理函数。 例如，name和slug会被清理以移除HTML标签和不安全的字符。

   这里需要特别强调一下 sanitize_term_field() 函数，它非常重要。它会根据 $taxonomy 和 $field 的不同，调用不同的过滤函数，保证数据的安全性。

   参数	说明
   $field	要清理的字段名，比如 name、slug、description 等。
   $value	要清理的值。
   $term_id	术语 ID。
   $taxonomy	分类法名称。
   $context	上下文，通常是 'db'，表示要清理的值将要写入数据库。

3. 别名 (Slug) 处理：

   • 别名生成： 如果用户没有提供别名（$slug 为空），函数会使用 sanitize_title() 函数根据术语名称（$name）自动生成一个别名。 sanitize_title() 函数会将名称转换为小写，移除特殊字符，并将空格替换为连字符。

   • 别名唯一性检查： wp_unique_term_slug() 函数是整个流程中最关键的部分之一，它确保生成的别名在当前分类法下是唯一的。

   咱们再深入 wp_unique_term_slug() 函数内部看看：

   function wp_unique_term_slug( $slug, $term_id, $taxonomy, $parent ) {
       global $wpdb;
   
       $original_slug = $slug;
       $i = 2;
       while ( true ) {
           $query = $wpdb->prepare(
               "SELECT term_id FROM $wpdb->terms AS t
               INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id
               WHERE tt.taxonomy = %s AND t.slug = %s AND t.term_id != %d",
               $taxonomy,
               $slug,
               $term_id
           );
   
           if ( ! is_null( $parent ) ) {
               $query .= $wpdb->prepare( " AND tt.parent = %d", $parent );
           }
   
           $found_id = $wpdb->get_var( $query );
   
           if ( ! $found_id ) {
               break;
           }
   
           $slug = $original_slug . "-$i";
           $i++;
       }
   
       return $slug;
   }

   这个函数会循环检查 $slug 是否已经存在于数据库中。如果存在，就在 $slug 后面加上一个递增的数字，直到找到一个唯一的别名为止。这个函数保证了在同一分类法下，不会出现重复的别名。

4. 更新数据库：

   • _wp_get_term_taxonomy_id() 函数根据 $term_id 和 $taxonomy 获取对应的 term_taxonomy_id。
   • 然后，函数会使用 $wpdb->update() 函数分别更新 wp_terms 表和 wp_term_taxonomy 表。
     • wp_terms 表存储的是术语的基本信息，比如 name、slug 和 term_group。
     • wp_term_taxonomy 表存储的是术语与分类法的关系，以及术语的描述和父级分类。

5. 清除缓存：

   • clean_term_cache() 函数会清除与该术语相关的缓存，确保下次访问时能获取到最新的数据。

6. 返回结果：

   • 最后，函数返回一个数组，包含了 term_id 和 term_taxonomy_id。

别名 (Slug) 的重要性

别名在 WordPress 中扮演着非常重要的角色，它直接影响着你的网站的 SEO 和用户体验。

• SEO 优化： 一个好的别名应该简洁、易懂，并且包含关键词。这样可以帮助搜索引擎更好地理解你的内容，从而提高你的网站在搜索结果中的排名。
• 用户体验： 一个清晰的别名可以让用户更容易记住你的网址，并且更容易分享你的内容。

计数问题：wp_update_term() 不负责计数

这里要特别强调一点：wp_update_term() 函数不负责更新术语的计数。也就是说，如果你更新了某个分类的名称，这个分类下的文章数量不会自动更新。

那谁来负责更新计数呢？答案是 wp_update_term_count_now() 函数，以及 wp_update_term_count()函数。

wp_update_term_count_now()函数会立即更新计数，而 wp_update_term_count() 函数则会将更新任务放入队列，稍后执行。

使用示例

说了这么多，咱们来几个实际的例子，看看 wp_update_term() 函数怎么用。

// 更新分类的名称和描述
$args = array(
    'name'        => '新的分类名称',
    'description' => '这是新的分类描述',
);

$result = wp_update_term( 1, 'category', $args );

if ( is_wp_error( $result ) ) {
    echo '更新失败：' . $result->get_error_message();
} else {
    echo '更新成功！术语 ID：' . $result['term_id'] . '，术语分类 ID：' . $result['term_taxonomy_id'];
}

// 更新标签的别名
$args = array(
    'slug' => 'new-tag-slug',
);

$result = wp_update_term( 5, 'post_tag', $args );

if ( is_wp_error( $result ) ) {
    echo '更新失败：' . $result->get_error_message();
} else {
    echo '更新成功！术语 ID：' . $result['term_id'] . '，术语分类 ID：' . $result['term_taxonomy_id'];
}

// 更新父级分类
$args = array(
    'parent' => 3, // 将当前分类的父级分类设置为 ID 为 3 的分类
);

$result = wp_update_term( 2, 'category', $args );

if ( is_wp_error( $result ) ) {
    echo '更新失败：' . $result->get_error_message();
} else {
    echo '更新成功！术语 ID：' . $result['term_id'] . '，术语分类 ID：' . $result['term_taxonomy_id'];
}

注意事项

• 安全性： 在使用 wp_update_term() 函数时，一定要注意安全性，特别是当用户可以控制 $args 参数时。务必对用户输入进行严格的验证和清理，防止恶意代码注入。
• 缓存： 更新术语后，记得清除缓存，确保数据的一致性。
• 计数： 如果需要更新术语的计数，记得手动调用 wp_update_term_count() 函数。
• 钩子： WordPress 提供了丰富的钩子，可以在 wp_update_term() 函数执行前后进行自定义操作。比如，你可以在术语更新后发送邮件通知管理员。

总结

wp_update_term() 函数是 WordPress 中一个非常重要的函数，它可以用来更新分类术语的信息。理解它的内部逻辑，可以帮助你更好地使用它，并且避免一些常见的错误。希望今天的讲解能够帮助大家更好地理解 wp_update_term() 函数，在实际开发中能够更加得心应手。

记住，别名很重要，计数需要手动更新，安全第一！ 今天就到这里，祝大家编程愉快！