PHP兼容新旧JSON处理方法详解

本文深入剖析了PHP在5.6至7.2旧版本中处理JSON时的一系列兼容性陷阱——从不可用的常量（如JSON_THROW_ON_ERROR、JSON_INVALID_UTF8_IGNORE）导致的致命错误，到json_decode返回null却无错误码、json_encode静默失败、json_last_error_msg()在7.0–7.2中不可靠等“看似成功实则丢数据”的隐蔽问题，并给出了经过实战验证的跨版本安全写法：动态判断常量可用性、强制UTF-8预处理、严格结合json_last_error()校验、封装健壮的safe_json_decode函数，以及关键接口的原始输入二进制日志策略，帮你避开那些让线上接口莫名失效、排查数小时却找不到根源的JSON暗坑。

PHP 7.3 之后 json_encode 和 json_decode 默认行为已统一，但老项目常需兼容 PHP 5.6–7.2，尤其遇到 JSON_INVALID_UTF8_IGNORE 不可用、JSON_THROW_ON_ERROR 报错、或 json_last_error_msg() 返回空字符串等问题——关键不是“能不能用”，而是“在哪种版本下必须换写法”。

PHP 5.6–7.2 中不能用的 JSON 常量

PHP 7.3+ 新增了多个错误控制常量，但在旧版本中直接使用会触发 Fatal error: Undefined class constant。最典型的是：

• JSON_THROW_ON_ERROR：7.3+ 才支持，旧版必须手动检查 json_last_error()
• JSON_INVALID_UTF8_IGNORE 和 JSON_INVALID_UTF8_SUBSTITUTE：7.2+ 引入，5.6/7.0/7.1 中传入会静默失效（不报错但也不起作用）
• JSON_UNESCAPED_UNICODE 在 5.4+ 就存在，可放心用；但 JSON_PARTIAL_OUTPUT_ON_ERROR 是 7.0+ 才有

实操建议：用 defined('JSON_THROW_ON_ERROR') 判断是否可用，否则 fallback 到传统错误检查流程。

json_decode 兼容写法：避免 null 却不报错

旧版 PHP 中，json_decode($str) 对非法 JSON（如含 BOM、控制字符、不合法 UTF-8）常返回 null，但 json_last_error() 可能是 JSON_ERROR_NONE，导致误判成功。常见于读取前端传来的带 emoji 或剪贴板粘贴内容。

• 始终传入第二个参数 true（避免返回 stdClass，统一为数组便于后续处理）
• 不要只判断返回值是否为 null，必须搭配 json_last_error() !== JSON_ERROR_NONE
• 对不确定来源的字符串，先用 mb_convert_encoding($str, 'UTF-8', 'UTF-8') 清理 BOM 和编码残留

示例：

function safe_json_decode($str) {
    if (!is_string($str) || $str === '') return null;
    $str = trim($str);
    if (defined('JSON_THROW_ON_ERROR')) {
        try {
            return json_decode($str, true, 512, JSON_THROW_ON_ERROR);
        } catch (\JsonException $e) {
            return null;
        }
    }
    $result = json_decode($str, true);
    return (json_last_error() === JSON_ERROR_NONE) ? $result : null;
}

json_encode 兼容 UTF-8 处理：避免乱码和 false

旧版 PHP（尤其是 5.6）对非 UTF-8 字符串调用 json_encode 会直接返回 false，且 json_last_error() 返回 JSON_ERROR_UTF8。但很多开发者只检查返回值，没查错误码，导致接口静默失败。

• 入库/接收数据时，用 mb_check_encoding($data, 'UTF-8') 预检，不通过则用 mb_convert_encoding($data, 'UTF-8', 'GB2312,GBK,BIG5') 尝试转码
• 避免对未过滤的 $_GET/$_POST 直接 json_encode，特别是中文 Windows 客户端可能提交 GBK 编码
• PHP 5.6 默认开启 detect_unicode = On，可能干扰 JSON 处理，可在 php.ini 中设为 Off（仅限 CLI 或明确控制环境时）

跨版本 JSON 错误调试：别信 json_last_error_msg() 的返回值

PHP 7.0–7.2 中，json_last_error_msg() 在某些错误场景下（如输入为空、内存不足）返回空字符串或 “No Error”，而非真实错误描述，极易误导排查方向。

• 优先用 json_last_error() 的整型码比对，例如：JSON_ERROR_DEPTH（1）、JSON_ERROR_UTF8（5）
• 在开发环境加一层封装，把错误码映射为可读字符串（不必依赖 json_last_error_msg）
• 对关键 JSON 接口，记录原始输入 + bin2hex(substr($input, 0, 32))，方便定位不可见字符问题

真正麻烦的不是语法错，而是那些看似成功、实则丢数据的“半截 JSON”——比如前端传了 2MB 字符串，而 post_max_size 设为 8M，但实际因 Nginx client_max_body_size 限制被截断，PHP 收到的就是不完整 JSON，json_decode 返回 null，错误码却是 JSON_ERROR_SYNTAX。

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