PHP中json_encode用法详解

`json_encode`是PHP中用于将PHP数组或对象转换为JSON字符串的关键函数，在前后端数据交互中扮演着重要角色。本文深入解析`json_encode`的用法，重点介绍如何通过`JSON_UNESCAPED_UNICODE`选项避免中文转义，以及利用`JSON_PRETTY_PRINT`选项格式化JSON输出，提升可读性。同时，详细阐述了`json_encode`在处理资源类型、循环引用、不可序列化对象及`NaN`/`Infinity`等特殊值时可能遇到的问题，并提供相应的解决方案。通过掌握`json_last_error()`等错误排查函数，开发者能够更高效地使用`json_encode`，确保数据转换的准确性和可靠性。

json_encode用于将PHP数组或对象转换为JSON字符串，支持通过JSON_UNESCAPED_UNICODE和JSON_PRETTY_PRINT等选项处理中文转义和格式化输出，需注意资源类型、循环引用、不可序列化对象及NaN/Infinity等特殊值会导致编码失败，可借助json_last_error()排查问题。

json_encode 在 PHP 里，简单来说就是把 PHP 的数据结构（比如数组、对象）转换成 JSON 格式的字符串。这个函数在前后端数据交互时简直是标配，因为它能把复杂的数据打包成一种通用的文本格式，让JavaScript或者其他语言也能轻松理解和解析。它的核心作用就是序列化，把内存中的数据结构“拍扁”成一段文本，方便传输和存储。

解决方案

json_encode 的基本用法其实非常直观：你只需要把你想要转换的 PHP 变量作为第一个参数传进去就行。它会尝试把这个变量转换成 JSON 字符串。

<?php
$data = [
    'name' => '张三',
    'age' => 30,
    'isStudent' => false,
    'courses' => ['PHP', 'JavaScript', 'SQL'],
    'address' => null
];

$jsonString = json_encode($data);
echo $jsonString;
// 输出: {"name":"\u5f20\u4e09","age":30,"isStudent":false,"courses":["PHP","JavaScript","SQL"],"address":null}
?>

你会发现上面的中文“张三”被转义了，这是 json_encode 的默认行为。但实际使用中，我们往往需要对输出格式做一些精细的控制，这就要用到它的第二个参数 $options。这是一个位掩码参数，可以通过组合不同的常量来改变 json_encode 的行为。

比如，如果你想让中文不被转义，或者让输出的 JSON 字符串更易读，就得加上相应的选项：

<?php
$data = [
    'name' => '李四',
    'age' => 25,
    'city' => '北京'
];

// 中文不转义，并且格式化输出
$jsonStringPretty = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
echo $jsonStringPretty;
/*
输出:
{
    "name": "李四",
    "age": 25,
    "city": "北京"
}
*/
?>

这里 JSON_UNESCAPED_UNICODE 确保了中文字符不会被编码成 \uXXXX 形式，而 JSON_PRETTY_PRINT 则让 JSON 字符串带有缩进和换行，方便阅读和调试。这两个选项在日常开发中非常常用，几乎是标配。

json_encode 转换时遇到中文乱码或转义字符怎么办？

这个问题简直是 json_encode 初学者最常遇到的“拦路虎”了。我记得自己刚开始用的时候，看到输出里一堆 \uXXXX 就头大，总觉得是哪里编码出了问题。其实，这并非乱码，而是 json_encode 的一种默认行为：它会把所有非 ASCII 字符（包括中文、日文、韩文等）都转义成 Unicode 编码形式。这样做是为了确保 JSON 字符串在任何环境下都能被正确解析，因为它只承诺支持 ASCII 字符集。

但对于我们中文开发者来说，这种转义在很多场景下显得多余，甚至会增加调试的难度。解决办法非常简单，只需要在调用 json_encode 时，给第二个参数 $options 加上 JSON_UNESCAPED_UNICODE 这个常量。

<?php
$item = [
    'product_name' => '新款智能手机',
    'price' => 2999.00,
    'description' => '一款功能强大的旗舰手机。'
];

echo "--- 默认转义效果 ---\n";
echo json_encode($item);
// 输出: {"product_name":"\u65b0\u6b3e\u667a\u80fd\u624b\u673a","price":2999,"description":"\u4e00\u6b3e\u529f\u80fd\u5f3a\u5927\u7684\u65d7\u8230\u624b\u673a\u3002"}

echo "\n\n--- 使用 JSON_UNESCAPED_UNICODE ---\n";
echo json_encode($item, JSON_UNESCAPED_UNICODE);
// 输出: {"product_name":"新款智能手机","price":2999,"description":"一款功能强大的旗舰手机。"}
?>

通过对比你会发现，加上 JSON_UNESCAPED_UNICODE 后，中文就能直接显示，不再是那些难以阅读的编码了。这是一个非常实用的技巧，几乎成了处理中文 JSON 数据的标准做法。当然，也要确保你的 PHP 脚本文件本身是 UTF-8 编码，并且 HTTP 响应头也正确设置了 Content-Type: application/json; charset=utf-8，这样才能保证从头到尾的编码一致性。

如何让 json_encode 输出的 JSON 字符串更易读，方便调试？

默认情况下，json_encode 输出的 JSON 字符串是一行紧凑的文本，没有任何缩进或换行。这对于机器解析来说效率很高，因为它节省了带宽和存储空间。但对于我们人类开发者来说，当 JSON 数据结构稍微复杂一点，或者需要排查问题时，这种紧凑的格式简直是噩梦。密密麻麻的一长串字符，想要一眼看出层级关系或者某个字段的值，几乎是不可能完成的任务。

为了解决这个问题，json_encode 提供了一个非常贴心的选项：JSON_PRETTY_PRINT。正如其名，它会让输出的 JSON 字符串“漂亮”起来，自动添加缩进和换行，使其结构清晰，层次分明。

<?php
$userProfile = [
    'id' => 1001,
    'username' => 'dev_user',
    'email' => 'dev@example.com',
    'settings' => [
        'theme' => 'dark',
        'notifications' => [
            'email' => true,
            'sms' => false,
            'push' => true
        ],
        'language' => 'zh-CN'
    ],
    'last_login' => '2023-10-27 10:30:00'
];

echo "--- 默认紧凑输出 ---\n";
echo json_encode($userProfile);

echo "\n\n--- 使用 JSON_PRETTY_PRINT 格式化输出 ---\n";
echo json_encode($userProfile, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
?>

当你运行上面的代码，你会明显感受到 JSON_PRETTY_PRINT 带来的便利。特别是当数据层级较深时，格式化后的输出能让你一眼就能理解数据的结构，快速定位到需要检查的部分。我个人在开发和调试阶段，几乎都会把这个选项加上，它能节省大量的时间和精力。当然，在生产环境中，为了追求性能和带宽，通常会移除这个选项，让 JSON 保持紧凑。

json_encode 无法转换某些数据类型或返回 null 是什么原因？

json_encode 虽然强大，但它并不是万能的，有些 PHP 数据类型它是处理不了的。当你发现 json_encode 返回 null 或者输出的 JSON 字符串不符合预期时，通常是遇到了它无法处理的数据类型或者一些特殊情况。这可不是函数出了 bug，而是它有自己的“规矩”。

几个常见的原因和解决方案：

1. 资源类型 (Resource Types) PHP 中的资源类型，比如数据库连接句柄 (mysqli_result 对象、PDO 对象)、文件句柄 (resource(stream)) 等，是无法直接被 json_encode 转换的。这些是 PHP 内部的特殊指针，不是可序列化的数据。

   • 处理方式： 在编码前，你需要手动提取资源中的有用数据（例如，从数据库结果集中获取行数据），将它们转换为数组或对象，再进行编码。

   <?php
   // 假设 $fileHandle 是一个文件资源
   $fileHandle = fopen('test.txt', 'r');
   $data = ['name' => 'test', 'handle' => $fileHandle];
   $json = json_encode($data);
   echo $json; // {"name":"test","handle":{}} 或直接返回null
   fclose($fileHandle); // 记得关闭资源
   
   // 正确的做法是提取数据
   $fileContent = file_get_contents('test.txt');
   $data = ['name' => 'test', 'content' => $fileContent];
   $json = json_encode($data);
   echo $json; // {"name":"test","content":"文件内容..."}
   ?>

2. 包含循环引用的对象 (Circular References) 如果你的对象中存在循环引用（例如，对象 A 引用对象 B，同时对象 B 又引用对象 A），json_encode 可能会陷入无限循环，最终导致失败并返回 null。

   • 处理方式： 避免在需要 JSON 化的对象中创建循环引用，或者在编码前手动处理这些引用，将其断开或替换为 ID。

3. 不可序列化的对象 (Non-Serializable Objects) 默认情况下，json_encode 只能序列化对象的公共属性。如果一个对象包含私有或保护属性，或者它本身不适合直接转换为 JSON（例如，一个复杂的业务逻辑对象），它可能无法被正确编码。

   • 处理方式： 让你的对象实现 JsonSerializable 接口。这个接口只有一个方法 jsonSerialize()，你可以在这个方法中定义对象被 json_encode 时应该返回的数据结构。

   <?php
   class MyUser implements JsonSerializable {
       private $id;
       public $name;
       protected $passwordHash; // 不想被序列化
   
       public function __construct($id, $name, $passwordHash) {
           $this->id = $id;
           $this->name = $name;
           $this->passwordHash = $passwordHash;
       }
   
       public function jsonSerialize(): mixed {
           // 只暴露 id 和 name，不暴露 passwordHash
           return [
               'user_id' => $this->id,
               'user_name' => $this->name
           ];
       }
   }
   
   $user = new MyUser(1, 'Alice', 'hashed_pass');
   echo json_encode($user, JSON_PRETTY_PRINT);
   /*
   输出:
   {
       "user_id": 1,
       "user_name": "Alice"
   }
   */
   ?>

4. NaN (Not a Number) 或 Infinity JSON 标准中并没有定义 NaN 和 Infinity 这些浮点数值。如果你的 PHP 数组或对象中包含了 NAN 或 INF 值，json_encode 也会返回 null。

   • 处理方式： 在编码前检查并过滤掉这些特殊浮点数，或者将其转换为 null 或其他 JSON 支持的值。

5. 编码错误检查 当你遇到 json_encode 返回 null 但又不知道具体原因时，json_last_error() 和 json_last_error_msg() 这两个函数是你的救星。它们能告诉你上次 json_encode (或 json_decode) 操作失败的具体原因。

   <?php
   $invalidData = [
       'value' => NAN // 包含 NaN
   ];
   
   $json = json_encode($invalidData);
   if ($json === false) { // 或者直接检查 $json === null
       echo "JSON 编码失败！错误代码：" . json_last_error() . "\n";
       echo "错误信息：" . json_last_error_msg() . "\n";
   } else {
       echo $json;
   }
   // 输出:
   // JSON 编码失败！错误代码：5
   // 错误信息：Malformed UTF-8 characters, possibly incorrectly encoded
   // (在 PHP 7.1+，对 NaN/INF 会返回 JSON_ERROR_INF_OR_NAN)
   ?>

   通过这些错误信息，你就能更精确地定位到问题所在，从而采取相应的处理措施。在实际开发中，养成检查 json_last_error() 的习惯，能帮你省去不少调试的麻烦。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~