README

此包代表一个不可变的电子邮件地址值对象以及额外的实用类。

安装

通过 Composer

$ composer require nordic/email-address

特性

不可变值对象
无依赖项
包含空电子邮件地址值对象（见空对象模式）
包含断言类
包含工厂类

基本类和接口

EmailAddressInterface - 是电子邮件地址值对象的基础接口。

EmailAddress - 通常是使用的不可变电子邮件地址值对象。

NullEmailAddress - 空电子邮件地址值对象（空对象设计模式）。

使用方法

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)

异常

InvalidEmailAddressException - 是一个基本异常，您可以使用。第一个参数是一个字符串值。

use Nordic\EmailAddress\InvalidEmailAddressException;

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

工厂模式

EmailAddressFactoryInterface - 是电子邮件地址工厂的基础接口。

EmailAddressFactory - 是创建 EmailAddress 值对象的工厂类。

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 可以用于检查字符串值是否为电子邮件地址字符串，或者检查电子邮件地址值对象是否不是空对象。所有方法如果断言失败将抛出 InvalidEmailAddressException。您始终可以将自定义异常消息作为第二个方法参数设置。

可用方法

Assertion::email - 如果字符串值不是有效的电子邮件地址，将失败。
Assertion::notNull - 如果电子邮件地址值对象是空电子邮件地址对象，将失败。

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

其他辅助工具

提供者接口和特性

当对象应仅提供电子邮件地址值对象时，使用接口 EmailAddressProviderInterface 和特性 EmailAddressProviderTrait（见 EmailAddressProviderTest.php 中的示例）。

感知接口和特性

当对象应该了解电子邮件地址值对象时，使用接口 EmailAddressAwareInterface 和特性 EmailAddressAwareTrait（见 EmailAddressAwareTest.php 中的示例）。

示例

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();

测试

$ composer test

致谢

许可

MIT 许可证（MIT）。请参阅许可文件了解更多信息。

nordic / email-address

维护者

详细信息