arraypress/wp-email-utils

A lightweight immutable value object for parsing and working with email addresses in WordPress.

dev-main 2026-02-28 12:59 UTC

Requires

• php: >=7.4

GPL-2.0-or-later

• David Sherlock

• parser
• email
• wordpress
• validation
• subaddress
• typo-detection

README

A lightweight immutable value object for parsing and working with email addresses in WordPress. Extracts parts, detects subaddressing, identifies common providers, suggests typo corrections, and provides comparison utilities.

Installation

composer require arraypress/wp-email-utils

Usage

Basic Parsing

use ArrayPress\EmailUtils\Email;

$email = Email::parse( '[e-mail]' );

if ( $email ) {
    $email->local();          // 'david+newsletter'
    $email->domain();         // 'gmail.com'
    $email->tld();            // 'com'
    $email->base_local();     // 'david'
    $email->base_address();   // '[e-mail]'
    $email->subaddress();     // 'newsletter'
}

One-Liners

$domain = parse_email( $input )?->domain();
$tld    = parse_email( $input )?->tld();
$valid  = parse_email( $input )?->valid() ?? false;

Detection

$email = Email::parse( '[e-mail]' );

$email->is_subaddressed();        // false
$email->is_common_provider();     // true
$email->supports_subaddressing(); // true
$email->is_role_based();          // true
$email->has_mx();                 // true (DNS lookup)

Typo Detection

$email = Email::parse( '[e-mail]' );

$email->has_typo();          // true
$email->suggested_domain();  // 'gmail.com'
$email->suggested_email();   // '[e-mail]'

Pattern Matching

$email = Email::parse( '[e-mail]' );

// Match against a list of patterns
$email->matches_any( [ '.edu', '@company.com' ] );  // true
$email->matches_any( [ '.gov', '@test.com' ] );     // false

// Match a single pattern
$email->matches_pattern( '.edu' );          // true
$email->matches_pattern( '@company.edu' );  // true
$email->matches_pattern( 'company.edu' );   // true (partial domain)

// Match all patterns
$email->matches_all( [ '.edu', 'company.edu' ] );  // true

// Validate patterns (static)
Email::is_valid_pattern( '@domain.com' );  // true
Email::is_valid_pattern( '.edu' );         // true
Email::is_valid_pattern( 'invalid' );      // false

// Filter to valid patterns (static)
Email::filter_valid_patterns( [ '@test.com', '', '.edu', 'bad' ] );
// Returns: [ '@test.com', '.edu' ]

// Sanitize a pattern list from raw input (static)
Email::sanitize_pattern_list( "@test.com\n.edu\nbad\n" );
// Returns: [ '@test.com', '.edu' ]

Supported Pattern Types

Pattern	Example	Matches
Full email	[e-mail]	Exact email match only
Domain	@company.com	Any email ending with @company.com
TLD	.edu	Any email ending with .edu
Partial domain	company.com	@company.com and @sub.company.com

Comparison

$email1 = Email::parse( '[e-mail]' );
$email2 = Email::parse( '[e-mail]' );

$email1->equals( $email2 );       // false
$email1->equals_base( $email2 );  // true (both are [e-mail])
$email1->same_domain( $email2 );  // true

Transformations

$email = Email::parse( '[e-mail]' );

// Immutable - returns new instances
$email->with_subaddress( 'shopping' );  // [e-mail]
$email->with_domain( 'yahoo.com' );     // [e-mail]
$email->with_local( 'john' );           // [e-mail]
$email->without_subaddress();           // [e-mail]

Array Output

$email = Email::parse( '[e-mail]' );

$email->to_array();           // Full parsed data
echo json_encode( $email );   // JSON serializable
echo (string) $email;         // '[e-mail]'

Options Helpers

// For building select dropdowns
Email::get_common_providers();                  // ['gmail.com' => 'gmail.com', ...]
Email::get_common_providers( as_options: true ); // [['value' => 'gmail.com', 'label' => 'gmail.com'], ...]

Email::get_role_prefixes();                     // ['admin' => 'admin', ...]
Email::get_role_prefixes( as_options: true );    // [['value' => 'admin', 'label' => 'admin'], ...]

Methods

Getters

Method	Returns	Description
valid()	bool	Whether email is valid
original()	string	Original input string
normalized()	string	Lowercase, trimmed email
local()	string	Local part (before @)
domain()	string	Domain part (after @)
tld()	string	Top-level domain
base_local()	string	Local part without subaddress
base_address()	string	Email without subaddress
subaddress()	?string	Subaddress tag or null
digit_count()	int	Digits in local part

Detection

Method	Returns	Description
is_subaddressed()	bool	Contains + subaddress
is_common_provider()	bool	Gmail, Yahoo, Outlook, etc.
supports_subaddressing()	bool	Provider supports + addressing
is_role_based()	bool	admin@, info@, support@, etc.
has_mx()	bool	Has valid MX records (DNS check)

Typo Detection

Method	Returns	Description
has_typo()	bool	Domain is a known typo
suggested_domain()	?string	Corrected domain or null
suggested_email()	?string	Full corrected email or null

Pattern Matching

Method	Returns	Description
matches_any()	bool	Matches any pattern in list
matches_all()	bool	Matches all patterns in list
matches_pattern()	bool	Matches a single pattern
is_valid_pattern()	bool	Pattern is valid (static)
filter_valid_patterns()	array	Filter to valid patterns (static)
sanitize_pattern_list()	array|string	Sanitize raw pattern input (static)

Comparison

Method	Returns	Description
equals()	bool	Exact match (case-insensitive)
equals_base()	bool	Base address match (ignores tags)
same_domain()	bool	Domain match

Transformations

Method	Returns	Description
with_local()	?static	New instance with different local
with_domain()	?static	New instance with different domain
with_subaddress()	?static	New instance with subaddress
without_subaddress()	?static	New instance without subaddress

Output

Method	Returns	Description
get_formatted()	string	local @ domain
to_array()	array	Full parsed data

Options

Method	Returns	Description
get_common_providers()	array	List of common providers
get_role_prefixes()	array	List of role prefixes

Requirements

• PHP 7.4+
• WordPress 5.0+

License

GPL-2.0-or-later