arraypress / wp-email-utils
An immutable value object for working with email addresses in WordPress — parsing, validation, transformation, classification and analysis.
Requires
- php: >=8.3
Requires (Dev)
- phpcompatibility/phpcompatibility-wp: ^2.1
- phpunit/phpunit: ^12.0
- squizlabs/php_codesniffer: ^3.13.5
- wp-coding-standards/wpcs: ^3.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
This library has moved. It is now part of
sugarcommerce/network(namespaceSugarCommerce\Network, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.
WordPress Email Utilities
An email address as a value object, so the fiddly questions have answers.
What it does
is_email() tells you whether an address is syntactically valid. Almost every
real question is a different one: are dave+shop@gmail.com and
d.a.v.e@gmail.com the same person signing up twice, is info@ a role
mailbox rather than a human, did someone type gmial.com, does the domain
accept mail at all.
Parse once into an Email, then ask. It is immutable, so the transformations
hand back a new instance rather than changing the one you have.
Features
- Compare two addresses as the same person, ignoring subaddresses and Gmail dots
- Spot role mailboxes —
info@,sales@,admin@— that are not individuals - Catch common domain typos and suggest the correction
- Check the domain actually has an MX record before accepting a signup
- Recognise educational and government addresses, for discounts or verification
- Add, replace or strip a
+tagsubaddress - Mask an address for display:
d••••e@example.com - Match against wildcard patterns, for allow and block lists
- List every domain and ending a rule about an address could name:
mail.example.co.uk,example.co.uk;uk,co.uk - Pull the host out of whatever was pasted where a domain goes: an address, a URL,
@example.com
Installation
composer require arraypress/wp-email-utils
Quick start
use ArrayPress\EmailUtils\Email; $email = Email::parse( $_POST['email'] ); if ( ! $email ) { return new WP_Error( 'invalid_email', 'That address is not valid.' ); } // Did they mean gmail.com? if ( $email->has_typo() ) { $suggestion = $email->suggested_email(); } // Is this the same customer signing up again with a +tag? if ( $email->equals_base( $existing_customer_email ) ) { // ... } // Route role mailboxes differently from real people. if ( $email->is_role_based() ) { // ... } // Show it in the admin without showing all of it. echo esc_html( $email->to_masked() ); // Show it to somebody who may not be its owner: first character, a fixed // run, the domain. "p••@example.com", whatever the length of the name. echo esc_html( Email::mask( 'patricia@example.com' ) );
The domain helpers are static and take a string, so an address too odd to
validate still has a domain to check. Email::domain_parents(),
Email::domain_suffixes(), Email::host_from() and Email::is_hostname()
know nothing of the public suffix list, and convert nothing between an
internationalised name and its xn-- form: the xn-- form is a host name
here and the Unicode one is not, as with is_email().
Requirements
- PHP 8.3 or later
- WordPress 7.1 or later
License
GPL-2.0-or-later