sanitize_key()

💡 云策文档标注

概述

sanitize_key() 函数用于清理字符串键，确保其符合 WordPress 内部标识符的规范。它通过转换为小写并移除非法字符来生成安全的键值。

关键要点

函数 sanitize_key() 清理字符串键，仅允许小写字母、数字、短横线和下划线。
参数 $key 为必需字符串，函数返回清理后的字符串。
内部实现使用 strtolower() 和 preg_replace() 进行转换和过滤。
提供 'sanitize_key' 过滤器钩子，允许开发者自定义清理逻辑。
广泛用于 WordPress 核心功能，如插件依赖检查、元数据处理和查询解析等。

代码示例

function sanitize_key( $key ) {
    $sanitized_key = '';

    if ( is_scalar( $key ) ) {
        $sanitized_key = strtolower( $key );
        $sanitized_key = preg_replace( '/[^a-z0-9_-]/', '', $sanitized_key );
    }

    /**
     * Filters a sanitized key string.
     *
     * @since 3.0.0
     *
     * @param string $sanitized_key Sanitized key.
     * @param string $key           The key prior to sanitization.
     */
    return apply_filters( 'sanitize_key', $sanitized_key, $key );
}

注意事项

仅当 $key 为标量（如字符串）时进行清理，否则返回空字符串。
清理过程会移除所有非小写字母、数字、短横线或下划线的字符，包括大写字母、斜杠和括号等。
自 WordPress 3.0.0 版本引入，是核心函数，常用于确保键值的一致性和安全性。

📄 原文内容

Sanitizes a string key.

Description

Keys are used as internal identifiers. Lowercase alphanumeric characters, dashes, and underscores are allowed.

Parameters

$keystringrequired: String key.

Return

string Sanitized key.

Source

function sanitize_key( $key ) {
	$sanitized_key = '';

	if ( is_scalar( $key ) ) {
		$sanitized_key = strtolower( $key );
		$sanitized_key = preg_replace( '/[^a-z0-9_-]/', '', $sanitized_key );
	}

	/**
	 * Filters a sanitized key string.
	 *
	 * @since 3.0.0
	 *
	 * @param string $sanitized_key Sanitized key.
	 * @param string $key           The key prior to sanitization.
	 */
	return apply_filters( 'sanitize_key', $sanitized_key, $key );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘sanitize_key’, string $sanitized_key, string $key ): Filters a sanitized key string.

Uses	Description
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Used by	Description
WP_Plugin_Dependencies::check_plugin_dependencies_during_ajax()`wp-includes/class-wp-plugin-dependencies.php`	Checks plugin dependencies after a plugin is installed via AJAX.
_wp_filter_post_meta_footnotes()`wp-includes/blocks.php`	Strips all HTML from the content of footnotes, and sanitizes the ID.
WP_Duotone::render_duotone_support()`wp-includes/class-wp-duotone.php`	Render out the duotone CSS styles and SVG.
WP_Style_Engine_CSS_Declarations::sanitize_property()`wp-includes/style-engine/class-wp-style-engine-css-declarations.php`	Sanitizes property names.
wp_create_user_request()`wp-includes/user.php`	Creates and logs a user request to perform a specific action.
_wp_personal_data_handle_actions()`wp-admin/includes/privacy-tools.php`	Handle list table actions.
wp_start_scraping_edited_file_errors()`wp-includes/load.php`	Starts scraping edited file errors.
WP_Customize_Manager::handle_load_themes_request()`wp-includes/class-wp-customize-manager.php`	Loads themes into the theme browsing/installation UI.
WP_Theme::get_post_templates()`wp-includes/class-wp-theme.php`	Returns the theme’s post templates.
wp_ajax_search_install_plugins()`wp-admin/includes/ajax-actions.php`	Handles searching plugins to install via AJAX.
wp_ajax_delete_plugin()`wp-admin/includes/ajax-actions.php`	Handles deleting a plugin via AJAX.
wp_ajax_search_plugins()`wp-admin/includes/ajax-actions.php`	Handles searching plugins via AJAX.
wp_ajax_install_theme()`wp-admin/includes/ajax-actions.php`	Handles installing a theme via AJAX.
wp_ajax_install_plugin()`wp-admin/includes/ajax-actions.php`	Handles installing a plugin via AJAX.
WP_Customize_Nav_Menu_Item_Setting::sanitize()`wp-includes/customize/class-wp-customize-nav-menu-item-setting.php`	Sanitize an input.
WP_Customize_Nav_Menus::ajax_load_available_items()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for loading available menu items.
wp_ajax_update_plugin()`wp-admin/includes/ajax-actions.php`	Handles updating a plugin via AJAX.
WP_Query::parse_orderby()`wp-includes/class-wp-query.php`	Converts the given orderby alias (if allowed) to a properly-prefixed value.
WP_Screen::get()`wp-admin/includes/class-wp-screen.php`	Fetches a screen object.
export_wp()`wp-admin/includes/export.php`	Generates the WXR export file for download.
WP_List_Table::__construct()`wp-admin/includes/class-wp-list-table.php`	Constructor.
update_user_status()`wp-includes/ms-deprecated.php`	Update the status of a user in the database.
set_screen_options()`wp-admin/includes/misc.php`	Saves option for number of rows when listing posts, pages, comments, etc.
post_preview()`wp-admin/includes/post.php`	Saves a draft or manually autosaves for the purpose of showing a post preview.
_wp_translate_postdata()`wp-admin/includes/post.php`	Renames `$_POST` data from form names to DB post columns.
edit_post()`wp-admin/includes/post.php`	Updates an existing post with values provided in `$_POST`.
bulk_edit_posts()`wp-admin/includes/post.php`	Processes the post data for the bulk editing of posts.
wp_ajax_heartbeat()`wp-admin/includes/ajax-actions.php`	Handles the Heartbeat API via AJAX.
wp_ajax_save_user_color_scheme()`wp-admin/includes/ajax-actions.php`	Handles auto-saving the selected color scheme for a user’s own profile via AJAX.
wp_ajax_dismiss_wp_pointer()`wp-admin/includes/ajax-actions.php`	Handles dismissing a WordPress pointer via AJAX.
wp_ajax_closed_postboxes()`wp-admin/includes/ajax-actions.php`	Handles closed post boxes via AJAX.
wp_ajax_hidden_columns()`wp-admin/includes/ajax-actions.php`	Handles hidden columns via AJAX.
wp_ajax_meta_box_order()`wp-admin/includes/ajax-actions.php`	Handles saving the meta box order via AJAX.
wp_ajax_inline_save_tax()`wp-admin/includes/ajax-actions.php`	Handles Quick Edit saving for a term via AJAX.
wp_ajax_get_tagcloud()`wp-admin/includes/ajax-actions.php`	Handles getting a tagcloud via AJAX.
wp_ajax_nopriv_heartbeat()`wp-admin/includes/ajax-actions.php`	Handles the Heartbeat API in the no-privilege context via AJAX .
wp_ajax_ajax_tag_search()`wp-admin/includes/ajax-actions.php`	Handles tag search via AJAX.
WP_Comments_List_Table::prepare_items()`wp-admin/includes/class-wp-comments-list-table.php`
WP_Customize_Manager::__construct()`wp-includes/class-wp-customize-manager.php`	Constructor.
_wp_customize_include()`wp-includes/theme.php`	Includes and instantiates the WP_Customize_Manager class.
WP_Query::parse_query()`wp-includes/class-wp-query.php`	Parses a query string and sets query type booleans.
WP_Tax_Query::transform_query()`wp-includes/class-wp-tax-query.php`	Transforms a single query, from one field to another.
WP_User_Query::prepare_query()`wp-includes/class-wp-user-query.php`	Prepares the query variables.
_get_last_post_time()`wp-includes/post.php`	Gets the timestamp of the last time any post was modified or published.
register_post_status()`wp-includes/post.php`	Registers a post status. Do not use before init.
register_post_type()`wp-includes/post.php`	Registers a post type.
_wp_preview_terms_filter()`wp-includes/revision.php`	Filters terms lookup to set the post format.
has_post_format()`wp-includes/post-formats.php`	Check if a post has any of the given formats, or any format.
set_post_format()`wp-includes/post-formats.php`	Assign a format to a post
wp_update_nav_menu_item()`wp-includes/nav-menu.php`	Saves the properties of a menu item or create a new one.
wp_xmlrpc_server::mw_editPost()`wp-includes/class-wp-xmlrpc-server.php`	Edits a post.
wp_xmlrpc_server::mw_newPost()`wp-includes/class-wp-xmlrpc-server.php`	Creates a new post.
WP_Meta_Query::get_sql()`wp-includes/class-wp-meta-query.php`	Generates SQL clauses to be appended to a main query.
delete_metadata()`wp-includes/meta.php`	Deletes metadata for the specified object.
update_metadata_by_mid()`wp-includes/meta.php`	Updates metadata by meta ID.
delete_metadata_by_mid()`wp-includes/meta.php`	Deletes metadata by meta ID.
update_meta_cache()`wp-includes/meta.php`	Updates the metadata cache for the specified objects.
add_metadata()`wp-includes/meta.php`	Adds metadata for the specified object.
update_metadata()`wp-includes/meta.php`	Updates metadata for the specified object. If no value already exists for the specified object ID and metadata key, the metadata will be added.

Show 54 more Show less

Changelog

Version	Description
3.0.0	Introduced.

User Contributed Notes

Skip to note 2 content

Muhammad Jawad Abbasi

4 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
In above code use one uppercase & other lowercase letters, number(1), dash, underscore, forward slash, brackets. So sanitize_key() function change one uppercase letter into lowercase, remove forward slash & brackets.

Output:
testexample1-_
Log in to add feedback

云策 WordPress 开发者社区

函数文档