剖析 WordPress `wp_insert_post()` 函数的源码：它如何调用 `wpdb` 类的 `insert()` 方法，并处理文章元数据。

咳咳，各位观众老爷们，大家好！今天咱们来聊聊 WordPress 里一个非常重要，又有点“神秘”的函数：wp_insert_post()。 它就像个文章制造机，你给它一些参数，它就能帮你把文章“嗖”的一下塞进数据库里。

今天咱们的目标就是把它彻底扒光，看看它到底是怎么“制造”文章的，特别是它如何与 wpdb 打交道，以及如何处理文章的元数据（也就是文章的一些额外信息）。

第一幕：wp_insert_post() 的入口

wp_insert_post() 接受一个数组作为参数，这个数组包含了文章的所有信息，比如标题、内容、状态等等。先来看看它的基本结构（简化版）：

function wp_insert_post( $postarr, $wp_error = false ) {

    // 0. 前期准备：参数预处理和权限检查

    // 1. 数据清洗与验证

    // 2. 准备要插入数据库的数据

    // 3. 核心：使用 wpdb 插入或更新数据

    // 4. 处理分类、标签等分类法

    // 5. 处理文章元数据 (Custom Fields)

    // 6. 触发各种钩子 (Actions)

    // 7. 返回文章 ID

    return $post_id;
}

我们一步一步来解剖。

0. 前期准备：参数预处理和权限检查

wp_insert_post() 会先对传入的 $postarr 数组进行一些预处理，比如设置默认值，检查用户权限等等。 如果用户没有权限发布文章，直接就拜拜了。

1. 数据清洗与验证

接下来，它会对数据进行清洗和验证，防止恶意代码注入，确保数据的安全性。 比如，会对文章标题、内容进行转义，以避免 XSS 攻击。

2. 准备要插入数据库的数据

这一步至关重要！wp_insert_post() 会根据 $postarr 数组，组装出一个新的数组，这个数组是专门给 wpdb 用的。 让我们来看看这个数组里都有啥：

$data = array(
    'post_author'    => $post_author,
    'post_date'      => $post_date,
    'post_date_gmt'  => $post_date_gmt,
    'post_content'   => $post_content,
    'post_title'     => $post_title,
    'post_excerpt'   => $post_excerpt,
    'post_status'    => $post_status,
    'comment_status' => $comment_status,
    'ping_status'    => $ping_status,
    'post_password'  => $post_password,
    'post_name'      => $post_name,
    'to_ping'        => $to_ping,
    'pinged'         => $pinged,
    'post_modified'  => $post_modified,
    'post_modified_gmt' => $post_modified_gmt,
    'post_content_filtered' => $post_content_filtered,
    'post_parent'    => $post_parent,
    'guid'           => $guid,
    'menu_order'     => $menu_order,
    'post_type'      => $post_type,
    'post_mime_type' => $post_mime_type,
    'comment_count'  => $comment_count,
);

这个 $data 数组的键 (key) 对应的是 wp_posts 数据表的列名。

3. 核心：使用 wpdb 插入或更新数据

重头戏来了！wp_insert_post() 会使用 WordPress 自带的数据库操作类 wpdb 来插入或更新数据。

global $wpdb;

if ( $update ) { // 如果是更新文章
    $wpdb->update( $wpdb->posts, $data, array( 'ID' => $post_ID ) );
} else { // 如果是插入新文章
    $wpdb->insert( $wpdb->posts, $data );
    $post_ID = $wpdb->insert_id; // 获取新插入文章的 ID
}

这里我们重点关注 wpdb->insert() 方法。 它接受两个参数：

• $wpdb->posts: 这是 wp_posts 数据表的名称。
• $data: 这是我们要插入的数据，就是上一步我们准备的数组。

wpdb->insert() 会根据 $data 数组，自动生成 SQL 语句，然后执行插入操作。 就像这样：

INSERT INTO wp_posts (post_author, post_date, post_date_gmt, post_content, post_title, ...)
VALUES (%d, %s, %s, %s, %s, ...);

其中的 %d、%s 等是占位符，wpdb 会自动将 $data 数组中的值替换掉这些占位符，防止 SQL 注入。

wpdb->insert() 源码剖析

为了更深入地了解 wpdb->insert()，我们来简单看看它的源码（简化版）：

class wpdb {
    function insert( $table, $data, $format = null ) {
        return $this->query( $this->prepare( "INSERT INTO `$table` ( `" . implode( '`, `', array_keys( $data ) ) . "` ) VALUES ( " . implode( ', ', array_fill( 0, count( $data ), '%s' ) ) . " )", array_values( $data ) ) );
    }

    function prepare( $query, ...$args ) {
        // 这个函数负责处理占位符，防止 SQL 注入
        // 省略具体实现
        return $prepared_query;
    }

    function query( $query ) {
        // 这个函数负责执行 SQL 查询
        // 省略具体实现
        return $this->last_result;
    }
}

可以看到，wpdb->insert() 实际上是调用了 wpdb->prepare() 和 wpdb->query() 这两个方法。

• wpdb->prepare() 负责处理占位符，防止 SQL 注入。 它会把 $data 数组中的值转义，确保安全。
• wpdb->query() 负责执行 SQL 查询。 它会把最终的 SQL 语句发送给数据库，然后返回结果。

4. 处理分类、标签等分类法 (Taxonomies)

文章插入数据库后，wp_insert_post() 还会处理文章的分类、标签等分类法。 它会调用 wp_set_object_terms() 函数，将文章与对应的分类、标签关联起来。

5. 处理文章元数据 (Custom Fields)

接下来就是我们今天的主角之一：文章元数据！ 也就是我们常说的自定义字段。

文章元数据存储在 wp_postmeta 数据表中。 每一条元数据都包含四个字段：

字段名	类型	描述
meta_id	BIGINT	元数据的 ID，自增
post_id	BIGINT	文章的 ID，关联 wp_posts 表
meta_key	VARCHAR	元数据的键 (key)，比如 "author_name"
meta_value	LONGTEXT	元数据的值 (value)，比如 "张三"

wp_insert_post() 使用 update_post_meta()、add_post_meta() 和 delete_post_meta() 这三个函数来管理文章元数据。

• update_post_meta( $post_id, $meta_key, $meta_value ): 更新指定文章的元数据。如果指定的 meta_key 已经存在，就更新它的值；否则，就新增一条元数据。
• add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ): 新增一条元数据。 $unique 参数表示是否允许同一个文章拥有多个相同 meta_key 的元数据。 如果 $unique 为 true，则只允许新增一条；否则，可以新增多条。
• delete_post_meta( $post_id, $meta_key, $meta_value = '', $delete_all = false ): 删除指定文章的元数据。 可以根据 meta_key 和 meta_value 来删除，也可以删除所有指定 meta_key 的元数据。

update_post_meta() 源码剖析

我们以 update_post_meta() 为例，来看看它是如何与 wpdb 打交道的：

function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) {
    global $wpdb;

    if ( ! $post_id || ! is_numeric( $post_id ) ) {
        return false;
    }

    $meta_key = wp_unslash( $meta_key );
    $meta_value = wp_unslash( $meta_value );

    $meta_id = $wpdb->get_var( $wpdb->prepare( "SELECT meta_id FROM $wpdb->postmeta WHERE post_id = %d AND meta_key = %s", $post_id, $meta_key ) );

    if ( $meta_id ) {
        // 如果 meta_key 已经存在，更新它的值
        if ( is_string( $meta_value ) ) {
            $meta_value = wp_slash( $meta_value );
        }

        $result = $wpdb->update(
            $wpdb->postmeta,
            array( 'meta_value' => $meta_value ),
            array( 'meta_id' => $meta_id )
        );

        return (bool) $result;
    } else {
        // 如果 meta_key 不存在，新增一条元数据
        return add_post_meta( $post_id, $meta_key, $meta_value );
    }
}

可以看到，update_post_meta() 首先会查询 wp_postmeta 数据表，看看是否存在指定 post_id 和 meta_key 的元数据。

• 如果存在，就使用 wpdb->update() 方法更新 meta_value 字段。
• 如果不存在，就调用 add_post_meta() 方法新增一条元数据。

wpdb->update() 的用法和 wpdb->insert() 类似，只不过它是用来更新数据的。

add_post_meta() 源码剖析

function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) {
    global $wpdb;

    if ( ! $post_id || ! is_numeric( $post_id ) ) {
        return false;
    }

    $meta_key = wp_unslash( $meta_key );
    $meta_value = wp_unslash( $meta_value );

    if ( $unique ) {
        // 如果 unique 为 true，检查是否已经存在相同的 meta_key
        $existing_meta = $wpdb->get_var( $wpdb->prepare( "SELECT meta_id FROM $wpdb->postmeta WHERE post_id = %d AND meta_key = %s", $post_id, $meta_key ) );

        if ( $existing_meta ) {
            return false; // 已经存在，不允许新增
        }
    }

    if ( is_string( $meta_value ) ) {
        $meta_value = wp_slash( $meta_value );
    }

    $result = $wpdb->insert(
        $wpdb->postmeta,
        array(
            'post_id'    => $post_id,
            'meta_key'   => $meta_key,
            'meta_value' => $meta_value,
        ),
        array(
            '%d',
            '%s',
            '%s',
        )
    );

    if ( $result ) {
        wp_cache_delete( $post_id, 'post_meta' );
        return (int) $wpdb->insert_id;
    }

    return false;
}

add_post_meta() 会先根据 $unique 参数，判断是否允许新增相同的 meta_key。 如果允许，就直接使用 wpdb->insert() 方法向 wp_postmeta 数据表插入一条新的元数据。

delete_post_meta() 源码剖析

function delete_post_meta( $post_id, $meta_key, $meta_value = '', $delete_all = false ) {
    global $wpdb;

    if ( ! $post_id || ! is_numeric( $post_id ) ) {
        return false;
    }

    $meta_key = wp_unslash( $meta_key );

    if ( $delete_all ) {
        // 删除所有指定 meta_key 的元数据
        $result = $wpdb->delete(
            $wpdb->postmeta,
            array(
                'post_id'  => $post_id,
                'meta_key' => $meta_key,
            ),
            array(
                '%d',
                '%s',
            )
        );
    } else {
        // 根据 meta_key 和 meta_value 删除元数据
        $meta_value = wp_unslash( $meta_value );

        $result = $wpdb->delete(
            $wpdb->postmeta,
            array(
                'post_id'    => $post_id,
                'meta_key'   => $meta_key,
                'meta_value' => $meta_value,
            ),
            array(
                '%d',
                '%s',
                '%s',
            )
        );
    }

    if ( $result ) {
        wp_cache_delete( $post_id, 'post_meta' );
        return true;
    }

    return false;
}

delete_post_meta() 使用 wpdb->delete() 方法从 wp_postmeta 数据表中删除元数据。 可以根据 meta_key 和 meta_value 精确删除，也可以直接删除所有指定 meta_key 的元数据。

6. 触发各种钩子 (Actions)

文章插入或更新后，wp_insert_post() 会触发一系列的钩子 (Actions)，允许开发者在文章发布前后执行自定义操作。 比如，可以利用 save_post 钩子，在文章保存后发送邮件通知。

7. 返回文章 ID

最后，wp_insert_post() 会返回新插入或更新的文章的 ID。

总结

今天我们一起深入剖析了 wp_insert_post() 函数的源码，了解了它是如何与 wpdb 打交道，以及如何处理文章的元数据。

简单来说，wp_insert_post() 的工作流程可以概括为以下几步：

1. 接收文章数据。
2. 数据清洗和验证。
3. 准备要插入数据库的数据。
4. 使用 wpdb->insert() 或 wpdb->update() 插入或更新数据。
5. 处理分类、标签等分类法。
6. 使用 update_post_meta()、add_post_meta() 和 delete_post_meta() 管理文章元数据。
7. 触发各种钩子。
8. 返回文章 ID。

希望通过今天的讲解，大家对 wp_insert_post() 函数有了更深入的了解。 掌握了这个函数，你就能更好地控制 WordPress 的文章发布流程，实现更强大的功能。

今天的讲座就到这里，谢谢大家！ 以后有机会再和大家一起深入探讨 WordPress 的其他“神秘”函数。 下课！