详解 WordPress `wp_json_encode()` 和 `wp_json_decode()` 函数源码：JSON 数据处理与安全。

各位老铁，早上好！我是老码农，今天咱们唠唠 WordPress 里 JSON 相关的两大法宝：wp_json_encode() 和 wp_json_decode()。 这俩家伙，一个负责把 PHP 的数据结构变成 JSON 字符串，另一个负责把 JSON 字符串还原成 PHP 的数据结构。 听起来挺简单，但 WordPress 为了安全和兼容性，在背后做了不少功夫。 咱们今天就来扒一扒它们的源码，看看里面藏着哪些玄机。

开场白：JSON，数据界的通用语

在 Web 开发的世界里，JSON 就像是不同语言之间的翻译官。 客户端（比如 JavaScript）和服务器端（比如 PHP）经常需要交换数据。 JSON 这种轻量级的数据格式，简单易懂，成了它们交流的通用语。

第一节：wp_json_encode()：PHP 数据的华丽变身

wp_json_encode()，顾名思义，就是把 PHP 的数组、对象等数据结构，转换成 JSON 格式的字符串。 它的基本用法跟 PHP 内置的 json_encode() 函数类似，但 WordPress 版本做了增强。

1.1 基本用法

<?php
$data = array(
  'name' => '老码农',
  'age' => 30,
  'skills' => array('PHP', 'JavaScript', 'WordPress')
);

$json_string = wp_json_encode($data);

echo $json_string;
// 输出：{"name":"老码农","age":30,"skills":["PHP","JavaScript","WordPress"]}
?>

是不是很简单？ 把一个 PHP 数组变成了 JSON 字符串。

1.2 源码剖析：WordPress 的小心思

别以为 wp_json_encode() 只是简单地调用了 json_encode()。 WordPress 在它的基础上，做了不少优化和安全处理。

源码大致如下（为了方便阅读，我做了简化）：

function wp_json_encode( $data, $options = 0, $depth = 512 ) {
  /**
   * Filter the JSON encoding options.
   *
   * @since 4.4.0
   *
   * @param int   $options The JSON encoding options to use.
   * @param mixed $data    The data to encode.
   * @param int   $depth   The maximum depth.
   */
  $options = apply_filters( 'wp_json_encode_options', $options, $data, $depth );

  $json = json_encode( $data, $options, $depth );

  // If json_encode() fails, fall back to the native JSON encode.
  if ( false === $json ) {
    //... 兼容旧版本PHP的方案，这里省略 ...
  }

  /**
   * Filter the JSON encoded string.
   *
   * @since 4.4.0
   *
   * @param string $json  The JSON encoded string.
   * @param mixed  $data  The original value.
   * @param int    $options The JSON encoding options used.
   * @param int    $depth   The maximum depth.
   */
  return apply_filters( 'wp_json_encoded', $json, $data, $options, $depth );
}

看到了吗？ WordPress 通过 apply_filters() 函数，提供了两个钩子：

• wp_json_encode_options: 允许你修改 JSON 编码的选项。 比如，你可以设置 JSON_PRETTY_PRINT 让 JSON 字符串更易读。
• wp_json_encoded: 允许你修改最终的 JSON 字符串。

这两个钩子，给了开发者很大的灵活性。

1.3 常用选项

wp_json_encode() 的第二个参数 $options，可以控制 JSON 编码的行为。 常见的选项有：

选项	含义
JSON_PRETTY_PRINT	让 JSON 字符串更易读，添加缩进和换行。 适合调试和查看。
JSON_UNESCAPED_UNICODE	不转义 Unicode 字符。 默认情况下，中文、日文等字符会被转义成 uXXXX 的形式。 使用这个选项，可以保持原样。
JSON_UNESCAPED_SLASHES	不转义斜杠 /。 默认情况下，斜杠会被转义成 /。
JSON_NUMERIC_CHECK	检查数字类型的字符串。 如果字符串可以被解析成数字，就转换成数字类型。 比如， "123" 会变成 123。

例子：

<?php
$data = array(
  'message' => '你好，世界！',
  'url' => 'https://example.com/path'
);

$json_string = wp_json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

echo $json_string;
/*
输出：
{
    "message": "你好，世界！",
    "url": "https://example.com/path"
}
*/
?>

1.4 安全性考量

wp_json_encode() 本身并没有直接的安全漏洞。 但在使用它的时候，需要注意以下几点：

• 避免敏感信息泄露: 不要把密码、密钥等敏感信息放到 JSON 数据里。
• 防止 XSS 攻击: 如果 JSON 数据会被输出到 HTML 页面，需要对数据进行转义，防止 XSS 攻击。 WordPress 提供了 esc_attr()、esc_html() 等函数来转义数据。

第二节：wp_json_decode()：JSON 字符串的还原术

wp_json_decode() 的作用正好相反，它是把 JSON 格式的字符串，转换成 PHP 的数组或对象。

2.1 基本用法

<?php
$json_string = '{"name":"老码农","age":30,"skills":["PHP","JavaScript","WordPress"]}';

$data = wp_json_decode($json_string);

var_dump($data);
/*
输出：
object(stdClass)#1 (3) {
  ["name"] => string(9) "老码农"
  ["age"] => int(30)
  ["skills"] => array(3) {
    [0] => string(3) "PHP"
    [1] => string(10) "JavaScript"
    [2] => string(9) "WordPress"
  }
}
*/
?>

默认情况下，wp_json_decode() 会把 JSON 数据转换成 PHP 的 stdClass 对象。

2.2 转换为数组

如果你想把 JSON 数据转换成数组，可以给 wp_json_decode() 传递第二个参数 true：

<?php
$json_string = '{"name":"老码农","age":30,"skills":["PHP","JavaScript","WordPress"]}';

$data = wp_json_decode($json_string, true);

var_dump($data);
/*
输出：
array(3) {
  ["name"] => string(9) "老码农"
  ["age"] => int(30)
  ["skills"] => array(3) {
    [0] => string(3) "PHP"
    [1] => string(10) "JavaScript"
    [2] => string(9) "WordPress"
    }
}
*/
?>

2.3 源码剖析：错误处理与兼容性

wp_json_decode() 的源码也值得一看：

function wp_json_decode( $json, $assoc = false, $depth = 512, $options = 0 ) {
  // Handle empty string.
  if ( empty( $json ) ) {
    return null;
  }

  /**
   * Filter the JSON decoding options.
   *
   * @since 5.5.0
   *
   * @param int    $options The JSON decoding options to use.
   * @param string $json    The JSON string to decode.
   * @param bool   $assoc   Whether to return objects as associative arrays.
   * @param int    $depth   The maximum depth.
   */
  $options = apply_filters( 'wp_json_decode_options', $options, $json, $assoc, $depth );

  $decoded = json_decode( $json, $assoc, $depth, $options );

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

  return $decoded;
}

关键点：

• 空字符串处理: 如果传入的 JSON 字符串为空，wp_json_decode() 会直接返回 null。
• 错误处理: json_decode() 函数可能会出错。 wp_json_decode() 会检查 json_last_error() 的返回值，如果出错，也会返回 null。
• 钩子: WordPress 同样提供了 wp_json_decode_options 钩子，允许修改 JSON 解码的选项。

2.4 安全性考量

wp_json_decode() 的安全性主要体现在以下几个方面：

• 防止代码注入: 如果 JSON 数据中包含恶意代码，wp_json_decode() 可能会执行这些代码。 因此，要确保 JSON 数据的来源可靠。
• 防止拒绝服务攻击: 如果 JSON 数据非常大，wp_json_decode() 可能会消耗大量的内存和 CPU 资源，导致拒绝服务攻击。 可以通过限制 JSON 数据的大小来防止这种攻击。

第三节：实战演练：WordPress REST API 中的 JSON

WordPress REST API 大量使用了 JSON 格式。 无论是请求数据，还是返回数据，都离不开 wp_json_encode() 和 wp_json_decode()。

3.1 请求数据

假设你要使用 REST API 创建一篇新的文章。 你需要构造一个包含文章标题、内容等信息的 JSON 字符串，然后发送给服务器。

<?php
$data = array(
  'title' => '我的第一篇文章',
  'content' => '这是文章的内容。',
  'status' => 'publish'
);

$json_string = wp_json_encode($data);

// 使用 WordPress 的 HTTP API 发送请求
$response = wp_remote_post(
  'https://example.com/wp-json/wp/v2/posts',
  array(
    'headers' => array(
      'Content-Type' => 'application/json',
      'Authorization' => 'Basic ' . base64_encode('username:password')  // 替换为你的用户名和密码
    ),
    'body' => $json_string
  )
);

if ( is_wp_error( $response ) ) {
  echo 'Error: ' . $response->get_error_message();
} else {
  echo 'Status code: ' . wp_remote_retrieve_response_code( $response ) . "n";
  echo 'Response body: ' . wp_remote_retrieve_body( $response );
}
?>

3.2 响应数据

服务器返回的响应数据，通常也是 JSON 格式的。 你需要使用 wp_json_decode() 把 JSON 字符串转换成 PHP 的数据结构，然后进行处理。

<?php
// 假设 $response_body 是服务器返回的 JSON 字符串
$response_body = '{"id":123,"title":"我的第一篇文章","content":"这是文章的内容。","status":"publish"}';

$data = wp_json_decode($response_body);

if ( $data ) {
  echo '文章 ID: ' . $data->id . "n";
  echo '文章标题: ' . $data->title . "n";
} else {
  echo 'Failed to decode JSON.';
}
?>

第四节：最佳实践：JSON 数据处理的正确姿势

• 数据验证: 在使用 wp_json_decode() 之前，务必对 JSON 字符串进行验证，确保它是合法的 JSON 格式。 可以使用 json_validate() 函数（需要 PHP 5.5+）或者第三方库。
• 错误处理: wp_json_decode() 在解析失败时会返回 null。 在使用解析结果之前，一定要检查返回值是否为 null。
• 数据过滤: 对于从外部获取的 JSON 数据，一定要进行过滤和转义，防止 XSS 攻击。
• 性能优化: 如果需要处理大量的 JSON 数据，可以考虑使用流式解析器，减少内存占用。

第五节：总结：wp_json_encode() 和 wp_json_decode() 的价值

wp_json_encode() 和 wp_json_decode() 不仅仅是简单的 JSON 编码和解码函数。 它们是 WordPress 为了安全、兼容性和灵活性而精心设计的工具。 通过钩子，开发者可以自定义 JSON 编码和解码的行为。 通过错误处理和数据验证，可以提高应用程序的安全性。 掌握这两个函数，对于开发 WordPress 主题和插件，以及使用 WordPress REST API，都非常有帮助。

结束语

好了，今天的讲座就到这里。 希望大家对 wp_json_encode() 和 wp_json_decode() 有了更深入的了解。 记住，代码的世界里，细节决定成败。 掌握好这些细节，才能写出高质量的代码。 祝大家编程愉快！ 咱们下期再见！