云策 WordPress 开发者社区

钩子文档

login_url

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

概述

login_url 是一个 WordPress 过滤器，用于修改 wp_login_url() 函数返回的登录 URL。它允许开发者自定义登录链接，支持重定向和强制重新授权参数。

关键要点

  • login_url 过滤器应用于 wp_login_url() 函数返回的 URL，用于自定义登录页面地址。
  • 过滤器接受三个参数：$login_url（登录 URL，非 HTML 编码）、$redirect（登录后重定向路径，可选）、$force_reauth（是否强制重新授权，布尔值）。
  • 从 WordPress 4.2.0 版本开始添加了 $force_reauth 参数，2.8.0 版本引入此过滤器。
  • 过滤器适用于网站上的登录链接（如博客页面），但不影响浏览器直接访问 /wp-login.php 的 URL。
  • 可用于创建自定义登录表单，例如为订阅者提供特定登录页面，而管理员仍使用核心登录表单（如启用双因素认证时）。

代码示例

add_filter( 'login_url', 'smyles_custom_login_url', 10, 3 );
/**
 * Filters the login URL.
 *
 * @since 2.8.0
 * @since 4.2.0 The `$force_reauth` parameter was added.
 *
 * @param string $login_url    The login URL. Not HTML-encoded.
 * @param string $redirect     The path to redirect to on login, if supplied.
 * @param bool   $force_reauth Whether to force reauthorization, even if a cookie is present.
 *
 * @return string
 */
function smyles_custom_login_url( $login_url, $redirect, $force_reauth ){
	// This will append /custom-login/ to you main site URL as configured in general settings (ie https://domain.com/custom-login/)
	$login_url = site_url( '/custom-login/', 'login' );
	if ( ! empty( $redirect ) ) {
		$login_url = add_query_arg( 'redirect_to', urlencode( $redirect ), $login_url );
	}
	if ( $force_reauth ) {
		$login_url = add_query_arg( 'reauth', '1', $login_url );
	}
	return $login_url;
}

注意事项

  • 过滤器不会影响直接访问 /wp-login.php 的浏览器 URL，仅适用于通过 wp_login_url() 生成的链接。
  • 自定义登录表单（如 User Registration 插件提供的）可能不支持双因素认证，此时核心登录表单仍有用。
  • 使用 add_query_arg() 函数可以更安全地添加查询参数，如 redirect_to 和 reauth。
📄 原文内容

Filters the login URL.

Parameters

$login_urlstring
The login URL. Not HTML-encoded.
$redirectstring
The path to redirect to on login, if supplied.
$force_reauthbool
Whether to force reauthorization, even if a cookie is present.

More Information

login_url is a filter applied to the url returned by the function wp_login_url()

Source

return apply_filters( 'login_url', $login_url, $redirect, $force_reauth );

View all references View on Trac View on GitHub

Used by Description
wp_login_url()wp-includes/general-template.php

Retrieves the login URL.

Changelog

Version Description
4.2.0 The $force_reauth parameter was added.
2.8.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    tripflex


    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

    Here’s an example of filtering the `login_url` to specify a custom one:

    add_filter( 'login_url', 'smyles_custom_login_url', 10, 3 );
/**
 * Filters the login URL.
 *
 * @since 2.8.0
 * @since 4.2.0 The `$force_reauth` parameter was added.
 *
 * @param string $login_url    The login URL. Not HTML-encoded.
 * @param string $redirect     The path to redirect to on login, if supplied.
 * @param bool   $force_reauth Whether to force reauthorization, even if a cookie is present.
 *
 * @return string
 */
function smyles_custom_login_url( $login_url, $redirect, $force_reauth ){
	// This will append /custom-login/ to you main site URL as configured in general settings (ie <a href="https://domain.com/custom-login/" rel="nofollow ugc">https://domain.com/custom-login/</a>)
	$login_url = site_url( '/custom-login/', 'login' );
	if ( ! empty( $redirect ) ) {
		$login_url = add_query_arg( 'redirect_to', urlencode( $redirect ), $login_url );
	}
	if ( $force_reauth ) {
		$login_url = add_query_arg( 'reauth', '1', $login_url );
	}
	return $login_url;
}

  2. Skip to note 5 content


    johnzoet1


    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

    Tested this login_url filter and it works fine for login links on the website, for example on blog pages.
    The filter will not work for a browser URL like /wp-login.php.

    This can be useful in case you have a custom login form for subscribers, while administrators still login with the WordPress core login form when two-factor authentication is enabled.

    A custom login form like those of User Registration plugin will not work with 2FA. This is where the core login form is still useful.

  3. Skip to note 6 content


    Steven Lin


    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

    Examples migrated from Codex:

    The following example would return a login URL http://example.com/my-login-page/ for the wp_login_url() function:

    add_filter( 'login_url', 'my_login_page', 10, 3 );
function my_login_page( $login_url, $redirect, $force_reauth ) {
    return home_url( '/my-login-page/?redirect_to=' . $redirect );
}

    Same as above, but uses the add_query_arg() function for adding the redirect_to parameter and is expanded for readability.

    add_filter( 'login_url', 'my_login_page', 10, 3 );
function my_login_page( $login_url, $redirect, $force_reauth ) {
    $login_page = home_url( '/my-login-page/' );
    $login_url = add_query_arg( 'redirect_to', $redirect, $login_page );
    return $login_url;
}