解释 `wp_json_encode()` 和 `wp_json_decode()` 函数的源码，它们如何封装 PHP 原生函数并处理编码问题？

各位好，今天咱们来聊聊 WordPress 里两个相当实在的函数：wp_json_encode() 和 wp_json_decode()。别看名字简单，它们可是 WordPress 在 JSON 数据处理上的一把好手，尤其是在编码问题上，更是下了不少功夫。

咱们先来热热身，看看这两个函数的原型：

<?php
/**
 * Encodes a PHP variable into a JSON string.
 *
 * @since 4.4.0
 *
 * @param mixed $data    The variable being encoded. Can be any type except a resource.
 * @param int   $options Optional. Options to be passed to json_encode(). Default 0.
 * @param int   $depth   Optional. The maximum depth. Must be greater than zero. Default 512.
 * @return string|false JSON encoded string on success or false on failure.
 */
function wp_json_encode( $data, $options = 0, $depth = 512 ) {
    // 函数体
}

/**
 * Decodes a JSON string into a PHP variable.
 *
 * @since 4.4.0
 *
 * @param string $json    The JSON string being decoded.
 * @param bool   $assoc   Optional. When true, returned objects will be converted into associative arrays. Default false.
 * @param int    $depth   Optional. User specified recursion depth. Default 512.
 * @param int    $options Optional. Bitmask of JSON decode options. Currently supports only
 *                        JSON_BIGINT_AS_STRING (default) and JSON_OBJECT_AS_ARRAY.
 * @return mixed The value encoded in JSON in appropriate PHP type. null is returned if
 *               the json cannot be decoded or if the encoded data is deeper than the
 *               recursion limit.
 */
function wp_json_decode( $json, $assoc = false, $depth = 512, $options = 0 ) {
    // 函数体
}

看到了吧？它们分别对应 PHP 的 json_encode() 和 json_decode()，但又不仅仅是简单的封装。接下来，咱们就一点一点地扒开它们的外衣，看看里面都藏了些什么玄机。

1. wp_json_encode()：披着 WordPress 外衣的 json_encode()

咱们先从 wp_json_encode() 开始。它的主要任务是把 PHP 的数据结构（比如数组、对象）转换成 JSON 字符串。

function wp_json_encode( $data, $options = 0, $depth = 512 ) {
    /**
     * Filters the JSON-encoded string before returning.
     *
     * @since 4.4.0
     *
     * @param string $json    JSON-encoded string.
     * @param mixed  $data    The value being encoded.
     * @param int    $options Optional. Options to be passed to json_encode(). Default 0.
     * @param int    $depth   Optional. The maximum depth. Must be greater than zero. Default 512.
     */
    $json = json_encode( $data, $options, $depth );

    if ( false === $json ) {
        return false;
    }

    return $json;
}

这代码简单到让人想哭！核心就是调用了 PHP 原生的 json_encode() 函数。但别急，事情并没有这么简单。WordPress 为什么要封装这一层呢？

• 统一接口： 方便日后扩展和修改。万一哪天 PHP 的 json_encode() 升级了，或者 WordPress 需要自定义一些行为，就可以在这里做文章，而不用修改所有调用 json_encode() 的地方。
• 可扩展性： 通过过滤器，允许开发者在 JSON 编码前后进行一些自定义操作。

重点：编码问题处理

虽然上面的代码看起来很简单，但 wp_json_encode() 实际上暗藏玄机，它间接处理了编码问题，尤其是在处理多字节字符（比如中文）时。

json_encode() 在处理 UTF-8 编码的字符串时表现良好。但是，如果你的数据源不是 UTF-8 编码，那么 json_encode() 可能会返回 false，或者产生乱码。

WordPress 假设你的数据是 UTF-8 编码的，并且建议你在处理数据之前，确保你的数据已经被正确地编码为 UTF-8。 WordPress 核心本身也大量使用 UTF-8 编码。

代码示例：

<?php
$data = array(
    'name' => '张三', // 中文姓名
    'age'  => 30,
);

$json = wp_json_encode( $data );

if ( $json ) {
    echo $json; // 输出：{"name":"张三","age":30}
} else {
    echo 'JSON 编码失败！';
}
?>

在这个例子中，如果你的 PHP 文件的编码不是 UTF-8，或者你的数据库连接编码不是 UTF-8，那么 wp_json_encode() 可能会失败。你需要确保所有环节都使用 UTF-8 编码。

2. wp_json_decode()：解码 JSON，更要防坑

接下来，咱们看看 wp_json_decode()。它的任务是把 JSON 字符串转换成 PHP 的数据结构。

function wp_json_decode( $json, $assoc = false, $depth = 512, $options = 0 ) {
    /**
     * Filters the JSON-decoded value before returning.
     *
     * @since 4.4.0
     *
     * @param mixed  $decoded JSON-decoded PHP data.
     * @param string $json    The JSON string being decoded.
     * @param bool   $assoc   Whether to return objects as associative arrays.
     * @param int    $depth   User specified recursion depth.
     * @param int    $options Optional bitmask of JSON decode options.
     */
    $decoded = json_decode( $json, $assoc, $depth, $options );

    if ( JSON_ERROR_NONE !== json_last_error() ) {
        return null;
    }

    return $decoded;
}

同样，核心也是调用了 PHP 原生的 json_decode() 函数。但是，wp_json_decode() 增加了一个非常重要的错误检查：

• 错误处理： 通过 json_last_error() 函数，检查 json_decode() 是否发生了错误。如果发生了错误，就返回 null。这可以避免因为 JSON 数据不合法而导致程序崩溃。

重点：错误处理机制

json_decode() 在处理不合法的 JSON 字符串时，可能会返回 null，但不会抛出异常。这意味着，如果你不进行错误检查，你的程序可能会继续执行，但结果可能是错误的。

wp_json_decode() 通过检查 json_last_error()，可以确保你的程序能够正确地处理 JSON 解码错误。

代码示例：

<?php
$json = '{"name": "John Doe", "age": 30}';

$data = wp_json_decode( $json );

if ( $data ) {
    echo $data->name; // 输出：John Doe
} else {
    echo 'JSON 解码失败！错误代码：' . json_last_error();
}

$invalid_json = '{"name": "John Doe", "age": 30'; // 缺少一个 }

$data = wp_json_decode( $invalid_json );

if ( $data ) {
    echo $data->name;
} else {
    echo 'JSON 解码失败！错误代码：' . json_last_error(); // 输出：JSON 解码失败！错误代码：4
}
?>

在这个例子中，如果 JSON 字符串不合法，wp_json_decode() 会返回 null，并且你可以通过 json_last_error() 函数获取错误代码，方便你进行调试。

3. 编码选项和参数

wp_json_encode() 和 wp_json_decode() 都接受一些可选的参数，可以控制编码和解码的行为。

• $options：

  • wp_json_encode(): 对应 json_encode() 的 $options 参数。例如, JSON_PRETTY_PRINT 可以让输出的 JSON 字符串更易读。
  • wp_json_decode(): 对应 json_decode() 的 $options 参数。例如，JSON_BIGINT_AS_STRING 可以将大整数作为字符串返回，避免精度丢失。

• $depth： 指定最大递归深度。 如果 JSON 数据嵌套太深，可能会导致栈溢出。

• $assoc (仅 wp_json_decode()): 如果设置为 true，则将 JSON 对象解码为关联数组，而不是 PHP 对象。

代码示例：

<?php
$data = array(
    'name' => 'John Doe',
    'age'  => 30,
);

// 使用 JSON_PRETTY_PRINT 选项，让 JSON 字符串更易读
$json = wp_json_encode( $data, JSON_PRETTY_PRINT );

echo '<pre>';
echo $json;
echo '</pre>';
/*
输出:
{
    "name": "John Doe",
    "age": 30
}
*/

$json = '{"name": "John Doe", "age": 9223372036854775807}'; // 超过 PHP_INT_MAX 的整数

// 使用 JSON_BIGINT_AS_STRING 选项，将大整数作为字符串返回
$data = wp_json_decode( $json, false, 512, JSON_BIGINT_AS_STRING );

echo $data->age; // 输出：9223372036854775807 (字符串)

// 将 JSON 对象解码为关联数组
$data = wp_json_decode( $json, true );

echo $data['name']; // 输出：John Doe
?>

4. 字符编码的注意事项

虽然 wp_json_encode() 和 wp_json_decode() 能够处理 UTF-8 编码的字符串，但在实际开发中，仍然需要注意以下几点：

• 确保 PHP 文件的编码是 UTF-8： 在你的代码编辑器中，将 PHP 文件保存为 UTF-8 编码。
• 设置 HTTP 头部： 在发送 JSON 数据时，设置 Content-Type 头部为 application/json; charset=utf-8。
• 数据库连接编码： 如果你的数据来自数据库，确保数据库连接编码也是 UTF-8。
• 输入验证和转义： 在将用户输入的数据编码为 JSON 之前，进行输入验证和转义，以防止 XSS 攻击。

5. 替代方案和性能考量

虽然 wp_json_encode() 和 wp_json_decode() 已经足够好用，但在某些情况下，你可能需要考虑其他的替代方案：

• serialize() 和 unserialize()： 如果你的数据不需要与其他系统交互，可以使用 PHP 的 serialize() 和 unserialize() 函数。它们的性能通常比 json_encode() 和 json_decode() 更好，但可读性较差。
• igbinary_serialize() 和 igbinary_unserialize()： 如果你的服务器安装了 igbinary 扩展，可以使用 igbinary_serialize() 和 igbinary_unserialize() 函数。它们的性能比 serialize() 和 unserialize() 更好，但需要安装额外的扩展。

在选择替代方案时，需要权衡性能、可读性和兼容性等因素。

6. WordPress 中的应用场景

wp_json_encode() 和 wp_json_decode() 在 WordPress 中被广泛使用，例如：

• REST API： WordPress REST API 使用 JSON 作为数据交换格式。
• 主题定制器： 主题定制器使用 JSON 来存储和传输主题选项。
• 插件设置： 插件可以使用 JSON 来存储和管理插件设置。
• AJAX 请求： AJAX 请求通常使用 JSON 作为数据格式。

总结

wp_json_encode() 和 wp_json_decode() 是 WordPress 中处理 JSON 数据的两个实用函数。它们封装了 PHP 原生的 json_encode() 和 json_decode() 函数，并增加了一些额外的功能，例如错误处理和编码选项。

虽然它们看起来很简单，但它们在 WordPress 的许多核心功能中都发挥着重要的作用。

表格总结：

函数	描述	PHP 原生函数	错误处理	编码处理	常用参数	WordPress 应用场景
wp_json_encode()	将 PHP 数据编码为 JSON 字符串	json_encode()	无	假设输入数据是 UTF-8 编码	$options (例如 JSON_PRETTY_PRINT)，$depth	WordPress REST API, 主题定制器, 插件设置, AJAX 请求
wp_json_decode()	将 JSON 字符串解码为 PHP 数据	json_decode()	有	无，依赖于 json_decode 的实现	$assoc (是否返回关联数组)，$depth，$options (例如 JSON_BIGINT_AS_STRING)	WordPress REST API, 主题定制器, 插件设置, AJAX 请求
json_encode()	PHP 原生函数，将 PHP 数据编码为 JSON 字符串	无	无	需要确保数据是 UTF-8 编码，否则可能返回 false 或乱码	$value, $options, $depth	底层函数，被 wp_json_encode() 调用
json_decode()	PHP 原生函数，将 JSON 字符串解码为 PHP 数据	无	无	需要确保 JSON 字符串是有效的 UTF-8 编码	$json, $assoc, $depth, $options	底层函数，被 wp_json_decode() 调用

希望今天的讲解对大家有所帮助！ 记住，掌握这些基础的工具，才能在 WordPress 的开发道路上走得更远。 编码愉快！