探究 WordPress `wp_insert_term()` 函数的源码：如何处理分类术语的插入和层级关系。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位程序猿、程序媛、以及未来可能成为程序猿的同学们，晚上好！我是今晚的特邀讲师，老码农一枚。今天咱们不开车，来聊聊WordPress底层的一个重要函数——wp_insert_term()。

这玩意儿，说白了，就是负责往数据库里塞分类术语的。别一听“分类术语”就觉得高大上，其实就是咱们网站上那些分类、标签之类的东西。它不仅能帮你创建新的分类，还能管理它们之间的层级关系，让你的网站井井有条。

咱们今天就来扒一扒 wp_insert_term() 的源码，看看它到底是怎么运作的，以及在使用过程中需要注意哪些坑。

一、wp_insert_term() 的基本用法

首先，咱们先简单回顾一下 wp_insert_term() 的基本用法，免得有同学掉队：

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

if ( is_wp_error( $result ) ) {
    echo '出错了：' . $result->get_error_message();
} else {
    echo '成功创建分类，ID 是：' . $result['term_id'];
}

这段代码的作用就是创建一个名为“我的新分类”的分类，并设置了描述、别名和父级分类。如果创建成功， $result 会返回一个包含 term_id 和 term_taxonomy_id 的数组；如果创建失败， $result 会返回一个 WP_Error 对象。

二、源码剖析：wp_insert_term() 的内部逻辑

好了，铺垫完毕，现在咱们正式进入源码环节。wp_insert_term() 的源码位于 wp-includes/taxonomy.php 文件中，代码比较长，咱们挑重点的部分来分析。

参数校验和数据准备

函数一开始，会进行一系列的参数校验和数据准备工作，确保传入的参数是有效的。

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

    // 1. 检查是否已安装数据库
    if ( ! is_object( $wpdb ) || empty( $wpdb->dbh ) ) {
        return new WP_Error( 'db_not_ready', __( 'Database not ready.' ) );
    }

    // 2. 检查术语名称是否为空
    if ( empty( $term ) ) {
        return new WP_Error( 'empty_term_name', __( 'Empty term name.' ) );
    }

    // 3. 检查分类法是否存在
    if ( ! taxonomy_exists( $taxonomy ) ) {
        return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
    }

    // 4. 初始化参数
    $defaults = array(
        'description' => '',
        'slug'        => '',
        'parent'      => 0,
    );
    $args = wp_parse_args( $args, $defaults );

    // 5. 数据清理
    $term = trim( strip_tags( $term ) );
    $description = trim( strip_tags( $args['description'] ) );
    $slug = sanitize_title( $args['slug'] );
    $parent = (int) $args['parent'];

    // ... 后续代码
}

可以看到，这里主要做了以下几件事情：

检查数据库是否已连接。
检查术语名称是否为空。
检查分类法是否存在。
使用 wp_parse_args() 合并默认参数和用户传入的参数。
对术语名称、描述和别名进行清理，防止 XSS 攻击。

别名 (Slug) 的处理

别名 (Slug) 是 URL 中使用的术语名称，必须是唯一的。wp_insert_term() 会检查是否存在重复的别名，如果存在，会自动生成一个新的别名。

    // ... 上面的代码

    // 6. 检查别名是否为空
    if ( empty( $slug ) ) {
        $slug = sanitize_title( $term );
    }

    // 7. 检查别名是否已存在
    $original_slug = $slug;
    $i = 1;
    while ( $wpdb->get_var( $wpdb->prepare( "SELECT term_id FROM $wpdb->terms WHERE slug = %s", $slug ) ) ) {
        $slug = $original_slug . '-' . $i;
        $i++;
    }

    // ... 后续代码

这段代码逻辑很简单：

如果用户没有指定别名，则使用术语名称生成一个别名。
使用循环检查别名是否已存在，如果已存在，则在别名后面加上递增的数字，直到找到一个唯一的别名。

父级分类的处理

如果用户指定了父级分类，wp_insert_term() 会检查父级分类是否存在，并且确保父级分类和当前分类属于同一个分类法。

    // ... 上面的代码

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

    // ... 后续代码

插入数据到数据库

经过一系列的校验和处理之后，wp_insert_term() 终于要将数据插入到数据库了。它会将数据插入到 wp_terms 和 wp_term_taxonomy 这两个表中。

    // ... 上面的代码

    // 9. 插入数据到 wp_terms 表
    $data = compact( 'name', 'slug' );
    $wpdb->insert( $wpdb->terms, $data );
    $term_id = (int) $wpdb->insert_id;

    // 10. 插入数据到 wp_term_taxonomy 表
    $data = array(
        'term_id'     => $term_id,
        'taxonomy'    => $taxonomy,
        'description' => $description,
        'parent'      => $parent,
    );
    $wpdb->insert( $wpdb->term_taxonomy, $data );
    $term_taxonomy_id = (int) $wpdb->insert_id;

    // ... 后续代码

这里使用了 $wpdb->insert() 方法将数据插入到数据库中。wp_terms 表存储术语的名称和别名，wp_term_taxonomy 表存储术语的描述、父级分类和分类法。

更新术语计数

插入数据之后，wp_insert_term() 会更新术语的计数，也就是统计每个术语下有多少篇文章。

    // ... 上面的代码

    // 11. 更新术语计数
    wp_update_term_count( $term_id, $taxonomy );

    // ... 后续代码

wp_update_term_count() 函数会查询 wp_term_relationships 表，统计与该术语相关的文章数量，并将结果更新到 wp_term_taxonomy 表的 count 字段中。

缓存清理

最后，wp_insert_term() 会清理相关的缓存，确保数据是最新的。

    // ... 上面的代码

    // 12. 清理缓存
    clean_term_cache( $term_id, $taxonomy );

    // ... 后续代码

clean_term_cache() 函数会清理术语的缓存、分类法的缓存和文章的缓存，防止出现数据不一致的情况。

返回结果

最终，wp_insert_term() 会返回一个包含 term_id 和 term_taxonomy_id 的数组，表示术语创建成功。如果创建失败，则返回一个 WP_Error 对象。

    // ... 上面的代码

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

三、层级关系的处理

wp_insert_term() 在处理层级关系时，主要依赖于 parent 参数。如果 parent 参数为 0，则表示创建的是顶级分类；如果 parent 参数为一个已存在的术语 ID，则表示创建的是该术语的子分类。

在插入数据到 wp_term_taxonomy 表时，会将 parent 参数的值存储到 parent 字段中。这样就建立了术语之间的父子关系。

WordPress 在显示分类时，会根据 parent 字段的值，递归地查询数据库，构建出分类的层级结构。

四、使用 wp_insert_term() 的注意事项

错误处理

在使用 wp_insert_term() 时，一定要注意错误处理。因为创建术语可能会失败，例如，术语名称为空、分类法不存在、别名已存在等等。

可以通过检查返回值是否为 WP_Error 对象来判断是否创建成功。如果创建失败，可以使用 $result->get_error_message() 方法获取错误信息。

$result = wp_insert_term( '我的新分类', 'category' );

if ( is_wp_error( $result ) ) {
    echo '出错了：' . $result->get_error_message();
} else {
    echo '成功创建分类，ID 是：' . $result['term_id'];
}

别名的唯一性

别名 (Slug) 必须是唯一的，否则会导致 URL 冲突。wp_insert_term() 会自动处理别名的唯一性，但如果你的网站有很多分类，可能会导致别名变得很长，影响用户体验。

因此，建议在创建分类时，尽量指定一个简洁、易懂的别名。

父级分类的存在性

如果指定了父级分类，一定要确保父级分类是存在的，并且和当前分类属于同一个分类法。否则会导致创建失败。

性能问题

wp_insert_term() 在创建术语时，会进行一系列的数据库查询和缓存清理操作，如果频繁调用该函数，可能会影响网站的性能。

因此，建议尽量避免在循环中调用 wp_insert_term()，可以考虑使用批量插入的方式，提高效率。

权限问题

创建术语需要一定的权限，如果当前用户没有权限，会导致创建失败。

可以通过 current_user_can() 函数检查用户是否具有相应的权限。

if ( current_user_can( 'manage_categories' ) ) {
    // 创建分类
    $result = wp_insert_term( '我的新分类', 'category' );
} else {
    echo '你没有权限创建分类';
}

五、一些小技巧

批量插入

虽然 wp_insert_term() 没有提供直接的批量插入功能，但可以通过自定义代码实现。例如，可以先将要创建的术语数据存储到一个数组中，然后循环调用 wp_insert_term()，最后统一进行缓存清理。

$terms = array(
    array(
        'name'        => '分类1',
        'taxonomy'    => 'category',
        'description' => '分类1的描述',
    ),
    array(
        'name'        => '分类2',
        'taxonomy'    => 'category',
        'description' => '分类2的描述',
    ),
);

foreach ( $terms as $term ) {
    wp_insert_term( $term['name'], $term['taxonomy'], array( 'description' => $term['description'] ) );
}

// 统一清理缓存
clean_term_cache( null, 'category' );

使用 wp_update_term() 更新术语

如果需要更新已存在的术语，可以使用 wp_update_term() 函数。该函数的用法和 wp_insert_term() 类似，但需要传入术语的 ID。

$result = wp_update_term(
    123, // 术语 ID
    'category',
    array(
        'name'        => '新的分类名称',
        'description' => '新的分类描述',
    )
);

if ( is_wp_error( $result ) ) {
    echo '出错了：' . $result->get_error_message();
} else {
    echo '成功更新分类';
}

使用 term_exists() 检查术语是否存在

在创建术语之前，可以使用 term_exists() 函数检查该术语是否已存在。这样可以避免重复创建相同的术语。

if ( ! term_exists( '我的新分类', 'category' ) ) {
    // 创建分类
    $result = wp_insert_term( '我的新分类', 'category' );
} else {
    echo '该分类已存在';
}

六、总结

wp_insert_term() 是 WordPress 中一个非常重要的函数，用于创建和管理分类术语。了解它的内部逻辑，可以帮助我们更好地使用它，避免一些常见的错误。

希望今天的讲座对大家有所帮助。如果大家还有什么问题，欢迎提问。

七、代码示例表格

代码片段	说明
`php<br>$result = wp_insert_term(<br> '我的新分类', // 术语名称<br> 'category', // 分类法名称 (taxonomy)<br> array(<br> 'description' => '这是我的新分类的描述', // 术语描述<br> 'slug' => 'my-new-category', // 术语别名 (slug)<br> 'parent' => 0 // 父级术语ID (0 表示顶级分类)<br> )<br>);`	创建一个名为“我的新分类”的分类，并设置描述、别名和父级分类。
`php<br>if ( is_wp_error( $result ) ) {<br> echo '出错了：' . $result->get_error_message();<br>} else {<br> echo '成功创建分类，ID 是：' . $result['term_id'];<br>}` \| 检查 `wp_insert_term()` 的返回值，判断是否创建成功，并输出错误信息或成功信息。
`php<br>while ( $wpdb->get_var( $wpdb->prepare( "SELECT term_id FROM $wpdb->terms WHERE slug = %s", $slug ) ) ) {<br> $slug = $original_slug . '-' . $i;<br> $i++;<br>}`	循环检查别名是否已存在，如果已存在，则在别名后面加上递增的数字，直到找到一个唯一的别名。
`php<br>$data = compact( 'name', 'slug' );<br>$wpdb->insert( $wpdb->terms, $data );<br>$term_id = (int) $wpdb->insert_id;` \| 将术语名称和别名插入到 `wp_terms` 表中。
`php<br>$data = array(<br> 'term_id' => $term_id,<br> 'taxonomy' => $taxonomy,<br> 'description' => $description,<br> 'parent' => $parent,<br>);<br>$wpdb->insert( $wpdb->term_taxonomy, $data );<br>$term_taxonomy_id = (int) $wpdb->insert_id;` \| 将术语ID、分类法、描述和父级分类插入到 `wp_term_taxonomy` 表中。
`php<br>wp_update_term_count( $term_id, $taxonomy );`	更新术语的计数，也就是统计每个术语下有多少篇文章。
`php<br>clean_term_cache( $term_id, $taxonomy );`	清理相关的缓存，确保数据是最新的。
`php<br>if ( ! term_exists( '我的新分类', 'category' ) ) {<br> // 创建分类<br> $result = wp_insert_term( '我的新分类', 'category' );<br>} else {<br> echo '该分类已存在';<br>}` \| 使用 `term_exists()` 函数检查该术语是否已存在，避免重复创建相同的术语。

发表回复 取消回复

发表回复取消回复