云策 WordPress 开发者社区

函数文档

sanitize_user()

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

概述

sanitize_user() 函数用于清理用户名，移除不安全字符，如标签、百分号编码字符和 HTML 实体。通过 $strict 参数可控制是否仅保留字母数字、下划线、空格、点、连字符和 @ 符号。

关键要点

  • 清理用户名，移除标签、百分号编码字符和 HTML 实体
  • 可选 $strict 参数，启用时仅保留字母数字、_、空格、.、-、@ 字符
  • 应用 'sanitize_user' 过滤器，允许自定义清理逻辑
  • 返回清理后的用户名字符串

代码示例

function sanitize_user( $username, $strict = false ) {n    $raw_username = $username;n    $username     = wp_strip_all_tags( $username );n    $username     = remove_accents( $username );n    // Remove percent-encoded characters.n    $username = preg_replace( '|%([a-fA-F0-9][a-fA-F0-9])|', '', $username );n    // Remove HTML entities.n    $username = preg_replace( '/&.+?;/', '', $username );nn    // If strict, reduce to ASCII for max portability.n    if ( $strict ) {n        $username = preg_replace( '|[^a-z0-9 _.-@]|i', '', $username );n    }nn    $username = trim( $username );n    // Consolidate contiguous whitespace.n    $username = preg_replace( '|\s+|', ' ', $username );nn    /**n     * Filters a sanitized username string.n     *n     * @since 2.0.1n     *n     * @param string $username     Sanitized username.n     * @param string $raw_username The username prior to sanitization.n     * @param bool   $strict       Whether to limit the sanitization to specific characters.n     */n    return apply_filters( 'sanitize_user', $username, $raw_username, $strict );n}

注意事项

  • 函数内部使用 wp_strip_all_tags() 和 remove_accents() 辅助清理
  • 清理后应用 'sanitize_user' 过滤器，参数包括清理后的用户名、原始用户名和 $strict 值
  • 在 WordPress 2.0.0 版本引入
📄 原文内容

Sanitizes a username, stripping out unsafe characters.

Description

Removes tags, percent-encoded characters, HTML entities, and if strict is enabled, will only keep alphanumeric, _, space, ., -, @. After sanitizing, it passes the username, raw username (the username in the parameter), and the value of $strict as parameters for the ‘sanitize_user’ filter.

Parameters

$usernamestringrequired
The username to be sanitized.
$strictbooloptional
If set to true, limits $username to specific characters.

Default:false

Return

string The sanitized username, after passing through filters.

Source

function sanitize_user( $username, $strict = false ) {
	$raw_username = $username;
	$username     = wp_strip_all_tags( $username );
	$username     = remove_accents( $username );
	// Remove percent-encoded characters.
	$username = preg_replace( '|%([a-fA-F0-9][a-fA-F0-9])|', '', $username );
	// Remove HTML entities.
	$username = preg_replace( '/&.+?;/', '', $username );

	// If strict, reduce to ASCII for max portability.
	if ( $strict ) {
		$username = preg_replace( '|[^a-z0-9 _.-@]|i', '', $username );
	}

	$username = trim( $username );
	// Consolidate contiguous whitespace.
	$username = preg_replace( '|s+|', ' ', $username );

	/**
	 * Filters a sanitized username string.
	 *
	 * @since 2.0.1
	 *
	 * @param string $username     Sanitized username.
	 * @param string $raw_username The username prior to sanitization.
	 * @param bool   $strict       Whether to limit the sanitization to specific characters.
	 */
	return apply_filters( 'sanitize_user', $username, $raw_username, $strict );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘sanitize_user’, string $username, string $raw_username, bool $strict )

Filters a sanitized username string.

Uses Description
wp_strip_all_tags()wp-includes/formatting.php

Properly strips all HTML tags including ‘script’ and ‘style’.
remove_accents()wp-includes/formatting.php

Converts all accent characters to ASCII characters.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Show 1 moreShow less

Used by Description
display_setup_form()wp-admin/install.php

Displays installer setup form.
edit_user()wp-admin/includes/user.php

Edit user settings based on contents of $_POST
WP_User::get_data_by()wp-includes/class-wp-user.php

Returns only the main user fields.
wp_authenticate()wp-includes/pluggable.php

Authenticates a user, confirming the login credentials are valid.
register_new_user()wp-includes/user.php

Handles registering a new user.
validate_username()wp-includes/user.php

Checks whether a username is valid.
wp_insert_user()wp-includes/user.php

Inserts a user into the database.
wpmu_create_user()wp-includes/ms-functions.php

Creates a user.
wpmu_validate_user_signup()wp-includes/ms-functions.php

Sanitizes and validates data required for a user sign-up.
wpmu_signup_user()wp-includes/ms-functions.php

Records user signup information for future activation.

Show 5 moreShow less

Changelog

Version Description
2.0.0 Introduced.

User Contributed Notes