Statistics
4332
3
0
56d
Badges
Tags
mail
Dependencies

Email address value object

Build Status Coverage Status Downloads this Month Latest stable

Installation

Via Composer:

$ composer require nepada/email-address

Usage

This package provides two implementations of email address value object:

  1. RfcEmailAddress - it adheres to RFCs and treats local part of email address as case sensitive. The domain part is normalized to lower case ASCII representation.
  2. CaseInsensitiveEmailAddress - the only difference from RfcEmailAddress is that local part is considered case insensitive and normalized to lower case.

It is up to you to decide which implementation suites your needs. If you want to support both implementations, use Nepada\EmailAddress\EmailAddress as a typehint. You can also cast one representation to the other using RfcEmailAddress::toCaseInsensitiveEmailAddress() and CaseInsensitiveEmailAddress::toRfcEmailAddress().

Creating value object

$rfcEmailAddress = Nepada\EmailAddress\RfcEmailAddress::fromString('Real.example+suffix@HÁČKYčárky.cz');
$rfcEmailAddress = Nepada\EmailAddress\RfcEmailAddress::fromDomainAndLocalPart('HÁČKYčárky.cz', 'Real.example+suffix');

$ciEmailAddress = Nepada\EmailAddress\CaseInsensitiveEmailAddress::fromString('Real.example+suffix@HÁČKYčárky.cz');
$ciEmailAddress = Nepada\EmailAddress\CaseInsensitiveEmailAddress::fromDomainAndLocalPart('HÁČKYčárky.cz', 'Real.example+suffix');

Nepada\EmailAddress\InvalidEmailAddressException is thrown in case of invalid input value.

Converting back to string

Casting the value object to string, will result in the original (non-canonical) string representation of email address:

echo((string) $emailAddress); // Real.example+suffix@HÁČKYčárky.cz
echo($emailAddress->toString()); // Real.example+suffix@HÁČKYčárky.cz

Canonical string representation of email address

echo($emailAddress->getValue()); // real.example+suffix@xn--hkyrky-ptac70bc.cz

Getting normalized local and domain part separately

echo($emailAddress->getLocalPart()); // real.example+suffix
echo($emailAddress->getDomain()); // xn--hkyrky-ptac70bc.cz

Integrations

  • v2.3.0 2.3.0

    New

    • Introduce two distinct implementations of RfcEmailAddress and CaseInsensitiveEmailAddress to be used instead of generic EmailAddress.
    • Add EmailAddress::equals() for comparing two email address value objects.

    Deprecations

    • EmailAddress::getOriginalValue() is deprecated, use toString() instead.
    • EmailAddress::getLowercaseValue() is deprecated, for case insensitive representation of email address use directly CaseInsensitiveEmailAddress implementation.
    • Named constructors on EmailAddress are deprecated, you should use named constructors of a specific implementation.
    • For backward compatibility reasons EmailAddress exists as an abstract class. It should not be inherited from by userland. It will be converted to interface in the next major release.
  • v2.2.0 2.2.0

    • Requires PHP >=7.4.
    • Uses native property typehints.
  • v2.1.0 2.1.0

    • Requires Nette 3.0 (Nette 2.4 support was dropped).
    • Requires PHP >=7.2.
    • PHP 7.4 compatibility.
  • v2.0.0 2.0.0

    • Added EmailAddress::toString() method
    • Constructor is private, use static factories EmailAddress::fromString() and EmailAddress::fromDomainAndLocalPart() instead (BC break)
    • EmailAddress is final (possible BC break)
  • v1.1.0 1.1.0

    • Throw exception if domain normalization fails (possible BC break).
    • Explicitly require ext-intl.
  • v1.0.0 1.0.0

    • Initial release.

Is this addon outdated? Did you find an issue? Please report it.

Componette Componette admin@componette.com