README

安装

在您的 composer.json 中使用 marspress/wp-options 包含最小 dev-main 或者运行 composer require marspress/wp-options

WP 选项

选项通常位于 wp-admin 中的设置菜单下。

资源

https://developer.wordpress.org/reference/functions/register_setting/

使用

new \MarsPress\Options\Settings\Option_Group() 需要 1 个必填参数。

键（必填）（字符串）
- 选项组的唯一键。
- 如果选项键已被使用，则选项组将不会被注册，并且将在 wp-admin 中显示管理通知。

可用方法

add_options 可以接受任意数量的参数，只要它们是 \MarsPress\Options\Settings\Option 类型。
- 返回 self：$this。
get_option_value() 需要 2 个参数，1 个必填和 1 个可选。
- 选项名称（必填）（字符串）
  - 要返回值的选项名称。
  - 如果选项值不存在于数据库中，该方法将返回 null。
  - 如果选项对象有一个返回回调，该方法将返回返回回调的返回值。
- 返回原始值（可选）（布尔值）
  - 是否跳过选项的返回回调。
  - 默认为 false。

new \MarsPress\Options\Settings\Option 需要 8 个参数，3 个必填和 5 个可选。

名称（必填）（字符串）
- 选项在选项组中的唯一名称。
- 如果在选项组内部已使用选项名称，则不会添加，并且将在 wp-admin 中显示管理通知。
标签（必填）（字符串）
- 字段的标签。
类型（必填）（字符串）
- 字段的类型。
- 有效值有
  - 文本
  - 密码
  - 电子邮件
  - 单选按钮
  - 复选框
  - 选择
  - 多选选择
  - 媒体
描述（可选）（字符串）
- 选项功能的简要描述。
- 这将在 HTML 输入元素下方显示。
选项（可选）（数组）
- 一个包含 value => label 对的数组。
- 默认为空数组：[]。
- 此参数应用于 radio、checkbox、select 和 select-multiple。否则传递空数组。
默认值（可选）（混合类型）
- 选项的默认值。
- 默认为 null。
清理回调（可选）（可调用）
- 一个可调用的函数，用于在将其输入到数据库之前清理输入值。
- 这可以是闭包函数，也可以是 [ $this, '<public_method_name>' ] 对于非静态类或 [ __CLASS__, '<public_method_name>' ] 对于静态类。
- 您的函数应接受 1 个参数，即字段的用户输入值。因此，它是一个 mixed 字段。
- 默认为 null。
返回回调（可选）（可调用）
- 一个可调用的函数，用于格式化选项值在其返回方法中。
- 这可以是闭包函数，也可以是 [ $this, '<public_method_name>' ] 对于非静态类或 [ __CLASS__, '<public_method_name>' ] 对于静态类。
- 您的函数应接受 1 个参数，即从数据库返回的选项值。
- 默认为 null。

new \MarsPress\Options\Settings\Page 需要 7 个参数，3 个必填和 4 个可选。

选项组（必填）（\MarsPress\Options\Settings\Option_Group）
- 选项组实例。
页面标题（必填）（字符串）
- 页面标题，这将作为 h1 元素输出到页面。
页面别名（必填）（字符串）
- 页面的 wp-admin 别名。
父级缩略名（可选）（字符串）
- 页面的父级缩略名。
- 默认为 null。
- 如果没有提供，您的页面将被添加到主wp-admin菜单。
- 如果您想将页面放在“设置”菜单下，请传递options-general.php。
菜单标题（可选）（字符串）
- 在wp-admin菜单中显示的菜单标题。
- 默认为页面标题。
图标（可选）（字符串）
- 菜单图标的dashicon字符串或绝对URL。
- 这仅在您的页面没有父级缩略名时使用。
- 默认为dashicons-admin-generic。
菜单位置（可选）（整数）
- wp-admin菜单中菜单项的位置。
- 这仅在您的页面没有父级缩略名时使用。
- 默认为80。

示例

首先，您必须创建一个选项组

$exampleOptionGroup = new \MarsPress\Options\Settings\Option_Group('example_settings');

然后您可以为您的选项组添加选项（包括每个字段类型的示例）

$exampleOptionGroup->add_options(
    new \MarsPress\Options\Settings\Option(
      'example_text',
      'Text Field Example',
      'text',
      'Example description.',
        [],
        null,
        function( $_input ){
          $_input = str_replace( '-example-sanitization', '', $_input );
          return $_input . '-example-sanitization';
        }
    ),
    new \MarsPress\Options\Settings\Option(
        'example_radio',
        'Radio Field Example',
        'radio',
        'Example description.',
        [
            '1' => 'Value One',
            '2' => 'Value Two',
            '3' => 'Value Three',
        ]
    ),
    new \MarsPress\Options\Settings\Option(
        'example_checkbox',
        'Checkbox Field Example',
        'checkbox',
        'Example description.',
        [
            '1' => 'Value One',
            '2' => 'Value Two',
            '3' => 'Value Three',
        ]
    ),
    new \MarsPress\Options\Settings\Option(
        'example_select',
        'Select Field Example',
        'select',
        'Example description.',
        [
            '1' => 'Value One',
            '2' => 'Value Two',
            '3' => 'Value Three',
        ]
    ),
    new \MarsPress\Options\Settings\Option(
        'example_select_w_groups',
        'Select Field with Groups Example',
        'select',
        'Example description.',
        [
            'Option Group Integers' => [
                '1' => 'Value One',
                '2' => 'Value Two',
                '3' => 'Value Three',
            ],
            'Option Group Floats'   => [
                '1.00' => 'Value One.00',
                '2.00' => 'Value Two.00',
                '3.00' => 'Value Three.00',
            ],
        ]
    ),
    new \MarsPress\Options\Settings\Option(
        'example_select_multiple',
        'Select Multiple Field Example',
        'select-multiple',
        'Example description.',
        [
            '1' => 'Value One',
            '2' => 'Value Two',
            '3' => 'Value Three',
        ]
    ),
    new \MarsPress\Options\Settings\Option(
        'example_select_multiple_w_groups',
        'Select Multiple Field with Groups Example',
        'select-multiple',
        'Example description.',
        [
            'Option Group Integers' => [
                '1' => 'Value One',
                '2' => 'Value Two',
                '3' => 'Value Three',
            ],
            'Option Group Floats'   => [
                '1.00' => 'Value One.00',
                '2.00' => 'Value Two.00',
                '3.00' => 'Value Three.00',
            ],
        ],
        null,
        null,
        function( $_value ){
            //Example Return Callback
            return implode( ', ', $_value );
        }
    ),
    new \MarsPress\Options\Settings\Option(
        'example_media',
        'Media Field Example',
        'media',
        'Example description.',
        [],
        null,
        null,
        function( $_value ){
            //Example Return Callback
            return "<img style='max-width: 300px; height: auto;' src='$_value'>";
        }
    ),

然后您可以创建一个页面

new \MarsPress\Options\Settings\Page(
  $exampleOptionGroup,
  'Example Settings',
  'example-settings',
  'options-general.php'
);

然后您可以访问您的选项值

echo $optionGroup->get_option_value('example_media');

方法/类链式调用

因为Option Group类的add_options方法返回自身，所以您可以使用类和方法的链式调用，如下所示

$exampleOptionGroup = (new \MarsPress\Options\Settings\Option_Group('example_settings'))->add_options(
    new \MarsPress\Options\Settings\Option(
        'example_text',
        'Text Field Example',
        'text',
        'This is the description.',
        [],
        null,
        function ( $_input ){
            $_input = str_replace( '-working', '', $_input );
            return $_input . '-working';
        }
    ),
);

尽管您也可以在\MarsPress\Options\Settings\Page构造函数内部进行链式调用，但建议您存储您Option Group的实例，以便您可以轻松访问选项值。

WP主题修改

主题修改通常在外观自定义器中。

资源

https://developer.wordpress.org/themes/customize-api/customizer-objects/

使用

new \MarsPress\Options\ThemeMods\Customization_Section()接受4个参数，2个必需和2个可选。

键（必填）（字符串）
- 唯一部分键。
- 如果部分键已在自定义管理器中存在，则在自定义器外观中会输出一个管理员通知。
标签（必填）（字符串）
- 在自定义器面板中显示的标签。
描述（可选）（字符串）
- 在标签下方显示的描述。
- 默认为null
位置（可选）（字符串）
- 在自定义器面板中的优先级/位置。
- 默认为160（面板底部附近）

可用方法

add_customizations接受任意数量的参数，只要它们是\MarsPress\Options\ThemeMods\Customization类型。
- 返回 self：$this。
get_customization_value()接受2个参数，1个必需和1个可选。
- 自定义名称（必需）（字符串）
  - 返回值的主题修改名称。
  - 如果主题修改值在数据库中不存在，该方法将返回null。
  - 如果自定义对象具有返回回调，则方法将返回返回回调的返回值。
- 返回原始值（可选）（布尔值）
  - 是否跳过主题修改的返回回调。
  - 默认为 false。

new \MarsPress\Options\ThemeMods\Customization()接受10个参数，3个必需和7个可选。

名称（必填）（字符串）
- 主题修改的ID。
- 这应该对部分是唯一的。
- 如果名称已在部分中存在，则不会添加它，并且在wp-admin中会显示一个管理员通知。
标签（必填）（字符串）
- HTML输入的标签。
类型（必填）（字符串）
- 输入类型。
- 有效值（一些取决于浏览器支持）
  - 文本
  - 隐藏
  - 数字
  - 范围
  - URL
  - 电话
  - 电子邮件
  - 搜索
  - 时间
  - 日期
  - 日期时间
  - 周
  - 复选框
  - 复选框多选
  - 选择
  - 多选选择
  - 单选按钮
  - 文本区域
  - 媒体
描述（可选）（字符串）
- 在HTML输入下方显示的描述。
- 默认为null
占位符（可选）（字符串）
- HTML输入的占位符。
- 这受HTML支持的占位符元素的影响。
- 默认为null
选项（可选）（数组）
- 值=>标签的选项数组。
- 这仅用于checkbox、checkbox-multiple、select、select-multiple和radio类型。
- 否则应传递一个空数组（[]）。
- 默认为空数组：[]
位置（可选）（整数）
- 部分内的优先级/位置。
- 默认为10
默认值（可选）（混合类型）
- 输入的默认值。
- 这是一个混合类型，因为它取决于你的主题模块类型。例如，一个text类型可能有默认值"这是默认值"，但像select-multiple这样的类型应该有一个数组。
- 默认为null
清理回调（可选）（可调用）
- 在将值保存到数据库之前需要执行的清理回调函数。
- 这可以是闭包函数，也可以是 [ $this, '<public_method_name>' ] 对于非静态类或 [ __CLASS__, '<public_method_name>' ] 对于静态类。
- 你的函数应该接受一个参数，即字段的用户输入值。因此，它是一个混合字段。
- 默认为null
返回回调（可选）（可调用）
- 在将值返回到PHP之前需要执行的返回回调函数。
- 这可以是闭包函数，也可以是 [ $this, '<public_method_name>' ] 对于非静态类或 [ __CLASS__, '<public_method_name>' ] 对于静态类。
- 你的函数应该接受一个参数，即字段的用户输入值。因此，它是一个混合字段。
- 默认为null

示例

首先，你需要创建一个部分

$exampleCustomizationSection = new \MarsPress\Options\ThemeMods\Customization_Section(
    'example_section',
    'Example Section',
    'Example Section Description.',
    1
);

然后你可以在部分中添加主题模块（包括最常见的字段类型示例）

$exampleCustomizationSection->add_customizations(
    new \MarsPress\Options\ThemeMods\Customization(
      'example_text',
      'Example Text Field',
      'text',
      'Example Field Description.',
      'Example placeholder'
    ),
    new \MarsPress\Options\ThemeMods\Customization(
        'example_select',
        'Example Select Field',
        'select',
        'Example Field Description.',
        null,
        [
            ''  => '-- Select --',
            '1' => 'Value One',
            '2' => 'Value Two',
            '3' => 'Value Three',
        ]
    ),
    new \MarsPress\Options\ThemeMods\Customization(
        'example_multi_select',
        'Example Select Multiple Field',
        'select-multiple',
        'Example Field Description.',
        null,
        [
            ''  => '-- Select --',
            '1' => 'Value One',
            '2' => 'Value Two',
            '3' => 'Value Three',
        ]
    ),
    new \MarsPress\Options\ThemeMods\Customization(
        'example_checkbox',
        'Example Checkbox Field',
        'checkbox',
        'Example Field Description.',
        null,
    ),
    new \MarsPress\Options\ThemeMods\Customization(
        'example_multi_checkbox',
        'Example Checkbox Multiple Field',
        'checkbox-multiple',
        'Example Field Description.',
        null,
        [
            '1' => 'Value One',
            '2' => 'Value Two',
            '3' => 'Value Three',
        ],
        10,
        null,
        null,
        function ( $_value ){
            if( is_array( $_value ) ){
                return implode( ',', $_value );
            }
            return $_value;
        }
    ),
    new \MarsPress\Options\ThemeMods\Customization(
        'example_radio',
        'Example Radio Field',
        'radio',
        'Example Field Description.',
        null,
        [
            ''  => '-- None --',
            '1' => 'Value One',
            '2' => 'Value Two',
            '3' => 'Value Three',
        ]
    ),
    new \MarsPress\Options\ThemeMods\Customization(
        'example_text_area',
        'Example Text Area Field',
        'textarea',
        'Example Field Description.',
        'Example placeholder'
    ),
    new \MarsPress\Options\ThemeMods\Customization(
        'example_media',
        'Example Media Field',
        'media',
        'Example Field Description.',
        null
    ),
);

方法/类链式调用

因为自定义部分类的add_customizations方法返回自身，所以你可以使用类和方法链，如下所示

$exampleCustomizationSection = (new \MarsPress\Options\ThemeMods\Customization_Section(
    'example_section',
    'Example Section',
    'Example Section Description.',
    1
)->add_customizations(
    new \MarsPress\Options\ThemeMods\Customization(
      'example_text',
      'Example Text Field',
      'text',
      'Example Field Description.',
      'Example placeholder'
    ),
));

marspress / wp-options

维护者

详细信息

README

安装

WP 选项

资源

使用

可用方法

示例

方法/类链式调用

WP主题修改

资源

使用

可用方法

示例

方法/类链式调用