云策 WordPress 开发者社区

钩子文档

sanitize_option_{$option}

查看官方原文 ↗
💡 云策文档标注

概述

sanitize_option_{$option} 是一个 WordPress 过滤器，用于在选项值被 sanitize_option() 函数清理后进一步过滤。它允许开发者自定义选项的清理逻辑，包括内置选项和自定义选项。

关键要点

  • 过滤器名称基于选项名动态生成，例如 sanitize_option_blogname。
  • 参数包括 $value（清理后的值）、$option（选项名）和 $original_value（原始传入值）。
  • 可用于过滤内置选项（如 admin_email）或自定义选项（如 feed_url）。
  • 从 WordPress 4.3.0 版本开始添加了 $original_value 参数。

代码示例

// 过滤内置选项示例
add_filter('sanitize_option_admin_email', 'sanitize_builtin_option', 10, 2);

function sanitize_builtin_option($value, $option) {
    // 自定义清理逻辑
    return $value;
}

// 过滤自定义选项示例
add_filter('sanitize_option_feed_url', 'sanitize_url', 10, 2);

function sanitize_url($value, $option) {
    // 清理 URL 逻辑
    return esc_url_raw($value);
}

注意事项

  • $original_value 参数表示在应用当前过滤器之前的值，而非原始数据库中的选项值。
  • 使用此过滤器时，需确保函数正确处理所有参数，避免意外覆盖。
📄 原文内容

Filters an option value following sanitization.

Parameters

$valuemixed
The sanitized option value.
$optionstring
The option name.
$original_valuemixed
The original value passed to the function.

More Information

There is one filter per option name; the $option in the filter name stands for the name (e.g. ‘sanitize_option_blogname‘, ‘sanitize_option_siteurl‘). You can use this filter to define a sanitizer for your own options. See the notes for sanitize_option() for a list of existing options.

Filter existing options

add_filter('sanitize_option_admin_email', 'sanitize_builtin_option', 10, 2);
add_filter('sanitize_option_new_admin_email', 'sanitize_builtin_option', 10, 2);

function sanitize_builtin_option($value, $option) {
//...
}

Filter your own options

add_filter('sanitize_option_feed_url', 'sanitize_url', 10, 2);
add_filter('sanitize_option_wpi_endpoint', 'sanitize_url', 10, 2);
add_filter('sanitize_option_contact_email', 'sanitize_email');

function sanitize_url($value, $option) {
//...
}

function sanitize_email($value, $option) {
//...
}

Source

return apply_filters( "sanitize_option_{$option}", $value, $option, $original_value );

View all references View on Trac View on GitHub

Used by Description
sanitize_option()wp-includes/formatting.php

Sanitizes various option values based on the nature of the option.

Changelog

Version Description
4.3.0 Added the $original_value parameter.
2.3.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    Steven Lin


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Example Migrated from Codex:

    add_option('blocksize', 200); # 256 gets stored for blocksize

add_filter('sanitize_option_blocksize', 'sanitize_blocksize');

if (! function_exists('lg')) {
    function lg($x) {
        return log($x) / log(2);
    }
}

function sanitize_blocksize($value) {
    return pow(2, ceil(lg($value)));
}

  2. Skip to note 4 content


    Gerard Reches


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    To be more clear, $original_value holds the value before any sanitize_option_{$option} filter has been applied to the current option.

    So if $value is originally 'My Value' and a filter with higher priority has sanitized it into 'my_value', what we will receive is:

    $value = 'my_value'<br />
    $option = 'the_option_name'<br />
    $original_value = 'My Value'

    $original_value is NOT the original option value, but the new option value before sanitization.