WordPress插件开发：存储自定义数组时出现额外空键层级问题

问题场景 #

开发WordPress插件时，通过后台表单添加自定义文章类型（Custom Post Types），使用以下代码处理用户输入：

public function cptSanitize( $input ) {  

    $output = array();
    
    // 调试输出（移除后出现存储异常）
    // var_dump($input);
    $output[$input['post_type']] = $input;
    // var_dump($output); 
    // var_dump(serialize($output)); die();
    return $output;
}

调试时var_dump的输出符合预期：

• 输入数组：

array(5) { 
    ["post_type"]=> string(11) "comic-books" 
    ["singular_name"]=> string(10) "Comic book" 
    ["plural_name"]=> string(11) "Comic books" 
    ["public"]=> string(1) "1" 
    ["has_archive"]=> string(1) "1" 
}

• 处理后的输出数组：

array(1) { 
    ["comic-books"]=> array(5) { 
        ["post_type"]=> string(11) "comic-books" 
        ["singular_name"]=> string(10) "Comic book" 
        ["plural_name"]=> string(11) "Comic books" 
        ["public"]=> string(1) "1" 
        ["has_archive"]=> string(1) "1" 
    } 
}

• 序列化结果：

"a:1:{
    s:11:\"comic-books\";
    a:5:{
        s:9:\"post_type\";s:11:\"comic-books\";
        s:13:\"singular_name\";s:10:\"Comic book\";
        s:11:\"plural_name\";s:11:\"Comic books\";
        s:6:\"public\";s:1:\"1\";
        s:11:\"has_archive\";s:1:\"1\";
    }
}"

但移除调试代码后，数据存入wp_options表时多了一层空键的嵌套，序列化内容变为：

a:1:{
    s:0:\"\";
    a:1:{
        s:11:\"comic-books\";
        a:5:{
            s:9:\"post_type\";s:11:\"comic-books\";
            s:13:\"singular_name\";s:10:\"Comic book\";
            s:11:\"plural_name\";s:11:\"Comic books\";
            s:6:\"public\";s:1:\"1\";
            s:11:\"has_archive\";s:1:\"1\";
        }
    }
}

补充现象：仅当wp_options表中无对应选项时出现该问题；若选项已存在（哪怕是空数组a:0:{}），数据存储完全符合预期。

原因分析 #

这是WordPress设置API的默认行为导致的：

• 当目标选项不存在时，WordPress会使用默认值（默认是false）来合并处理sanitize函数返回的值。由于false不是数组，WP会将返回的数组当作单个元素，自动包裹到一个空键的数组中。
• 当选项已存在（哪怕是空数组），WordPress会直接用sanitize后的数组覆盖原有值，不会触发额外的包裹逻辑。

解决方法 #

最稳妥的方案是在注册设置时，明确指定选项的默认值为空数组：

register_setting(
    'your_settings_group', // 替换为你的设置组名称
    'your_option_name',    // 替换为你的选项名称
    array(
        'sanitize_callback' => array( $this, 'cptSanitize' ),
        'default'           => array(), // 指定默认值为空数组
    )
);

设置默认值为空数组后，即使选项不存在，WordPress也会将sanitize返回的数组直接作为选项值存储，不会额外添加空键的嵌套层级。

内容的提问来源于stack exchange，提问作者Luigi Caradonna