wp_login_form()

💡 云策文档标注

概述

wp_login_form() 函数用于在 WordPress 中任何位置生成一个简单的登录表单。默认情况下，表单 HTML 会被直接输出，但可以通过参数控制返回 HTML 字符串。

关键要点

函数接受一个可选的 $args 数组参数，用于自定义表单输出，如重定向 URL、表单 ID、标签文本等。
通过设置 'echo' 参数为 false，可以返回表单 HTML 字符串而非直接输出，适用于短代码或模板函数。
函数内置多个过滤器钩子（如 login_form_top、login_form_middle、login_form_bottom），允许开发者自定义表单内容。
返回类型取决于 'echo' 参数：若为 true 则返回 void，若为 false 则返回字符串形式的表单 HTML。

代码示例

// 基本用法：输出登录表单
wp_login_form();

// 自定义参数并返回 HTML 字符串
$args = array(
    'echo' => false,
    'redirect' => home_url('/dashboard/'),
    'label_username' => '用户名',
    'remember' => true
);
$form_html = wp_login_form($args);

注意事项

重定向 URL 必须为绝对路径，默认重定向回当前请求 URI。
在 WordPress 5.3 及以上版本中，可能会因管理员邮箱检查导致静默登录失败，可通过禁用 admin_email_check 过滤器解决。
在短代码回调中使用时，通常应设置 'echo' => false 以返回 HTML 字符串。

📄 原文内容

Provides a simple login form for use anywhere within WordPress.

Description

The login form HTML is echoed by default. Pass a false value for $echo to return it instead.

Parameters

$argsarrayoptional

Array of options to control the form output.

echo bool
Whether to display the login form or return the form HTML code.
Default true (echo).
redirect string
URL to redirect to. Must be absolute, as in “https://example.com/mypage/“.
Default is to redirect back to the request URI.
form_id string
ID attribute value for the form. Default 'loginform'.
label_username string
Label for the username or email address field. Default ‘Username or Email Address’.
label_password string
Label for the password field. Default 'Password'.
label_remember string
Label for the remember field. Default ‘Remember Me’.
label_log_in string
Label for the submit button. Default ‘Log In’.
id_username string
ID attribute value for the username field. Default 'user_login'.
id_password string
ID attribute value for the password field. Default 'user_pass'.
id_remember string
ID attribute value for the remember field. Default 'rememberme'.
id_submit string
ID attribute value for the submit button. Default 'wp-submit'.
remember bool
Whether to display the “rememberme” checkbox in the form.
value_username string
Default value for the username field.
value_remember bool
Whether the “Remember Me” checkbox should be checked by default.
Default false (unchecked).
required_username bool
Whether the username field has the 'required' attribute.
Default false.
required_password bool
Whether the password field has the 'required' attribute.
Default false.

Default:array()

Return

void|string Void if 'echo' argument is true, login form HTML if 'echo' is false.

Source

function wp_login_form( $args = array() ) {
	$defaults = array(
		'echo'              => true,
		// Default 'redirect' value takes the user back to the request URI.
		'redirect'          => ( is_ssl() ? 'https://' : 'http://' ) . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'],
		'form_id'           => 'loginform',
		'label_username'    => __( 'Username or Email Address' ),
		'label_password'    => __( 'Password' ),
		'label_remember'    => __( 'Remember Me' ),
		'label_log_in'      => __( 'Log In' ),
		'id_username'       => 'user_login',
		'id_password'       => 'user_pass',
		'id_remember'       => 'rememberme',
		'id_submit'         => 'wp-submit',
		'remember'          => true,
		'value_username'    => '',
		// Set 'value_remember' to true to default the "Remember me" checkbox to checked.
		'value_remember'    => false,
		// Set 'required_username' to true to add the required attribute to username field.
		'required_username' => false,
		// Set 'required_password' to true to add the required attribute to password field.
		'required_password' => false,
	);

	/**
	 * Filters the default login form output arguments.
	 *
	 * @since 3.0.0
	 *
	 * @see wp_login_form()
	 *
	 * @param array $defaults An array of default login form arguments.
	 */
	$args = wp_parse_args( $args, apply_filters( 'login_form_defaults', $defaults ) );

	/**
	 * Filters content to display at the top of the login form.
	 *
	 * The filter evaluates just following the opening form tag element.
	 *
	 * @since 3.0.0
	 *
	 * @param string $content Content to display. Default empty.
	 * @param array  $args    Array of login form arguments.
	 */
	$login_form_top = apply_filters( 'login_form_top', '', $args );

	/**
	 * Filters content to display in the middle of the login form.
	 *
	 * The filter evaluates just following the location where the 'login-password'
	 * field is displayed.
	 *
	 * @since 3.0.0
	 *
	 * @param string $content Content to display. Default empty.
	 * @param array  $args    Array of login form arguments.
	 */
	$login_form_middle = apply_filters( 'login_form_middle', '', $args );

	/**
	 * Filters content to display at the bottom of the login form.
	 *
	 * The filter evaluates just preceding the closing form tag element.
	 *
	 * @since 3.0.0
	 *
	 * @param string $content Content to display. Default empty.
	 * @param array  $args    Array of login form arguments.
	 */
	$login_form_bottom = apply_filters( 'login_form_bottom', '', $args );

	$form =
		sprintf(
			'<form name="%1$s" id="%1$s" action="%2$s" method="post">',
			esc_attr( $args['form_id'] ),
			esc_url( site_url( 'wp-login.php', 'login_post' ) )
		) .
		$login_form_top .
		sprintf(
			'<p class="login-username">
				<label for="%1$s">%2$s</label>
				<input type="text" name="log" id="%1$s" autocomplete="username" class="input" value="%3$s" size="20"%4$s />
			</p>',
			esc_attr( $args['id_username'] ),
			esc_html( $args['label_username'] ),
			esc_attr( $args['value_username'] ),
			( $args['required_username'] ? ' required="required"' : '' )
		) .
		sprintf(
			'<p class="login-password">
				<label for="%1$s">%2$s</label>
				<input type="password" name="pwd" id="%1$s" autocomplete="current-password" spellcheck="false" class="input" value="" size="20"%3$s />
			</p>',
			esc_attr( $args['id_password'] ),
			esc_html( $args['label_password'] ),
			( $args['required_password'] ? ' required="required"' : '' )
		) .
		$login_form_middle .
		( $args['remember'] ?
			sprintf(
				'<p class="login-remember"><label><input name="rememberme" type="checkbox" id="%1$s" value="forever"%2$s /> %3$s</label></p>',
				esc_attr( $args['id_remember'] ),
				( $args['value_remember'] ? ' checked="checked"' : '' ),
				esc_html( $args['label_remember'] )
			) : ''
		) .
		sprintf(
			'<p class="login-submit">
				<input type="submit" name="wp-submit" id="%1$s" class="button button-primary" value="%2$s" />
				<input type="hidden" name="redirect_to" value="%3$s" />
			</p>',
			esc_attr( $args['id_submit'] ),
			esc_attr( $args['label_log_in'] ),
			esc_url( $args['redirect'] )
		) .
		$login_form_bottom .
		'</form>';

	if ( $args['echo'] ) {
		echo $form;
	} else {
		return $form;
	}
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘login_form_bottom’, string $content, array $args ): Filters content to display at the bottom of the login form.
apply_filters( ‘login_form_defaults’, array $defaults ): Filters the default login form output arguments.
apply_filters( ‘login_form_middle’, string $content, array $args ): Filters content to display in the middle of the login form.
apply_filters( ‘login_form_top’, string $content, array $args ): Filters content to display at the top of the login form.

Uses	Description
is_ssl()`wp-includes/load.php`	Determines if SSL is used.
site_url()`wp-includes/link-template.php`	Retrieves the URL for the current site where WordPress application files (e.g. wp-blog-header.php or the wp-admin/ folder) are accessible.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
esc_attr()`wp-includes/formatting.php`	Escaping for HTML attributes.
esc_url()`wp-includes/formatting.php`	Checks and cleans a URL.
esc_html()`wp-includes/formatting.php`	Escaping for HTML blocks.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Show 6 more Show less

Changelog

Version	Description
6.6.0	Added `required_username` and `required_password` arguments.
3.0.0	Introduced.

User Contributed Notes

Skip to note 4 content

Codex

11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
This example displays a login form.
Log in to add feedback
Skip to note 5 content

benjamintoth

4 years ago

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

I have found this function is often broken by the admin_email_check update for WP 5.3 resulting in a silent login failure. If you run into silent login failures try disabling the admin email check.

// Disable administration email verification
add_filter( ‘admin_email_check_interval’, ‘__return_false’ );

Log in to add feedback
Skip to note 6 content

Shahar A

6 years ago

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
This example displays a login form as shortcode ([wpdocs_log_me]).
```
function wpdocs_log_me_shortcode_fn() {

  $args = array(
    'echo'            => true,
    'redirect'        => get_permalink( get_the_ID() ),
    'remember'        => true,
    'value_remember'  => true,
  );

  return wp_login_form( $args );

}
add_shortcode( 'wpdocs_log_me', 'wpdocs_log_me_shortcode_fn' );
```
- Since you are returning it from inside a shortcode callback, you want to return a string instead of displaying it. Thus, it should be 'echo' => false in my opinion.
  
  SkillsUp 5 years ago
Log in to add feedback

云策 WordPress 开发者社区

函数文档