README

This package represents an immutable email address value object and additional utility classes.

Install

Via Composer

$ composer require nordic/email-address

Features

Immutable value object
No dependencies
Include null email address value object (see Null object pattern)
Include assertion class
Include factory class

Basic classes and interfaces

EmailAddressInterface - is the base interface for email address value objects.

EmailAddress - immutable email address value object that will be used most of the time.

NullEmailAddress - null email address value object (null object design pattern).

Usage

use Nordic\EmailAddress\EmailAddress;
use Nordic\EmailAddress\NullEmailAddress;

$emailAddress = new EmailAddress('email@example.com');
$nullEmailAddress = new NullEmailAddress;

// Compare two email addresses
$emailAddressSame = new EmailAddress('email@example.com');
$emailAddressAnother = new EmailAddress('another@example.com');

var_dump($emailAddress->equals($emailAddressSame)); // boolean(true)
var_dump($emailAddress->equals($emailAddressAnother)); // boolean(false)

Exceptions

InvalidEmailAddressException - is a basic exception that you can use. The first argument is a string value.

use Nordic\EmailAddress\InvalidEmailAddressException;

$e = new InvalidEmailAddressException('wrong_email', 'Wrong email address');
var_dump($e->getEmailAddress()); // string(17) "wrong_email"

Factory pattern

EmailAddressFactoryInterface - is the base interface for email address factory.

EmailAddressFactory - is the factory class that creates EmailAddress value objects.

use Nordic\EmailAddress\EmailAddressFactory;

$factory = new EmailAddressFactory;
$emailAddress = $factory->createEmailAddress('email@example.com');
$nullEmailAddress = $factory->createEmailAddress();
$emailAddress = $factory->createEmailAddress('wrong_email'); // will throw InvalidEmailAddressException

Assertion

The class Assertion can be used for checking if string value is an email address string or check if email address value object is not null object. All methods will throw InvalidEmailAddressException if assertion will fails. You can always set a custom exception message as the second method argument.

Available methods:

Assertion::email - will fail in case if string value is not a valid email address.
Assertion::notNull - will fail in case if email address value object is null email address object.

use Nordic\EmailAddress\Assertion;

$email = Assertion::email('email@example.com');
$email = Assertion::email('wrong_email'); // will throw InvalidEmailAddressException

$emailAddress = Assertion::notNull($emailAddress);
// will throw InvalidEmailAddressException if $emailAddress is instance of NullEmailAddress

Additional helpers

Provider interface and trait

Use interface EmailAddressProviderInterface and trait EmailAddressProviderTrait when the object should only provide email address value object (see EmailAddressProviderTest.php for examples).

Aware intrerface and trait

Use interface EmailAddressAwareInterface and trait EmailAddressAwareTrait when the object should aware about email address value object (see EmailAddressAwareTest.php for examples).

Example

use Nordic\EmailAddress\Assertion;
use Nordic\EmailAddress\EmailAddress;
use Nordic\EmailAddress\EmailAddressInterface;
use Nordic\EmailAddress\EmailAddressFactory;
use Nordic\EmailAddress\InvalidEmailAddressException;
use Nordic\EmailAddress\EmailAddressProviderInterface;
use Nordic\EmailAddress\EmailAddressProviderTrait;

class MyClass implements EmailAddressProviderInterface
{
    use EmailAddressProviderTrait;

    public function __construct(EmailAddressInterface $emailAddress)
    {
        $this->emailAddress = Assertion::notNull($emailAddress);
    }
}

$factory = new EmailAddressFactory;

try {
    $myClass = new MyClass($factory->createEmailAddress('email@example.com'));
} catch (InvalidEmailAddressException $e) {
    // do something
}

$emailAddress = $myClass->getEmailAddress();

Testing

$ composer test

Credits

License

The MIT License (MIT). Please see License File for more information.

nordic / email-address

Maintainers

Details