详解 WordPress `wp_insert_post()` 函数在 WP-CLI 中的源码：如何在命令行中创建文章。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众，各位朋友，欢迎来到今天的“WordPress源码解剖”讲座！我是老码农李大锤，今天咱们要聊的是一个在WordPress开发中非常重要的函数：wp_insert_post()，以及如何在WP-CLI（WordPress命令行工具）中利用它来呼风唤雨，哦不，是创建文章。

咱们的目标是：从源码的角度，彻底搞懂 wp_insert_post()，并学会如何在命令行中高效地批量创建、更新文章。准备好了吗？Let’s rock!

一、wp_insert_post()：文章创建的引擎

首先，我们要认识一下今天的主角：wp_insert_post()。这个函数是WordPress的核心函数之一，负责在数据库中插入或更新文章（包括页面、自定义文章类型等）。

函数签名：

/**
 * Inserts or updates a post.
 *
 * @since 2.0.0
 *
 * @param array|object $postarr An array or object of post data. See wp_parse_args() for information
 *                              on accepted arguments.
 * @param bool         $wp_error Whether to return a WP_Error on failure. Default false.
 * @return int|WP_Error The post ID on success. The value 0 or WP_Error on failure.
 */
function wp_insert_post( $postarr = array(), $wp_error = false ) {
  // 函数体内容
}

参数解析：
- $postarr：这是一个数组或对象，包含了文章的所有数据，例如标题、内容、状态、作者等等。这是最关键的参数，决定了你要创建什么样的文章。
- $wp_error：一个布尔值，决定了如果插入失败，是返回 0 还是 WP_Error 对象。方便进行错误处理。
返回值：
- 成功：返回新创建或更新的文章的 ID。
- 失败：返回 0 或者 WP_Error 对象（取决于 $wp_error 参数）。

二、$postarr：文章数据的容器

$postarr 数组是 wp_insert_post() 的灵魂所在。它定义了文章的所有属性。让我们来详细看看它能包含哪些关键字段：

字段名	数据类型	描述	默认值
`post_author`	int	文章作者的 ID。	当前用户 ID
`post_date`	string	文章发布日期，格式为 ‘YYYY-MM-DD HH:MM:SS’。	当前时间
`post_date_gmt`	string	文章发布日期的 GMT 时间，格式同 `post_date`。	根据 `post_date` 自动计算
`post_content`	string	文章内容。	空字符串
`post_title`	string	文章标题。	空字符串
`post_excerpt`	string	文章摘要。	空字符串
`post_status`	string	文章状态，例如 ‘publish’（已发布）、’draft’（草稿）、’pending’（待审核）、’future’（预定发布）等。	‘draft’
`comment_status`	string	评论状态，’open’（允许评论）或 ‘closed’（禁止评论）。	‘open’
`ping_status`	string	引用通告状态，’open’（允许引用通告）或 ‘closed’（禁止引用通告）。	‘open’
`post_password`	string	文章密码，用于保护文章。	空字符串
`post_name`	string	文章别名（slug），URL 友好的版本。	根据标题自动生成，也可以手动指定
`to_ping`	string	要进行引用通告的 URL 列表，用空格分隔。	空字符串
`pinged`	string	已经进行过引用通告的 URL 列表，用空格分隔。	空字符串
`post_modified`	string	文章最后修改日期，格式同 `post_date`。	当前时间
`post_modified_gmt`	string	文章最后修改日期的 GMT 时间，格式同 `post_date_gmt`。	根据 `post_modified` 自动计算
`post_content_filtered`	string	经过过滤的文章内容。	空字符串
`post_parent`	int	父级文章的 ID（用于页面或分层自定义文章类型）。	0
`guid`	string	文章的唯一标识符，通常是一个 URL。	自动生成
`menu_order`	int	菜单排序。	0
`post_type`	string	文章类型，例如 ‘post’（文章）、’page’（页面）、’attachment’（附件）或自定义文章类型。	‘post’
`post_mime_type`	string	文章的 MIME 类型（仅适用于附件）。	空字符串
`comment_count`	int	评论数量。	0
`tax_input`	array	分类法（taxonomy）数据，用于设置文章的分类、标签等。	空数组
`meta_input`	array	自定义字段（meta）数据，用于存储文章的额外信息。	空数组
`ID`	int	文章 ID。如果指定了 ID，则表示更新文章，而不是创建新文章。	0（表示创建新文章）

三、wp_insert_post() 源码剖析

咱们来深入源码，看看 wp_insert_post() 内部都做了些什么。由于源码比较长，我们只关注关键部分：

function wp_insert_post( $postarr = array(), $wp_error = false ) {
  global $wpdb;

  // 1. 准备数据
  $defaults = array(
    'post_status' => 'draft',
    'post_type' => 'post',
    'post_author' => get_current_user_id(),
    'ping_status' => get_option( 'default_ping_status' ),
    'post_parent' => 0,
    'menu_order' => 0,
    'to_ping' => '',
    'pinged' => '',
    'post_excerpt' => '',
    'post_content_filtered' => '',
    'post_password' => '',
    'post_mime_type' => '',
    'guid' => '',
    'import_id' => 0,
    'comment_status' => get_option( 'default_comment_status' ),
  );

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

  // 2. 数据验证和过滤
  $postarr = sanitize_post( $postarr, 'db' );

  // 3. 触发 'pre_insert_post' action
  do_action( 'pre_insert_post', $postarr );

  // 4. 检查是否需要更新文章
  if ( ! empty( $postarr['ID'] ) ) {
    $update = true;
    $post_ID = (int) $postarr['ID'];
  } else {
    $update = false;
  }

  // 5. 插入或更新文章数据
  if ( $update ) {
    // 更新文章
    $wpdb->update( $wpdb->posts, $data, array( 'ID' => $post_ID ) );
  } else {
    // 插入文章
    $wpdb->insert( $wpdb->posts, $data );
    $post_ID = (int) $wpdb->insert_id;
  }

  // 6. 更新分类法 (Taxonomies)
  wp_set_post_terms( $post_ID, $postarr['tax_input'] );

  // 7. 更新自定义字段 (Meta)
  if ( isset( $postarr['meta_input'] ) ) {
    foreach ( $postarr['meta_input'] as $key => $value ) {
      update_post_meta( $post_ID, $key, $value );
    }
  }

  // 8. 触发 'wp_insert_post' action
  do_action( 'wp_insert_post', $post_ID, $post, $update );

  return $post_ID;
}

关键步骤解析：
1. 准备数据： 使用 wp_parse_args() 将传入的 $postarr 数组与默认值合并，确保所有必要的字段都有值。
2. 数据验证和过滤： 使用 sanitize_post() 函数对数据进行清理和验证，防止恶意代码注入。
3. 触发 pre_insert_post action： 允许其他插件或主题在文章插入之前对数据进行修改。
4. 判断是插入还是更新： 根据 $postarr['ID'] 是否存在来判断是创建新文章还是更新现有文章。
5. 插入或更新文章数据： 使用 $wpdb->insert() 或 $wpdb->update() 方法将数据插入或更新到 wp_posts 表中。
6. 更新分类法： 使用 wp_set_post_terms() 函数更新文章的分类、标签等。
7. 更新自定义字段： 使用 update_post_meta() 函数更新文章的自定义字段。
8. 触发 wp_insert_post action： 允许其他插件或主题在文章插入或更新之后执行一些操作。

四、WP-CLI 与 wp_insert_post()：命令行下的文章管理

现在，我们来学习如何在 WP-CLI 中使用 wp_insert_post()。WP-CLI 允许你在命令行中管理 WordPress，这对于批量创建文章、自动化任务非常有用。

WP-CLI 命令：wp post create

WP-CLI 提供了一个 wp post create 命令，它实际上就是对 wp_insert_post() 函数的封装。
基本用法：
```
wp post create --post_title='我的第一篇文章' --post_content='这是文章的内容。' --post_status='publish'
```
这条命令会创建一个标题为 "我的第一篇文章"，内容为 "这是文章的内容"，状态为 "已发布" 的文章。
高级用法：
- 从文件中读取内容：
```
wp post create --post_title='我的文章' --post_content=@path/to/content.txt
```
  这会将 content.txt 文件中的内容作为文章的内容。
- 批量创建文章：
  
  可以使用脚本来循环创建文章。例如，创建一个名为 create_posts.sh 的脚本：
```
#!/bin/bash

for i in {1..10}; do
  wp post create --post_title="文章标题 $i" --post_content="文章内容 $i" --post_status='publish'
done
```
  然后执行 bash create_posts.sh，就可以创建 10 篇文章了。
- 更新文章：
```
wp post update <post_id> --post_title='新的文章标题' --post_content='新的文章内容'
```
  将 <post_id> 替换为要更新的文章的 ID。
- 自定义字段：
  虽然wp post create 本身不能直接设置自定义字段，但是可以使用 --porcelain 参数来获取新创建的文章ID，然后通过wp post meta来设置自定义字段。
```
post_id=$(wp post create --post_title='文章标题' --post_content='文章内容' --porcelain)
wp post meta add $post_id my_custom_field '自定义字段的值'
```
一个更复杂的例子：批量导入文章并设置分类

假设你有一个 CSV 文件 articles.csv，包含了文章的标题、内容和分类信息，你想使用 WP-CLI 批量导入这些文章并设置分类。

articles.csv 内容示例：

title,content,category
文章标题1,文章内容1,分类1
文章标题2,文章内容2,分类2
文章标题3,文章内容3,分类1|分类3

创建一个 PHP 脚本 import_posts.php：

<?php

// 确保在 WP-CLI 环境中运行
if ( ! defined( 'WP_CLI' ) || ! WP_CLI ) {
  return;
}

/**
 * 导入文章
 *
 * @when before_wp_load
 */
WP_CLI::add_command( 'import_posts', function( $args, $assoc_args ) {
  $csv_file = WP_CLI::get_config( 'csv_file', 'articles.csv' ); // 允许通过 --csv_file=xxx 指定CSV文件

  // 读取 CSV 文件
  $rows = array_map( 'str_getcsv', file( $csv_file ) );
  $header = array_shift( $rows );

  foreach ( $rows as $row ) {
    $data = array_combine( $header, $row );

    $post_title = $data['title'];
    $post_content = $data['content'];
    $categories = explode( '|', $data['category'] );

    // 创建文章
    $post_id = wp_insert_post( array(
      'post_title' => $post_title,
      'post_content' => $post_content,
      'post_status' => 'publish',
    ) );

    if ( is_wp_error( $post_id ) ) {
      WP_CLI::error( "创建文章失败： " . $post_id->get_error_message() );
      continue;
    }

    // 设置分类
    wp_set_post_terms( $post_id, $categories, 'category' );

    WP_CLI::success( "成功创建文章：$post_title (ID: $post_id)" );
  }
} );

// 添加配置项，允许通过 --csv_file=xxx 指定csv文件
WP_CLI::add_config( 'csv_file', 'articles.csv', 'CSV 文件路径' );

将 import_posts.php 放在 WordPress 插件目录下，激活插件。

然后，在命令行中运行：

wp import_posts

或者，如果你想使用不同的CSV文件：

wp import_posts --csv_file=my_articles.csv

这个脚本会读取 articles.csv 文件，循环创建文章，并根据 CSV 文件中的 "category" 字段设置文章的分类。注意，这里使用了 WP_CLI::get_config和WP_CLI::add_config，使得用户可以通过命令行参数 --csv_file=xxx 来覆盖默认的CSV文件名，增强了灵活性。

五、最佳实践与注意事项

数据验证： 在使用 wp_insert_post() 之前，一定要对数据进行验证，防止恶意代码注入。
错误处理： 检查 wp_insert_post() 的返回值，如果返回的是 WP_Error 对象，要进行相应的错误处理。
性能优化： 批量创建文章时，尽量减少数据库查询次数。可以考虑使用 wp_suspend_cache_addition() 函数来暂停缓存更新，提高性能。
钩子利用： 善用 pre_insert_post 和 wp_insert_post 这两个 action 钩子，可以在文章创建前后执行一些自定义操作。
安全第一： 在 WP-CLI 中执行命令时，要确保命令的安全性，防止未经授权的用户执行敏感操作。

六、总结

今天，我们深入剖析了 wp_insert_post() 函数的源码，并学习了如何在 WP-CLI 中利用它来创建和更新文章。希望通过今天的讲解，大家能够更加熟练地掌握这个强大的工具，提高 WordPress 开发效率。

记住，理解源码是成为优秀开发者的关键一步。下次遇到类似的问题，不妨打开源码，仔细研究一番，你会发现一个全新的世界！

感谢大家的收听！下次再见！

发表回复 取消回复

发表回复取消回复