分析 WordPress `wp_insert_term()` 函数源码：分类术语的数据库操作与缓存清理。

各位观众，晚上好！我是今天的主讲人，很高兴和大家一起探索 WordPress 世界里一个相当核心，但又经常被忽略的角落：wp_insert_term() 函数。

今天，咱们不整虚的，直接撸起袖子，一起扒开 wp_insert_term() 的源码，看看它到底是怎么把分类术语（category term）塞到数据库里，又是怎么小心翼翼地清理缓存的。保证让你听完之后，下次再遇到分类术语的问题，心里门儿清！

第一部分：wp_insert_term() 的前世今生和基本用法

wp_insert_term()，顾名思义，是 WordPress 用来插入新分类术语的函数。它不仅仅是简单地往数据库里丢一条数据，还涉及到各种校验、过滤、以及至关重要的缓存管理。

基本用法长这样：

$result = wp_insert_term(
    '我的新分类', // 术语名称
    'category', // 分类法（taxonomy）名称，比如 'category', 'post_tag'
    array(
        'description' => '这是我的新分类的描述',
        'slug' => 'my-new-category', // 术语别名，用于 URL
        'parent' => 0 // 父级分类 ID，0 表示顶级分类
    )
);

if ( is_wp_error( $result ) ) {
    // 插入失败，处理错误
    echo '出错了：' . $result->get_error_message();
} else {
    // 插入成功
    echo '成功插入分类，ID 是：' . $result['term_id'];
    echo '分类法 ID 是：' . $result['term_taxonomy_id'];
}

wp_insert_term() 函数返回两种类型的值：

• WP_Error 对象： 如果插入过程中出现任何错误，比如术语名称为空、别名冲突等等，它会返回一个 WP_Error 对象，你可以通过 get_error_message() 方法获取错误信息。
• 数组： 如果插入成功，它会返回一个关联数组，包含两个键：
  • term_id：新插入的术语 ID。
  • term_taxonomy_id：术语和分类法的关联 ID (term_taxonomy table中的ID)。

第二部分：源码剖析：一步一步走进 wp_insert_term() 的内心世界

好了，铺垫结束，现在让我们深入到 wp-includes/taxonomy.php 文件里，一起解剖 wp_insert_term() 的源码（为了方便阅读，我对源码进行了一些简化和注释）：

function wp_insert_term( $term, $taxonomy, $args = array() ) {
    global $wpdb;

    // 1. 参数检查和准备

    // 确保术语名称和分类法名称不为空
    if ( empty( $term ) || empty( $taxonomy ) ) {
        return new WP_Error( 'missing_term_name', __( 'A term name must be supplied.' ) );
    }

    if ( ! taxonomy_exists( $taxonomy ) ) {
        return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
    }

    $defaults = array( 'description' => '', 'slug' => '', 'parent' => 0 );
    $args = wp_parse_args( $args, $defaults );

    $description = $args['description'];
    $slug        = $args['slug'];
    $parent      = absint( $args['parent'] );

    // 2. 术语名称和别名的过滤和处理

    // 对术语名称进行过滤，防止恶意代码注入
    $term = wp_unslash( strip_tags( $term ) );

    // 如果没有提供别名，则根据术语名称自动生成
    if ( empty( $slug ) ) {
        $slug = sanitize_title( $term );
    }

    $slug = wp_unique_term_slug( $slug, (object) array( 'taxonomy' => $taxonomy, 'term_id' => 0 ) );

    // 3. 父级分类的验证

    // 检查父级分类是否存在
    if ( $parent ) {
        if ( ! term_exists( (int) $parent, $taxonomy ) ) {
            return new WP_Error( 'invalid_term_parent', __( 'Parent term does not exist.' ) );
        }
    }

    // 4. 检查术语是否已经存在

    // 检查是否存在相同名称和分类法的术语
    $id = term_exists( $term, $taxonomy, $parent );
    if ( $id ) {
        if ( is_array( $id ) ) {
            $id = $id['term_id'];
        }
        return new WP_Error( 'term_exists', __( 'Term already exists.' ), $id );
    }

    // 5. 准备 SQL 查询

    $data = compact( 'name', 'slug' );
    $data = wp_unslash( $data ); // sanitize
    $formats = array( '%s', '%s' );

    // 6. 执行数据库插入操作

    $wpdb->insert( $wpdb->terms, $data, $formats );
    $term_id = (int) $wpdb->insert_id;

    if ( ! $term_id ) {
        return new WP_Error( 'db_insert_error', __( 'Could not insert term into the database.' ), $wpdb->last_error );
    }

    // 7. 插入 term_taxonomy 表

    $wpdb->insert(
        $wpdb->term_taxonomy,
        array(
            'term_id' => $term_id,
            'taxonomy' => $taxonomy,
            'description' => $description,
            'parent' => $parent,
            'count' => 0
        ),
        array( '%d', '%s', '%s', '%d', '%d' )
    );
    $term_taxonomy_id = (int) $wpdb->insert_id;

    if ( ! $term_taxonomy_id ) {
        return new WP_Error( 'db_insert_error', __( 'Could not insert term taxonomy into the database.' ), $wpdb->last_error );
    }

    // 8. 清理缓存

    clean_term_cache( $term_id, $taxonomy );

    // 9. 触发 actions

    do_action( 'create_term', $term_id, $term_taxonomy_id, $taxonomy, $args );

    // 10. 返回结果
    return array( 'term_id' => $term_id, 'term_taxonomy_id' => $term_taxonomy_id );
}

代码流程分解：

1. 参数检查和准备：

   • 首先，函数会检查传入的术语名称 $term 和分类法名称 $taxonomy 是否为空。如果为空，直接返回一个 WP_Error 对象，提示缺少必要的参数。
   • 然后，它会验证指定的分类法 $taxonomy 是否存在。如果不存在，同样返回 WP_Error 对象，提示分类法无效。
   • 接着，使用 wp_parse_args() 函数将传入的 $args 数组与默认值进行合并，确保 $description、$slug 和 $parent 都有值。

2. 术语名称和别名的过滤和处理：

   • 使用 wp_unslash() 和 strip_tags() 函数对术语名称 $term 进行过滤，移除反斜杠和 HTML 标签，防止恶意代码注入。
   • 如果用户没有提供别名 $slug，函数会使用 sanitize_title() 函数根据术语名称自动生成一个别名。sanitize_title() 会将术语名称转换为小写，并将空格和特殊字符替换为短横线。
   • 使用 wp_unique_term_slug() 函数确保生成的别名在当前分类法下是唯一的。如果别名已经存在，wp_unique_term_slug() 会在别名后面添加一个数字，直到找到一个唯一的别名。

3. 父级分类的验证：

   • 如果指定了父级分类 $parent，函数会使用 term_exists() 函数检查父级分类是否存在。如果父级分类不存在，返回 WP_Error 对象，提示父级分类无效。

4. 检查术语是否已经存在：

   • 使用 term_exists() 函数检查是否存在相同名称和分类法的术语。如果存在，返回 WP_Error 对象，提示术语已经存在。

5. 准备 SQL 查询：

   • 使用 compact() 函数创建一个包含术语名称 $name 和别名 $slug 的关联数组 $data。
   • 使用 wp_unslash() 函数对 $data 数组进行过滤。
   • 定义 $formats 数组，指定 SQL 查询中占位符的类型。

6. 执行数据库插入操作：

   • 使用 $wpdb->insert() 函数将术语名称和别名插入到 wp_terms 表中。
   • 获取新插入的术语 ID $term_id。
   • 如果插入失败，返回 WP_Error 对象，提示数据库插入错误。

7. 插入 term_taxonomy 表：

   • 使用 $wpdb->insert() 函数将术语 ID、分类法名称、描述、父级分类和计数器插入到 wp_term_taxonomy 表中。
   • 获取新插入的 term taxonomy ID $term_taxonomy_id。
   • 如果插入失败，返回 WP_Error 对象，提示数据库插入错误。

8. 清理缓存：

   • 使用 clean_term_cache() 函数清理与新插入的术语相关的缓存。这是非常重要的一步，可以确保在插入术语后，网站能够立即显示最新的分类信息。

9. 触发 actions：

   • 使用 do_action() 函数触发 create_term action。插件和主题可以使用这个 action 来执行一些自定义的操作，比如发送通知、更新其他数据等等。

10. 返回结果：

    • 返回一个包含新插入的术语 ID $term_id 和 term taxonomy ID $term_taxonomy_id 的关联数组。

第三部分：缓存清理：clean_term_cache() 的秘密

clean_term_cache() 函数在 wp_insert_term() 中扮演着至关重要的角色。它负责清理与新插入的术语相关的缓存，确保网站能够立即显示最新的分类信息。让我们深入了解一下 clean_term_cache() 函数的源码：

function clean_term_cache( $ids, $taxonomy = '' ) {
    if ( ! is_array( $ids ) ) {
        $ids = array( $ids );
    }

    $taxonomies = array();
    if ( $taxonomy ) {
        $taxonomies[] = $taxonomy;
    } else {
        foreach ( $ids as $id ) {
            $term = get_term( $id );
            if ( $term && ! is_wp_error( $term ) ) {
                if ( ! in_array( $term->taxonomy, $taxonomies, true ) ) {
                    $taxonomies[] = $term->taxonomy;
                }
            }
        }
    }

    foreach ( $taxonomies as $taxonomy ) {
        wp_cache_delete( "get_terms:$taxonomy", 'terms' );
        wp_cache_delete( "get_terms_orderby:$taxonomy", 'terms' );
    }

    foreach ( $ids as $id ) {
        wp_cache_delete( "term_$id", 'terms' );
        wp_cache_delete( "term_taxonomy_id_$id", 'terms' );
        wp_cache_delete( "get_term_$id", 'terms' );
    }

    do_action( 'clean_term_cache', $ids, $taxonomy );
}

代码流程分解：

1. 参数处理：

   • 函数接收两个参数：

     • $ids：要清理缓存的术语 ID，可以是一个单独的 ID，也可以是一个 ID 数组。
     • $taxonomy：分类法名称，可选参数。如果提供了分类法名称，函数只会清理与该分类法相关的缓存。

   • 如果 $ids 不是一个数组，函数会将其转换为一个包含单个 ID 的数组。

2. 确定分类法：

   • 如果提供了 $taxonomy 参数，函数会将分类法名称添加到 $taxonomies 数组中。
   • 如果没有提供 $taxonomy 参数，函数会遍历 $ids 数组，获取每个术语的分类法名称，并将分类法名称添加到 $taxonomies 数组中。

3. 清理全局缓存：

   • 遍历 $taxonomies 数组，清理与每个分类法相关的全局缓存：
     • wp_cache_delete( "get_terms:$taxonomy", 'terms' )：清理 get_terms() 函数的缓存。get_terms() 函数用于获取指定分类法下的所有术语。
     • wp_cache_delete( "get_terms_orderby:$taxonomy", 'terms' )：清理 get_terms() 函数排序结果的缓存。

4. 清理单个术语缓存：

   • 遍历 $ids 数组，清理与每个术语相关的缓存：
     • wp_cache_delete( "term_$id", 'terms' )：清理术语对象的缓存。
     • wp_cache_delete( "term_taxonomy_id_$id", 'terms' )：清理 term taxonomy ID 的缓存。
     • wp_cache_delete( "get_term_$id", 'terms' )：清理 get_term() 函数的缓存。get_term() 函数用于获取指定 ID 的术语对象。

5. 触发 action：

   • 使用 do_action() 函数触发 clean_term_cache action。插件和主题可以使用这个 action 来执行一些自定义的缓存清理操作。

缓存清理的重要性：

如果没有及时清理缓存，网站可能会显示过时的分类信息。例如，在插入一个新的分类后，网站可能仍然无法显示该分类，直到缓存过期。因此，clean_term_cache() 函数在 wp_insert_term() 函数中扮演着至关重要的角色，可以确保网站能够立即显示最新的分类信息。

第四部分：一些注意事项和最佳实践

• 别名（Slug）的唯一性： 确保你的别名在当前分类法下是唯一的。如果别名已经存在，wp_insert_term() 会自动添加一个数字后缀，但这可能会导致 URL 不美观。建议在插入术语之前，先检查别名是否可用。

• 父级分类（Parent）的正确性： 如果你指定了父级分类，一定要确保父级分类存在。否则，wp_insert_term() 会返回一个错误。

• 错误处理： wp_insert_term() 可能会返回 WP_Error 对象。在实际开发中，一定要检查返回值，并根据错误信息进行相应的处理。

• 缓存管理： 虽然 wp_insert_term() 会自动清理缓存，但在某些特殊情况下，你可能需要手动清理缓存。例如，如果你使用了自定义的缓存插件，或者你对分类术语进行了批量修改。

• Action 的利用： create_term 和 clean_term_cache 这两个 Action 是非常有用的扩展点。你可以使用它们来实现一些自定义的功能，比如发送通知、更新其他数据、或者清理自定义的缓存。

第五部分：实战案例：自定义分类的批量导入

假设你需要从一个 CSV 文件中批量导入自定义分类（比如 "product_category"）的术语。下面是一个简单的示例代码：

<?php
// 假设 CSV 文件包含两列：术语名称和描述
$csv_file = 'product_categories.csv';

if ( ( $handle = fopen( $csv_file, "r" ) ) !== FALSE ) {
    while ( ( $data = fgetcsv( $handle, 1000, "," ) ) !== FALSE ) {
        $term_name = sanitize_text_field( $data[0] );
        $term_description = sanitize_text_field( $data[1] );

        // 插入术语
        $result = wp_insert_term(
            $term_name,
            'product_category',
            array(
                'description' => $term_description,
            )
        );

        if ( is_wp_error( $result ) ) {
            // 插入失败，记录错误信息
            error_log( '插入分类 ' . $term_name . ' 失败：' . $result->get_error_message() );
        } else {
            // 插入成功，输出提示信息
            echo '成功插入分类：' . $term_name . '<br>';
        }
    }
    fclose( $handle );
} else {
    echo '无法打开 CSV 文件！';
}
?>

代码解释：

1. 打开 CSV 文件： 使用 fopen() 函数打开 CSV 文件。
2. 逐行读取数据： 使用 fgetcsv() 函数逐行读取 CSV 文件中的数据。
3. 清理数据： 使用 sanitize_text_field() 函数清理术语名称和描述，防止恶意代码注入。
4. 插入术语： 使用 wp_insert_term() 函数插入术语。
5. 错误处理： 检查 wp_insert_term() 函数的返回值，如果插入失败，记录错误信息；如果插入成功，输出提示信息。
6. 关闭 CSV 文件： 使用 fclose() 函数关闭 CSV 文件。

表格总结：wp_insert_term() 的核心要素

要素	描述	重要性
参数检查	确保术语名称、分类法名称不为空，分类法存在。	高
过滤与清理	对术语名称和别名进行过滤，防止恶意代码。	高
别名生成	如果没有提供别名，自动生成一个唯一的别名。	中
父级分类验证	检查父级分类是否存在。	中
数据库操作	将术语信息插入 wp_terms 和 wp_term_taxonomy 表中。	高
缓存清理	使用 clean_term_cache() 清理与新插入的术语相关的缓存。	高
Action 触发	触发 create_term action，允许插件和主题执行自定义操作。	中
错误处理	检查 wp_insert_term() 的返回值，并根据错误信息进行相应的处理。	高

总结：

wp_insert_term() 是 WordPress 中一个非常重要的函数，它负责将分类术语插入到数据库中，并清理相关的缓存。理解 wp_insert_term() 的源码，可以帮助你更好地理解 WordPress 的分类系统，并能够更灵活地处理分类术语相关的问题。希望今天的分享能帮助大家更深入地了解 WordPress。下次有机会，我们再一起探索 WordPress 的其他奥秘！谢谢大家！