README

An immutable value object for working with email addresses. Provides parsing, validation, transformation, and analysis.

Installation

composer require arraypress/email-utils

Usage

Basic Parsing

use ArrayPress\EmailUtils\Email;

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

if ( $email ) {
    $email->domain();        // 'gmail.com'
    $email->local();         // 'david+newsletter'
    $email->tld();           // 'com'
    $email->base_address();  // 'david@gmail.com'
    $email->subaddress();    // 'newsletter'
}

One-Liners

$domain = Email::parse( $input )?->domain();
$score  = Email::parse( $input )?->spam_score() ?? 100;
$valid  = Email::parse( $input )?->valid() ?? false;

Detection

$email = Email::parse( 'admin@harvard.edu' );

$email->valid();                 // true
$email->is_educational();        // true
$email->is_role_based();         // true
$email->is_common_provider();    // false
$email->is_authority_provider(); // false
$email->is_government();         // false
$email->is_military();           // false
$email->is_private();            // false
$email->is_auto_generated();     // false
$email->has_mx();                // true (DNS lookup)

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

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

// Get pattern type (static)
Email::get_pattern_type( 'user@test.com' );  // 'email'
Email::get_pattern_type( '@domain.com' );    // 'domain'
Email::get_pattern_type( '.edu' );           // 'tld'
Email::get_pattern_type( 'company.com' );    // 'partial'

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

Supported Pattern Types

Typo Detection

$email = Email::parse( 'user@gmial.com' );

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

Transformations

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

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

Output Formats

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

$email->to_anonymized();      // 'da***@gm***.com'
$email->to_masked( 2, 1 );    // 'da**d@gmail.com'
$email->to_hashed();          // 'a1b2c3...@gmail.com'
$email->to_hashed( true );    // 'a1b2c3...@d4e5f6...'
$email->to_placeholder();     // 'deleted@site.invalid'

Spam Scoring

$email = Email::parse( 'xj382kd92@dodgy.xyz' );

$email->spam_score();        // 0-100 (higher = worse)
$email->spam_score( true );  // Include MX check
$email->spam_rating();       // 'excellent', 'good', 'fair', 'poor', 'bad'

Comparison

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

$email1->equals( $email2 );       // false
$email1->equals_base( $email2 );  // true
$email1->same_domain( $email2 );  // true

Country Detection

Email::parse( 'user@example.co.uk' )?->country();  // 'GB'
Email::parse( 'user@example.de' )?->country();     // 'DE'
Email::parse( 'user@example.com' )?->country();    // null

Array Output

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

// Simplified (for APIs)
$email->to_simple_array();

// Comprehensive
$email->to_array();

// JSON
echo json_encode( $email );

Methods

Getters

Detection

Matching

Typo Suggestions

Transformations

Output

Scoring

Comparison

Requirements

• PHP 7.4+

License

GPL-2.0-or-later