概述

wp_json_file_decode() 是 WordPress 5.9.0 引入的函数，用于读取并解码 JSON 文件。它处理文件路径验证、错误触发，并返回解码后的 PHP 数据类型。

关键要点

• 函数接受两个参数：$filename（必需，JSON 文件路径）和 $options（可选，用于 json_decode() 的选项）。
• 默认情况下，JSON 对象返回为对象；通过设置 $options['associative'] 为 true 可返回关联数组。
• 如果文件不存在或解码失败，函数返回 null 并触发错误消息。
• 内部使用 wp_normalize_path()、wp_trigger_error() 和 wp_parse_args() 等辅助函数。
• 在 WordPress 核心中用于处理字体集合、主题 JSON 和块元数据等场景。

代码示例

function wp_json_file_decode( $filename, $options = array() ) {
    $result   = null;
    $filename = wp_normalize_path( realpath( $filename ) );

    if ( ! $filename ) {
        wp_trigger_error(
            __FUNCTION__,
            sprintf(
                /* translators: %s: Path to the JSON file. */
                __( "File %s doesn't exist!" ),
                $filename
            )
        );
        return $result;
    }

    $options      = wp_parse_args( $options, array( 'associative' => false ) );
    $decoded_file = json_decode( file_get_contents( $filename ), $options['associative'] );

    if ( JSON_ERROR_NONE !== json_last_error() ) {
        wp_trigger_error(
            __FUNCTION__,
            sprintf(
                /* translators: 1: Path to the JSON file, 2: Error message. */
                __( 'Error when decoding a JSON file at path %1$s: %2$s' ),
                $filename,
                json_last_error_msg()
            )
        );
        return $result;
    }

    return $decoded_file;
}

注意事项

• 确保提供的文件路径有效且可读，否则函数会触发错误并返回 null。
• 使用 $options 参数可以控制解码行为，例如返回关联数组而非对象。
• 函数依赖于 PHP 的 json_decode()，因此需确保 JSON 格式正确以避免解码错误。