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( 'david+newsletter@gmail.com' );

if ( $email ) {
    $email->local();          // 'david+newsletter'
    $email->domain();         // 'gmail.com'
    $email->tld();            // 'com'
    $email->base_local();     // 'david'
    $email->base_address();   // 'david@gmail.com'
    $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( 'admin@gmail.com' );

$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( 'user@gmial.com' );

$email->has_typo();          // true
$email->suggested_domain();  // 'gmail.com'
$email->suggested_email();   // 'user@gmail.com'

Pattern Matching

$email = Email::parse( 'user@company.edu' );

// 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

Comparison

$email1 = Email::parse( 'david+test@gmail.com' );
$email2 = Email::parse( 'david+other@gmail.com' );

$email1->equals( $email2 );       // false
$email1->equals_base( $email2 );  // true (both are david@gmail.com)
$email1->same_domain( $email2 );  // true

Transformations

$email = Email::parse( 'david@gmail.com' );

// Immutable - returns new instances
$email->with_subaddress( 'shopping' );  // david+shopping@gmail.com
$email->with_domain( 'yahoo.com' );     // david@yahoo.com
$email->with_local( 'john' );           // john@gmail.com
$email->without_subaddress();           // david@gmail.com

Array Output

$email = Email::parse( 'david@gmail.com' );

$email->to_array();           // Full parsed data
echo json_encode( $email );   // JSON serializable
echo (string) $email;         // 'david@gmail.com'

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

Detection

Typo Detection

Pattern Matching

Comparison

Transformations

Output

Options

Requirements

• PHP 7.4+
• WordPress 5.0+

License

GPL-2.0-or-later