Update email provider token-message hooks

[joemaller]

What?

The primary purpose of this PR is to provide the $token to the email provider's subject filter. It also brings consistency to the shape of Two Factor's email provider token-message hook arguments, and standardizes the namespaces used by those filters. Includes tests and documentation.

Fixes: #898

Why?

Many services now include the login token in their email subject lines like "Your login code is 123456". This improves user-experience and speeds MFA logins.

Previously, the email subject filter did not have access to$token and its arguments did not match the shape of the message filter arguments. Developers wanting to include the token in email subjects had to use clumsy, fragile workarounds.

This PR adds (renames) two hooks:

• two_factor_email_token_subject
• two_factor_email_token_message

This PR deprecates two existing hooks:

• two_factor_token_email_subject
• two_factor_token_email_message

New hook names provide a clean pathway for changing the signature of two_factor_token_email_subject without breaking existing functionality. The new filter adds a $token argument to match the shape of two_factor_token_email_message. This makes it very easy for developers to include $token in email subject lines.

How?

• The arguments to both the two_factor_email_token_subject and two_factor_email_token_message filters are now symmetrical: $subject|$message, $token, $user_id.
• Old hooks have been deprecated for backwards compatibility.
• The new filters have been added to readme.txt. They were not previously documented.
• Added tests to cover both the new and deprecated filters.

Use of AI Tools

AI assistance: Yes
Tool(s): Opencode, browsers
Model(s): grok 4.3, gemini-3.1-pro-preview
Used for: Architectural suggestions, consistency and style-matching with existing code, and code review/QA.

Testing Instructions

Tests covering the changes were added.
Add this line to a theme with Two Factor installed to add the token to the email subject.

add_filter( 'two_factor_email_token_subject', function( $subject, $token ) {
    return "{$token} is your login code";
}, 10, 2 );

Changelog Entry

Change - Added $token to the token-email subject filter.
Deprecated - two_factor_token_email_subject and two_factor_token_email_message. Replaced with consistently named two_factor_email_token_* filters.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: joemaller <joemaller@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.