README

PHP Values 是一个用于在 PHP 中创建不可变值对象的工具。值对象接收原始值，对其进行转换、验证，并可以在您的应用程序中一致且可靠地使用。

例如，假设您在创建用户时需要一个电子邮件地址。您可以更传统地这样写

public function createUser(string $email)
{
    // perform sanitation and validation on email before using
}

但更优的做法是写成这样

use RyanWhitman\PhpValues\Email;

public function createUser(Email $email)
{
    // email has already been sanitized and validated and is ready for use
}

安装

您应该通过 composer 安装此包

composer require ryanwhitman/php-values

示例

首先创建一个 Value 类。例如，一个用于电子邮件地址的 Value 类

<?php

namespace App\Values;

use RyanWhitman\PhpValues\Value;
use RyanWhitman\PhpValues\Concerns\Stringable;

class Email extends Value
{
    use Stringable;

    protected function transform(string $email): string
    {
        return filter_var($email, FILTER_SANITIZE_EMAIL);
    }

    protected function validate(string $email): bool
    {
        return filter_var($email, FILTER_VALIDATE_EMAIL);
    }
}

现在，您可以开始使用这个值了

<?php

use App\Values\Email;

// Valid email address
Email::from('email@example.com'); // instance of Email
Email::from('email@example.com')->get(); // email@example.com
Email::getFrom('email@example.com'); // email@example.com
(string) Email::from('email@example.com'); // email@example.com
Email::isValid('email@example.com'); // true

// Valid email address (with imperfections)
Email::getFrom(' email @example.com '); // email@example.com
Email::isValid(' email @example.com '); // true

// Invalid email address
Email::from('non-email'); // throws exception
Email::tryFrom('non-email'); // null
Email::isValid('non-email'); // false

用法

要创建一个新的 Value 类，扩展 RyanWhitman\PhpValues\Value 类。从那里，定义一个可选的 transform 方法（可选）和一个必须的 validate 方法。在实例化时，transform 方法接收原始输入并对其进行转换，如果需要的话。然后，validate 方法接收转换后的值并返回 true 或 false。如果验证通过，则对象可用于使用。如果验证通过，将抛出 InvalidValueException。注意：存在 2 个 try 静态方法，用于捕获异常并返回 null。

transform(mixed $value): mixed

transform 方法是一个可选方法，在实例化期间调用。它接收输入值，当定义时，应返回值的净化/转换版本。由于子类需要正确的类型，transform 方法没有在基抽象值类中定义。

protected function transform(string $email): string
{
    return filter_var($email, FILTER_SANITIZE_EMAIL);
}

validate(mixed $value): bool

validate 方法在实例化期间调用。它接收转换后的值并应返回 true 或 false。由于子类需要正确的类型，validate 方法没有在基抽象值类中定义。

protected function validate(string $email): bool
{
    return filter_var($email, FILTER_VALIDATE_EMAIL);
}

基础值

假设您正在创建一个用于个人姓名的 Value 类。您可能希望删除所有不必要的空白。当然，您可以在 transform 方法中调用另一个 Value 类，但您也可以定义一个 $baseValues 属性来自动运行其他 Value 类

<?php

namespace App\Values;

use RyanWhitman\PhpValues\SquishedString;
use RyanWhitman\PhpValues\Value;

class Name extends Value
{
    protected array $baseValues = [
        SquishedString::class,
    ];

    // ...
}

静态方法

from(mixed $value): Value

from 静态方法在验证通过时将返回一个 Value 实例，在验证失败时将抛出异常。

Email::from('email@example.com'); // instance of Email
Email::from('non-email'); // throws InvalidValueException

getFrom(mixed $value): mixed

getFrom 静态方法是对 ::from($value)->get() 的简写。

Email::getFrom('email@example.com'); // email@example.com
Email::getFrom('non-email'); // throws InvalidValueException

tryFrom(mixed $value): ?Value

tryFrom 静态方法在验证通过时将返回一个 Value 实例，在验证失败时将返回 null。

Email::tryFrom('email@example.com'); // instance of Email
Email::tryFrom('non-email'); // null

tryGetFrom(mixed $value): mixed

tryGetFrom 静态方法是对 ::tryFrom($value)->get() 的简写。

Email::tryGetFrom('email@example.com'); // email@example.com
Email::tryGetFrom('non-email'); // null

isValid(mixed $value): bool

isValid 静态方法将返回 true 或 false。

Email::isValid('email@example.com'); // true
Email::isValid('non-email'); // false

实例方法

getOrigValue(): mixed

getOrigValue 方法返回原始输入值（在转换之前）。

Email::from('e m ail@example.com')->getOrigValue(); // e m ail@example.com

get(): mixed

get 方法返回转换和验证后的值。

Email::from('e m ail@example.com')->get(); // email@example.com

快捷方法

如上所述，getFrom 和 tryGetFrom 静态方法是对 ::from($value)->get() 和 ::tryFrom($value)->get() 的简写。您可以在自定义的 get 方法上添加 ShortcutMethod 注释/属性来添加相同的快捷功能。快捷方法必须使用驼峰命名法定义，并以 get 开头（例如 getFormatted）。

在 PHP 7.4+ 中使用 doctrine 注解

use RyanWhitman\PhpValues\Annotations\ShortcutMethod;

/**
 * @ShortcutMethod
 */
public function getFormatted()
{
    // ...
}

在 PHP 8.0+ 中使用属性

use RyanWhitman\PhpValues\Attributes\ShortcutMethod;

#[ShortcutMethod]
public function getFormatted()
{
    // ...
}

例如，添加 ShortcutMethod 注解/属性到 getFormatted 方法后，以下代码将正常工作

::getFormattedFrom($value)
::tryGetFormattedFrom($value)

特性

RyanWhitman\PhpValues\Concerns\Stringable

Stringable 特性简单定义了 __toString() 魔术方法为 (string) $this->get()。

异常

PHP Values 将抛出以下 1 个或 2 个异常之一

RyanWhitman\PhpValues\Exceptions\InvalidValueException 将在发生 TypeError（例如，需要一个数组但提供了一个字符串）或验证失败时抛出。此异常非常有用，因为它表明原始输入无效。RyanWhitman\PhpValues\Exceptions\Exception 在其他错误发生时抛出（例如，未定义 validate 方法）。注意：仅 try 方法捕获 InvalidValueException。

预构建值

测试

composer test

贡献

有关详细信息，请参阅 CONTRIBUTING。

安全

如果您发现任何安全相关的问题，请通过电子邮件 ryanawhitman@gmail.com 而不是使用问题跟踪器。

致谢

许可

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

ryanwhitman / php-values

维护者

详情