[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)
Search

title

Body

[close]

/wp-includes/ -> class-wp-email-address.php (summary)

[Source view] [Print] [Project Stats]

Class 'WP_Email_Address'.

File Size: 405 lines (14 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 7 functions

  __construct()
  from_string()
  get_localpart()
  get_ascii_domain()
  get_unicode_domain()
  get_ascii_address()
  get_unicode_address()

Functions
Functions that are not part of a class:

__construct( string $localpart, string $ascii_domain, ?string $unicode_domain )   X-Ref
Private constructor. Use {@see WP_Email_Address::from_string()} to create instances.

param: string $localpart           The local part of the email address.
param: string $ascii_domain        The domain part of the email address, which may include punycode transcription.
param: string|null $unicode_domain The domain part of the email address, which may contain Unicode characters, or

from_string( string $input, string $character_set = 'unicode' )   X-Ref
Creates a WP_Email_Address from a string.

This method is intended to accept all strings that are considered valid email
addresses by the WHATWG HTML specification for the `email` input type
{@link https://html.spec.whatwg.org/multipage/input.html#email-state-(type=email)}
and some additional addresses, while rejecting strings that are more likely to
be typos, mispastes, or attacks. This class may reject a few address that are
valid according to RFC 5322, but it always accepts an address if it's valid
according to WHATWG. Put differently: If users can type an address into the
major browsers of 2026, this class accepts them, if they can't (in 2026),
this class may or may not.

Example:

// Typical all-US-ASCII email address.
$email = WP_Email_Address::from_string( 'webmaster@example.com' );
'webmaster'   === $email->get_localpart();
'example.com' === $email->get_ascii_domain();
'example.com' === $email->get_unicode_domain();

// Punycode domains are always decoded.
$email = WP_Email_Address::from_string( 'books@xn--bcher-kva.de' );
'books'            === $email->get_localpart();
'xn--bcher-kva.de' === $email->get_ascii_domain();
'Bücher.de'        === $email->get_unicode_domain();

// Unicode localparts are accepted if Unicode addresses are requested (the default).
$email = WP_Email_Address::from_string( 'bücher@example.com' );
'bücher' === $email->get_localpart();

// Addresses with non-ASCII are rejected if ASCII-only addresses are requested.
null === WP_Email_Address::from_string( 'books@xn--bcher-kva.de', 'ascii' );
null === WP_Email_Address::from_string( 'bücher@xn--bcher-kva.de', 'ascii' );
null === WP_Email_Address::from_string( 'bücher@Bücher.de', 'ascii' );

// Some valid addresses (according to RFC 5322) are rejected.
null === WP_Email_Address::from_string( '"<iframe src=...>"@example.com' );

Note! If an address contains punycode encodings but the required {@see idn_to_utf8()}
function is missing (from the `intl` extension), this will reject that email address.

param: string            $input         The email address string to parse.
param: 'ascii'|'unicode' $character_set Allow only ASCII addresses or all valid Unicode addresses.
return: WP_Email_Address|null A WP_Email_Address instance, or null if the input fails to validate.

get_localpart()   X-Ref
Returns the local part of the email address (the portion before the '@').

Example:

$email = WP_Email_Address::from_string( 'checkout@bücher.tld' );
'checkout' === $email->get_localpart();

return: string The local part of the email address.

get_ascii_domain()   X-Ref
Returns the ASCII form of the domain, suitable for contexts in which
other software will be reading and decoding it. May contain punycode.

Example:

$email = WP_Email_Address::from_string( 'checkout@bücher.tld' );
'xn--bcher-kva.tld' === $email->get_ascii_domain();

Note! Do not mix a Unicode local part with an ASCII domain part.
Prefer to keep the entire address in one form.

return: string Form of domain for machines, potentially containing

get_unicode_domain()   X-Ref
Returns the Unicode form of the domain, suitable for contexts in which
humans will be reading it. May contain Unicode characters.

Example:

$email = WP_Email_Address::from_string( 'checkout@bücher.tld' );
'bücher.tld' === $email->get_unicode_domain();

Note! Do not mix a Unicode local part with an ASCII domain part.
Prefer to keep the entire address in one form.

return: string The domain part of the email address.

get_ascii_address()   X-Ref
Returns the complete email address for contexts in which software
will read it; may contain punycode transliterated Unicode characters.

Use this method in places such as an `<a href>` attribute where other
software will decode the address.

The returned value can always be passed to {@see WP_Email_Address::from_string()}
and will produce an equivalent WP_Email_Address instance.

return: string

get_unicode_address()   X-Ref
Returns the complete email address for contexts in which humans
will read it; may contain Unicode characters in the domain.

Use this method in places such as HTML text nodes which visually
show the email address and domain.

The returned value can always be passed to {@see WP_Email_Address::from_string()}
and will produce an equivalent WP_Email_Address instance.

return: string The complete email address.


Generated : Sun Jun 14 08:20:09 2026 Cross-referenced by PHPXref