剖析 WordPress `wpdb` 类的 `insert()` 方法源码：它是如何安全地构建 `INSERT` 语句并处理占位符的。

各位观众老爷，大家好！ 欢迎来到今天的“WordPress源码大冒险”系列讲座。 今天我们要扒的是WordPress数据库操作的核心——wpdb类的insert()方法。 这个方法看似简单，但其实藏着不少小秘密，比如如何安全地构建SQL语句，以及如何优雅地处理占位符。 准备好了吗？ Let’s dive in!

1. wpdb::insert() 方法的概览

首先，让我们大致了解一下 wpdb::insert() 方法的作用。 它的主要任务是将数据插入到数据库表中。 它的基本用法如下：

$wpdb->insert(
    string $table,
    array $data,
    array|string|null $format = null
): int|false

• $table: 要插入数据的表名。
• $data: 一个关联数组，键是表中的列名，值是要插入的数据。
• $format: 一个数组，指定 $data 数组中每个值的格式。 可以是字符串，例如 ‘%s’, ‘%d’, ‘%f’， 也可以是 null，让 wpdb 自动推断类型。

返回值：

• 成功时，返回插入的行数。
• 失败时，返回 false。

2. 源码剖析：从入口到 SQL 构建

现在，让我们深入 wpdb::insert() 的源码，一步步追踪它是如何构建 SQL 语句的。

public function insert( string $table, array $data, array|string|null $format = null ): int|false {
    $table = esc_sql( $table );

    $formats = $format ? (array) $format : array();
    $fields  = array_keys( $data );
    $values  = array_values( $data );

    // Build format array if different from data array.
    if ( count( $formats ) !== count( $fields ) ) {
        foreach ( $fields as $field ) {
            $formats[] = '%s';
        }
    }

    $fields  = '`' . implode( '`,`', array_map( 'esc_sql', $fields ) ) . '`';
    $holders = implode( ',', $formats );

    $sql = "INSERT INTO `$table` ($fields) VALUES ($holders)";

    return $this->query( $this->prepare( $sql, $values ) );
}

让我们一行一行来解读这段代码：

• $table = esc_sql( $table );: esc_sql() 函数用于转义表名中的特殊字符，防止 SQL 注入。 这是一个非常重要的安全措施。
• $formats = $format ? (array) $format : array();: 如果提供了 $format 参数，就将其转换为数组；否则，创建一个空数组。
• $fields = array_keys( $data );: 获取 $data 数组的所有键，也就是列名。
• $values = array_values( $data );: 获取 $data 数组的所有值，也就是要插入的数据。
• if ( count( $formats ) !== count( $fields ) ) { ... }: 如果 $formats 数组的长度与 $fields 数组的长度不一致，说明没有为每个字段指定格式，那么就为每个字段都添加一个默认的格式 ‘%s’ (字符串)。
• $fields = '‘ . implode( ‘,‘, array_map( ‘esc_sql’, $fields ) ) . ‘';: 这个地方有点绕，我们拆解一下：
  • array_map( 'esc_sql', $fields ): 使用 esc_sql() 函数转义每个列名中的特殊字符，防止 SQL 注入。
  • implode( ',', ... ): 将转义后的列名用 ‘,‘ 连接起来，形成一个用反引号包裹的列名列表，例如 'column1,column2`,column3``'。 为什么要用反引号呢？ 因为有些列名可能包含特殊字符或SQL保留字，用反引号可以避免解析错误。
• $holders = implode( ',', $formats );: 将 $formats 数组中的格式化字符串用逗号连接起来，形成一个占位符列表，例如 ‘%s,%d,%f’。
• $sql = "INSERT INTO$table($fields) VALUES ($holders)";: 将表名、列名列表和占位符列表组合成一个完整的 SQL 语句，但此时的 SQL 语句仍然包含占位符，例如 INSERT INTO my_table` (`column1`,`column2`) VALUES (%s,%d)`。
• return $this->query( $this->prepare( $sql, $values ) );: 调用 $this->prepare() 方法来安全地替换 SQL 语句中的占位符，然后调用 $this->query() 方法执行 SQL 语句，并将结果返回。

3. wpdb::prepare() 方法：占位符的秘密武器

wpdb::prepare() 方法是 WordPress 中处理 SQL 占位符的关键。 它的作用是将 SQL 语句中的占位符替换为实际的值，并且在替换之前对值进行必要的转义，以防止 SQL 注入。

public function prepare( string $query, array|mixed $args ): string {
    if ( is_null( $query ) ) {
        return '';
    }

    $args = func_get_args();
    array_shift( $args ); // Remove $query.
    if ( is_array( $args[0] ) ) {
        $args = $args[0];
    }
    $query = str_replace( "'%s'", '%s', $query ); // Strip slashes added by esc_sql.
    $query = str_replace( '"%s"', '%s', $query ); // Strip slashes added by esc_sql.

    $query = str_replace( "'%d'", '%d', $query ); // Strip slashes added by esc_sql.
    $query = str_replace( '"%d"', '%d', $query ); // Strip slashes added by esc_sql.
    $query = str_replace( "'%f'", '%f', $query ); // Strip slashes added by esc_sql.
    $query = str_replace( '"%f"', '%f', $query ); // Strip slashes added by esc_sql.

    $num_args = count( $args );
    $index    = 0;

    $query = preg_replace_callback(
        '/%(([sd])|f)/',
        function ( $match ) use ( &$index, $num_args, $args ) {
            if ( $index >= $num_args ) {
                return $match[0];
            }

            $arg   = $args[ $index ];
            $index++;

            switch ( $match[2] ) {
                case 's':
                    return "'" . esc_sql( $arg ) . "'";
                case 'd':
                    return intval( $arg );
                case 'f':
                    return floatval( $arg );
                default:
                    return $match[0];
            }
        },
        $query
    );

    return $query;
}

让我们逐步分析这段代码：

• if ( is_null( $query ) ) { return ''; }: 如果传入的SQL语句为空，则直接返回空字符串。
• $args = func_get_args(); array_shift( $args );: 获取所有传入的参数，并移除第一个参数（SQL语句）。
• if ( is_array( $args[0] ) ) { $args = $args[0]; }: 如果第二个参数是一个数组，则将其展开为参数列表。 这种设计允许你传入一个数组作为所有占位符的值。
• $query = str_replace( "'%s'", '%s', $query ); ...: 这几行代码的作用是移除由 esc_sql() 函数添加的反斜杠。 为什么要移除呢？ 因为在 $wpdb->insert() 方法中，我们已经对列名进行了转义，如果这里再对值进行转义，可能会导致重复转义，从而出现错误。 举个例子，如果一个字符串中包含单引号，esc_sql() 会将其转义为 '。 如果我们不移除这些反斜杠，那么最终插入到数据库中的字符串就会变成 \'，这显然不是我们想要的结果。
• $num_args = count( $args ); $index = 0;: 获取参数的数量，并初始化一个索引变量 $index，用于追踪当前处理的参数。
• $query = preg_replace_callback( '/%(([sd])|f)/', ... , $query );: 这是最核心的部分。 它使用 preg_replace_callback() 函数来查找 SQL 语句中的占位符（%s, %d, %f），并使用一个回调函数来替换它们。

让我们来看看回调函数做了什么：

• if ( $index >= $num_args ) { return $match[0]; }: 如果当前索引超出了参数的数量，说明 SQL 语句中的占位符比提供的参数多，那么就直接返回占位符本身，不进行替换。 这可以防止出现错误。
• $arg = $args[ $index ]; $index++;: 获取当前参数的值，并将索引加 1。
• switch ( $match[2] ) { ... }: 根据占位符的类型（%s, %d, %f）来对参数进行不同的处理：
  • case 's': 如果是字符串占位符 (%s)，则使用 esc_sql() 函数对参数进行转义，然后用单引号包裹。 为什么要用单引号包裹呢？ 因为在 SQL 中，字符串必须用单引号括起来。
  • case 'd': 如果是整数占位符 (%d)，则使用 intval() 函数将参数转换为整数。
  • case 'f': 如果是浮点数占位符 (%f)，则使用 floatval() 函数将参数转换为浮点数。
  • default: 如果占位符类型未知，则直接返回占位符本身，不进行替换。

4. 安全性考量：SQL 注入的防范

wpdb::insert() 和 wpdb::prepare() 方法在防止 SQL 注入方面做了很多工作。 总结如下：

• 参数化查询： 使用占位符来代替直接将值嵌入到 SQL 语句中。 这样可以避免将用户输入的数据作为 SQL 代码来执行。
• 输入验证和转义： 使用 esc_sql() 函数对表名、列名和字符串类型的值进行转义，以防止恶意用户输入包含 SQL 代码的字符串。
• 类型转换： 使用 intval() 和 floatval() 函数将整数和浮点数类型的值转换为相应的类型，以确保数据的正确性。

虽然 wpdb 类已经做了很多安全措施，但仍然需要开发者注意以下几点：

• 永远不要信任用户输入： 即使使用了 wpdb::prepare() 方法，也应该对用户输入的数据进行验证，以确保其符合预期的格式和范围。
• 避免拼接 SQL 语句： 尽量使用 wpdb::insert(), wpdb::update(), wpdb::delete() 等方法来操作数据库，避免手动拼接 SQL 语句。
• 使用白名单验证： 对于一些特定的字段，例如枚举类型或布尔类型，可以使用白名单验证来确保用户输入的值是合法的。

5. 举例说明：让代码说话

为了更好地理解 wpdb::insert() 方法的工作原理，让我们来看几个例子：

例子 1：插入一条简单的记录

global $wpdb;

$table_name = $wpdb->prefix . 'my_table';

$data = array(
    'column1' => 'Hello',
    'column2' => 123,
    'column3' => 3.14
);

$result = $wpdb->insert(
    $table_name,
    $data
);

if ( $result ) {
    echo 'Successfully inserted ' . $result . ' row(s).';
} else {
    echo 'Error inserting data: ' . $wpdb->last_error;
}

在这个例子中，我们向 wp_my_table 表中插入一条记录。 由于没有提供 $format 参数，wpdb 会自动将所有字段都视为字符串类型。

生成的 SQL 语句如下（经过 $wpdb->prepare() 处理）：

INSERT INTO `wp_my_table` (`column1`,`column2`,`column3`) VALUES ('Hello','123','3.14')

例子 2：指定数据类型

global $wpdb;

$table_name = $wpdb->prefix . 'my_table';

$data = array(
    'column1' => 'Hello',
    'column2' => 123,
    'column3' => 3.14
);

$format = array(
    '%s',
    '%d',
    '%f'
);

$result = $wpdb->insert(
    $table_name,
    $data,
    $format
);

if ( $result ) {
    echo 'Successfully inserted ' . $result . ' row(s).';
} else {
    echo 'Error inserting data: ' . $wpdb->last_error;
}

在这个例子中，我们提供了 $format 参数，明确指定了每个字段的数据类型。

生成的 SQL 语句如下（经过 $wpdb->prepare() 处理）：

INSERT INTO `wp_my_table` (`column1`,`column2`,`column3`) VALUES ('Hello',123,3.14)

例子 3：使用数组作为参数

global $wpdb;

$table_name = $wpdb->prefix . 'my_table';

$data = array(
    'column1' => 'Hello',
    'column2' => 123,
    'column3' => 3.14
);

$format = array(
    '%s',
    '%d',
    '%f'
);

$sql = "INSERT INTO `$table_name` (`column1`,`column2`,`column3`) VALUES (%s,%d,%f)";
$prepared_query = $wpdb->prepare($sql, array_values($data));

$result = $wpdb->query($prepared_query);

if ( $result ) {
    echo 'Successfully inserted row(s).';
} else {
    echo 'Error inserting data: ' . $wpdb->last_error;
}

在这个例子中，我们手动构建 SQL 语句，并使用 wpdb->prepare() 方法来处理占位符。 我们将 $data 数组的值作为参数传递给 wpdb->prepare() 方法。

6. 总结：掌握 wpdb::insert()，玩转数据库

wpdb::insert() 方法是 WordPress 中操作数据库的重要工具。 通过深入了解它的源码，我们可以更好地理解它是如何构建 SQL 语句，如何处理占位符，以及如何防止 SQL 注入的。 掌握了这些知识，我们就能更加安全、高效地使用 WordPress 的数据库功能。

表格总结

方法/函数	作用
wpdb::insert()	将数据插入到数据库表中。
wpdb::prepare()	安全地替换 SQL 语句中的占位符，防止 SQL 注入。
esc_sql()	转义字符串中的特殊字符，防止 SQL 注入。
intval()	将变量转换为整数。
floatval()	将变量转换为浮点数。
array_keys()	返回数组的所有键。
array_values()	返回数组的所有值。
implode()	将数组元素连接成一个字符串。
array_map()	对数组的每个元素应用回调函数。
preg_replace_callback()	执行一个正则表达式搜索并且使用一个回调进行替换。

今天的讲座就到这里。 感谢大家的观看！ 希望大家有所收获，在 WordPress 的世界里玩得开心！ 下次再见！