WordPress插件中实现同一设置项保存多个值的方法

1. 理解WordPress设置API的默认行为

wordpress的设置api（settings api）是插件和主题管理选项的强大工具。通过register_setting、add_settings_section和add_settings_field等函数，开发者可以轻松地创建自定义设置页面和字段。然而，其默认设计通常倾向于为每个设置字段保存一个单一值。例如，如果有一个名为cat_slug的设置项，每次保存时，新值会覆盖旧值。

当需求是为同一个设置项（如cat_slug）保存多个独立的分类目录别名或相关联的数据（如多个折扣配置）时，就需要采用一种特殊的处理方式来突破这种单一值的限制。

2. 实现多值保存的核心策略：数组字段命名

要让WordPress设置API能够保存一个设置项的多个值，关键在于修改HTML输入字段的name属性。通过在字段名后添加[]，可以指示PHP将提交的数据作为数组处理。

假设我们有一个设置项名为slug-configuration，其中包含一个子键cat_slug。为了让cat_slug能够存储多个值，我们需要将输入字段的name属性从slug-configuration[cat_slug]修改为slug-configuration[cat_slug][]。

以下是修改后的cat_slug_render函数示例：

function cat_slug_render() {
    // 获取当前保存的选项，如果不存在则默认为空数组
    $options = get_option( 'slug-configuration', array() );

    // 从多值数组中选择一个值作为输入框的默认显示值
    // 这里选择第一个值，如果数组为空则显示空字符串
    $current_value = $options['cat_slug'][0] ?? '';
    ?>
    <input type='text' size="50" name='slug-configuration[cat_slug][]' value='<?php echo esc_html( $current_value ); ?>'>
    <?php
}

关键点说明：

• name='slug-configuration[cat_slug][]'：这是实现多值保存的核心。当表单提交时，PHP会自动将所有同名（slug-configuration[cat_slug][]）的输入字段值收集到一个数组中，并将其作为cat_slug键的值保存。
• get_option( 'slug-configuration', array() )：始终为get_option提供一个默认值（这里是空数组），以防止在选项尚未保存时出现PHP通知或错误。

3. 处理输入字段的默认显示值

当一个设置项保存了多个值时，在一个单行的文本输入框中如何显示这些值是一个设计选择。通常，我们会选择显示其中一个值（例如，第一个或最后一个），或者不显示任何值，让用户每次都输入新值。

• 显示第一个保存的值：

  function cat_slug_render_first_value() {
      $options = get_option( 'slug-configuration', array() );
      // 使用空合并运算符 (??) 确保在 'cat_slug' 或其索引 0 不存在时返回空字符串
      $current_value = $options['cat_slug'][0] ?? '';
      ?>
      <input type='text' size="50" name='slug-configuration[cat_slug][]' value='<?php echo esc_html( $current_value ); ?>'>
      <?php
  }

  登录后复制

• 显示最后一个保存的值： 如果希望显示最近添加的值，可以使用array_key_last()函数（PHP 7.3+）来获取数组的最后一个键。

  function cat_slug_render_last_value() {
      $options = get_option( 'slug-configuration', array() );
      $last_key = array_key_last( $options['cat_slug'] ?? [] ); // 获取 'cat_slug' 数组的最后一个键
      $current_value = $options['cat_slug'][$last_key] ?? '';
      ?>
      <input type='text' size="50" name='slug-configuration[cat_slug][]' value='<?php echo esc_html( $current_value ); ?>'>
      <?php
  }

  登录后复制

注意事项：

讯飞公文

讯飞公文写作助手是一款依托于讯飞星火大模型、专为广大公文材料撰稿人打造的高效公文写作平台。

167

查看详情

• 用户体验： 如果目标是让用户每次都添加一个新记录，那么输入框可以留空。如果用户需要编辑现有记录，则可能需要更复杂的UI（例如，一个列表，每个项目旁边有编辑/删除按钮）。
• 安全性： esc_html()函数用于确保输出到HTML属性中的数据是安全的，防止跨站脚本（XSS）攻击。??（空合并运算符）用于优雅地处理数组键可能不存在的情况，避免PHP通知或错误。

4. 数据保存与清洗（Sanitization）

当设置项接收数组形式的数据时，对应的清洗函数（Sanitization Callback）也需要进行相应的调整，以确保每个数组元素都被正确地清洗。

例如，如果您的设置项slug-configuration注册时指定了一个清洗函数：

register_setting(
    'slug-configuration', // option group
    'slug-configuration', // option name
    'slug_configuration_sanitize_callback' // sanitize callback
);

那么slug_configuration_sanitize_callback函数需要能够处理传入的数组：

function slug_configuration_sanitize_callback( $input ) {
    $new_input = array();
    if ( isset( $input['cat_slug'] ) && is_array( $input['cat_slug'] ) ) {
        $new_input['cat_slug'] = array_map( 'sanitize_text_field', $input['cat_slug'] );
        // 过滤掉空值，如果需要
        $new_input['cat_slug'] = array_filter( $new_input['cat_slug'] );
    }
    // 处理其他设置项...
    return $new_input;
}

在这个清洗函数中，array_map('sanitize_text_field', ...)用于对cat_slug数组中的每个元素应用sanitize_text_field函数，确保所有输入的文本都是安全的。

5. 检索和使用多值数据

一旦多值数据被保存，就可以像访问普通数组一样检索和遍历它们。

// 获取保存的选项
$options = get_option( 'slug-configuration', array() );

// 确保 'cat_slug' 键存在且是一个数组，否则默认为空数组
$cat_slugs = $options['cat_slug'] ?? array();

// 遍历并使用每个分类别名
if ( ! empty( $cat_slugs ) ) {
    echo '<ul>';
    foreach ( $cat_slugs as $slug ) {
        echo '<li>' . esc_html( $slug ) . '</li>';
        // 在这里可以对 $slug 进行进一步处理，例如查询对应的分类或应用折扣
    }
    echo '</ul>';
} else {
    echo '<p>暂无保存的分类别名。</p>';
}

6. 高级考量与最佳实践

• 用户界面（UI）增强： 对于多值输入，单个文本框通常不足以提供良好的用户体验。考虑使用JavaScript动态添加/删除输入字段，以允许用户方便地管理多个值。
• 数据结构设计： 如果需要保存相关联的多个数据（例如，分类别名和对应的折扣百分比），简单的索引数组可能不够。在这种情况下，可以考虑保存一个由关联数组组成的数组，例如：

  // HTML 输入字段示例 (使用索引以保持数据关联)
  // <input type='text' name='slug-configuration[discounts][0][cat_slug]' value='...' />
  // <input type='text' name='slug-configuration[discounts][0][discount_percentage]' value='...' />
  // <input type='text' name='slug-configuration[discounts][1][cat_slug]' value='...' />
  // <input type='text' name='slug-configuration[discounts][1][discount_percentage]' value='...' />

  登录后复制

  相应的，清洗函数和数据检索逻辑也需要调整以处理这种更复杂的数据结构。

• 性能： 如果需要保存大量数据，get_option可能会加载整个选项数组。对于非常大的数据集，可能需要考虑将数据存储在自定义数据库表中。

总结

通过在HTML输入字段的name属性中使用[]，WordPress插件可以轻松地为单个设置项保存和管理多个值。这种方法在需要灵活配置列表项（如多个分类别名、多个API密钥等）时非常有用。在实现过程中，务必注意数据的清洗、安全性（esc_html()）以及用户体验，并根据实际需求考虑更复杂的数据结构和UI交互。

以上就是WordPress插件中实现同一设置项保存多个值的方法的详细内容，更多请关注php中文网其它相关文章！