函数文档

signup_user()

💡 云策文档标注

概述

signup_user() 函数用于显示新用户账户注册表单,供访客填写。它处理用户名、邮箱和错误参数,并支持通过过滤器自定义默认变量。

关键要点

  • 函数 signup_user( $user_name = '', $user_email = '', $errors = '' ) 接受三个参数:用户名、用户邮箱和错误对象(WP_Error 或字符串)。
  • 内部使用全局变量 $active_signup 和 $_POST['signup_for'] 来确定注册类型(默认为 'blog')。
  • 通过 apply_filters( 'signup_user_init', $signup_user_defaults ) 过滤器允许开发者修改默认用户变量。
  • 输出 HTML 表单,包含隐藏字段、输入框和错误显示,使用 WordPress 函数如 esc_attr_e() 和 checked() 确保安全。
  • 与相关函数如 validate_user_signup() 和 validate_blog_signup() 配合使用,用于多站点环境。

代码示例

function signup_user( $user_name = '', $user_email = '', $errors = '' ) {
    global $active_signup;

    if ( ! is_wp_error( $errors ) ) {
        $errors = new WP_Error();
    }

    $signup_for = isset( $_POST['signup_for'] ) ? esc_html( $_POST['signup_for'] ) : 'blog';

    $signup_user_defaults = array(
        'user_name'  => $user_name,
        'user_email' => $user_email,
        'errors'     => $errors,
    );

    $filtered_results = apply_filters( 'signup_user_init', $signup_user_defaults );
    $user_name        = $filtered_results['user_name'];
    $user_email       = $filtered_results['user_email'];
    $errors           = $filtered_results['errors'];

    // 输出表单 HTML
}

注意事项

  • 此函数主要用于多站点(MU)环境,自 WordPress 3.0.0 引入。
  • 错误参数应为 WP_Error 对象或空字符串,函数内部会检查并初始化 WP_Error。
  • 表单输出包含隐藏字段,通过 do_action( 'signup_hidden_fields', $context ) 钩子可扩展。
  • 确保在调用前正确设置参数,以避免表单显示错误或数据不一致。

📄 原文内容

Shows a form for a visitor to sign up for a new user account.

Parameters

$user_namestringrequired
The username.
$user_emailstringrequired
The user’s email.
$errorsWP_Error|stringrequired
A WP_Error object containing existing errors. Defaults to empty string.

Source

function signup_user( $user_name = '', $user_email = '', $errors = '' ) {
global $active_signup;

if ( ! is_wp_error( $errors ) ) {
$errors = new WP_Error();
}

$signup_for = isset( $_POST['signup_for'] ) ? esc_html( $_POST['signup_for'] ) : 'blog';

$signup_user_defaults = array(
'user_name' => $user_name,
'user_email' => $user_email,
'errors' => $errors,
);

/**
* Filters the default user variables used on the user sign-up form.
*
* @since 3.0.0
*
* @param array $signup_user_defaults {
* An array of default user variables.
*
* @type string $user_name The user username.
* @type string $user_email The user email address.
* @type WP_Error $errors A WP_Error object with possible errors relevant to the sign-up user.
* }
*/

$filtered_results = apply_filters( 'signup_user_init', $signup_user_defaults );
$user_name = $filtered_results['user_name'];
$user_email = $filtered_results['user_email'];
$errors = $filtered_results['errors'];

?>

<h2>
site_name );
?>
</h2>

<form id="setupform" method="post" action="wp-signup.php" novalidate="novalidate">
<input type="hidden" name="stage" value="validate-user-signup" />

<input id="signupblog" type="hidden" name="signup_for" value="blog" />

<input id="signupblog" type="hidden" name="signup_for" value="user" />

<fieldset class="signup-options">
<legend></legend>
<p class="wp-signup-radio-buttons">
<span class="wp-signup-radio-button">
<input id="signupblog" type="radio" name="signup_for" value="blog" <?php checked( $signup_for, 'blog' ); ?> />
<label class="checkbox" for="signupblog"></label>
</span>
<span class="wp-signup-radio-button">
<input id="signupuser" type="radio" name="signup_for" value="user" <?php checked( $signup_for, 'user' ); ?> />
<label class="checkbox" for="signupuser"></label>
</span>
</p>
</fieldset>

<p class="submit"><input type="submit" name="submit" class="submit" value="<?php esc_attr_e( 'Next' ); ?>" /></p>
</form>
</pre><p class="wporg-dot-link-list"><a href="https://developer.wordpress.org/reference/files/wp-signup.php/">View all references</a> <a href="https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-signup.php#L591">View on Trac</a> <a href="https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-signup.php#L591-L663">View on GitHub</a></p></section>
<section class="wp-block-wporg-code-reference-hooks"><h2 id="hooks" class="is-toc-heading wp-block-heading has-heading-5-font-size" tabindex="-1" ><a href="#hooks">Hooks</a></h2> <dl><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/signup_hidden_fields/"><span class="hook-func">do_action</span>( ‘signup_hidden_fields’, <nobr><span class="arg-type">string</span> <span class="arg-name">$context</span></nobr> )</a></dt><dd><p>Fires when hidden sign-up form fields output when creating another site or user.</p>
</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/signup_user_init/"><span class="hook-func">apply_filters</span>( ‘signup_user_init’, <nobr><span class="arg-type">array</span> <span class="arg-name">$signup_user_defaults</span></nobr> )</a></dt><dd><p>Filters the default user variables used on the user sign-up form.</p>
</dd></dl></section>

<section class="wp-block-wporg-code-reference-related" data-nosnippet="true"><h2 id="related" class="is-toc-heading wp-block-heading has-heading-5-font-size" tabindex="-1" ><a href="#related">Related</a></h2> <section style="margin-top:var(--wp--preset--spacing--20)" class="wp-block-wporg-code-table" id="uses"><figure class="wp-block-table "><table><thead><tr><th scope="col">Uses</th><th scope="col">Description</th></tr></thead><tbody><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/get_network/">get_network()</a><code>wp-includes/ms-network.php

Retrieves network data given a network ID or network object.

show_user_form()wp-signup.php

Displays the fields for the new user account registration form.

esc_attr_e()wp-includes/l10n.php

Displays translated text that has been escaped for safe use in an attribute.

checked()wp-includes/general-template.php

Outputs the HTML checked attribute.

__()wp-includes/l10n.php

Retrieves the translation of $text.

_e()wp-includes/l10n.php

Displays translated text.

esc_html()wp-includes/formatting.php

Escaping for HTML blocks.

apply_filters()wp-includes/plugin.php

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

do_action()wp-includes/plugin.php

Calls the callback functions that have been added to an action hook.

is_wp_error()wp-includes/load.php

Checks whether the given variable is a WordPress Error.

WP_Error::__construct()wp-includes/class-wp-error.php

Initializes the error.

Show 7 moreShow less

Used by Description
validate_user_signup()wp-signup.php

Validates the new user sign-up.

validate_blog_signup()wp-signup.php

Validates new site signup.

Changelog

Version Description
MU (3.0.0) Introduced.