check_password_reset_key()

check_password_reset_key() は、ユーザーがパスワードリセットリンク内のキーとログイン名を使用した際に、それが正当かつ有効かどうかを確認するための関数です。

キーが期限内でハッシュと一致しているか、または古い形式のキーが許可された場合にユーザーを返し、不正または期限切れの場合は適切なエラー（invalid_key または expired_key）を返します。

基本構文

$user = check_password_reset_key( string $key, string $login );

• $key：リセットリンクに含まれるワンタイムキー
• $login：リセット対象のユーザーのログイン名

キーが有効であれば WP_User オブジェクトを返し、無効や期限切れであれば WP_Error を返します。

引き数と戻り値

使用例

タグを使った使用例

$user = check_password_reset_key( $_GET['key'], $_GET['login'] );

if ( is_wp_error($user) ) {
    echo 'エラー: ' . $user->get_error_message();
} else {
    // key有効なのでパスワードリセット画面へ
    reset_password($user, $_POST['new_pass']);
    echo 'パスワードを変更しました。';
}

リクエストされたキーとログイン名をチェックし、不正であればエラーメッセージを表示、有効なら reset_password() を呼び出して処理を進めます。

注意点

• ワンタイムキーの有効期限はデフォルトで24時間以内です（DAY_IN_SECONDS）。
• 古い（平文）キーを扱う場合ついては、password_reset_key_expired フィルターで動作をカスタマイズ可能です。
• パラメーターに不正な形式や空文字を渡すと invalid_key エラーが返ります。

よく一緒に使われる関数

get_password_reset_key()

リセット開始時にキーとハッシュが生成され、DBの user_activation_key に保存されます。

reset_password()

キーが有効な場合に、ユーザーのパスワードを更新する本体処理を担います。

apply_filters( 'password_reset_key_expired', … )

古い形式（平文）または期限切れキー使用時に WP_User を返すようカスタマイズするフィルターです。

想定されるトラブル

常に invalid_key が返される

キー・ログイン名の受け渡しに誤りがある。例えば rawurlencode() を使ったがデコードに失敗したなど。

解決方法

• rawurlencode() の際は、rawurldecode() と組み合わせてクリーンに受け渡す
• var_dump() で実際の値を確認する

expired_key なのに期限切れ扱いされない

password_reset_expiration フィルターで期限時間を調整している、または平文キーなので期限判定の後に返される可能性あり。

解決方法

• 期限延長したい場合はフィルターで password_reset_expiration を変更
• 平文キー許可時は password_reset_key_expired フィルターを使って WP_User を返すようカスタマイズ

Q&A

まとめ

check_password_reset_key() は、パスワードリセット処理を安全に行うための中核関数です。

キーの有効性と期限を厳密に確認し、適切なエラーを返します。リセットリンクを独自実装する際にも整合性を保てるよう、get_password_reset_key() などと併せて使用すると強力です。また、期限延長や平文のサポートなど、フィルターを使って柔軟にカスタマイズできる点も強みです。