auth_cookie_expiration
云策文档标注
概述
auth_cookie_expiration 是一个 WordPress 过滤器，用于自定义用户认证 Cookie 的过期时间。它允许开发者根据用户 ID 和“记住我”选项调整会话持续时间。
关键要点
- 过滤器名称：auth_cookie_expiration，用于修改认证 Cookie 的过期时长（以秒为单位）。
- 参数：$length（过期时长，整数）、$user_id（用户 ID，整数）、$remember（是否记住用户登录，布尔值，默认 false）。
- 默认值：14 天（14 * DAY_IN_SECONDS），可通过 apply_filters 调用覆盖。
- 相关函数：wp_set_auth_cookie() 和 wp_update_user() 使用此过滤器设置或更新用户 Cookie。
- 引入版本：WordPress 2.8.0。
代码示例
// 示例1：将登录会话延长至一年
add_filter('auth_cookie_expiration', 'wpdev_login_session');
function wpdev_login_session($expire) {
return YEAR_IN_SECONDS;
}
// 示例2：根据 $remember 和用户权限自定义过期时间
add_filter('auth_cookie_expiration', 'auth_cookie_expiration_filter_5587', 10, 3);
function auth_cookie_expiration_filter_5587($expiration, $user_id, $remember) {
if ($remember && !user_can($user_id, 'edit_others_posts')) {
return YEAR_IN_SECONDS;
}
return $expiration;
}
// 示例3：设置永久 Cookie（使用 PHP_INT_MAX）
add_filter('auth_cookie_expiration', function (int $length): int {
return PHP_INT_MAX;
});
// 示例4：基于用户角色设置过期时间
add_filter('auth_cookie_expiration', 'wp_homework_change_cookie_logout', 10, 3);
function wp_homework_change_cookie_logout($expiration, $user_id, $remember) {
$user = wp_get_current_user();
$allowed_roles = array('administrator', 'scholar');
if (array_intersect($allowed_roles, $user->roles)) {
$expiration = 31557600; // 一年（秒）
}
return $expiration;
}注意事项
- 建议考虑 $remember 参数：当 $remember 为 false 时，应设置较短的过期时间或保持默认，以避免 wp_update_user() 中的启发式标志误判。
- 自定义过期时间时，注意安全性和用户体验，避免设置过长或永久 Cookie 导致潜在风险。
- 代码示例展示了多种应用场景，包括基于角色、权限和“记住我”选项的定制化处理。
原文内容
Filters the duration of the authentication cookie expiration period.
Parameters
$lengthint-
Duration of the expiration period in seconds.
$user_idint-
User ID.
$rememberbool-
Whether to remember the user login. Default false.
Source
$expiration = time() + apply_filters( 'auth_cookie_expiration', 14 * DAY_IN_SECONDS, $user_id, $remember );
Changelog
| Version | Description |
|---|---|
| 2.8.0 | Introduced. |
Skip to note 5 content
Ethan O’Sullivan
An example of how to extend time in your WordPress session by a year, simply enter this code into your `functions.php` or plugin. Other durations have been added to show different times hat can be set.
add_filter ( 'auth_cookie_expiration', 'wpdev_login_session' ); function wpdev_login_session( $expire ) { // Set login session limit in seconds return YEAR_IN_SECONDS; // return MONTH_IN_SECONDS; // return DAY_IN_SECONDS; // return HOUR_IN_SECONDS; }wp_update_user(). After a password change, it guesses the user wants “Remember me” if the current cookie time left is longer than what this filter returns with $remember = false. Comment based on WP 5.0.2.Skip to note 6 content
polev
Extension of the example, only extending expiration if $remember and low privelege.
add_filter('auth_cookie_expiration', 'auth_cookie_expiration_filter_5587', 10, 3); function auth_cookie_expiration_filter_5587($expiration, $user_id, $remember) { if ($remember && !user_can($user_id, 'edit_others_posts')) { return YEAR_IN_SECONDS; // return MONTH_IN_SECONDS; // return DAY_IN_SECONDS; // return HOUR_IN_SECONDS; } // default return $expiration; }Skip to note 7 content
kmvan
// forever add_filter('auth_cookie_expiration', function (int $length): int { return PHP_INT_MAX; });Skip to note 8 content
Zübeyir Muştak
function wp_homework_change_cookie_logout( $expiration){ $user = wp_get_current_user(); $allowed_roles = array('administrator', 'scholar'); if( array_intersect($allowed_roles, $user->roles ) ) { $expiration = 31557600; } return $expiration; } add_filter( 'auth_cookie_expiration','wpse108399_change_cookie_logout', 10, 3 );