README

Yerp

Yerp 是一个 PHP 对象属性验证库。它被编写用来为其他一些库提供简单的验证，但它可能在其他地方也有价值。

Yerp 使用 PHP 属性在公共属性上设置验证规则。然后您可以将该对象的实例传递给验证器并获取结果。结果是布尔值，因此没有翻译或语言要求。您可以根据结果指定自己的消息。

安装

composer require thepublicgood/yerp

使用方法

每个验证规则都是 TPG\Yerp\Rules 命名空间中不同的属性类。

这里有一个快速示例

use TPG\Yerp\Rules;

class User
{
    #[Rules\Required]
    public string $firstName;
    #[Rules\Nullable]
    public ?string $lastName = null;
    #[Rules\Required, Rules\Email]
    public string $emailAddress;
    #[Rules\Boolean(true)]
    public boolean $active;
}

有一些内置的规则，您可以轻松地添加自己的规则。

请注意，只有公共属性可以验证。

运行验证器

要验证一个对象，将其传递给 Validator 类并调用 validate 方法。这将返回一个 Validated 实例，它提供了访问每个属性上每个规则的结果。

class UserController
{
    public function create()
    {
        // Create a new object instance
        $user = new User();
        $user->firstName = 'John';
        $user->lastName = 'Doe';
        $user->emailAddress = 'john.doe@example.com';
        $user->active = false;

        // Pass to the validator
        $validated = (new Validator($user))->validate();
    }
}

获取结果

Validated 类提供了一个 property 方法，您可以使用它来获取特定属性的验证结果。该方法返回一个 Result 实例。您可以使用提供的 passed 方法来测试给定属性的验证结果

$validated = (new Validator($user))->validate();

$validated->property('firstName')->passed();

passed 方法返回一个表示该属性验证结果的布尔值。还有一个 failed 方法，它返回相反的结果

$validated->property('firstName')->failed();

如果您想了解属性上特定规则的结果，可以将规则类的名称传递给 property 方法

$validated->property('firstName', Rule\Required::class)->passed();

在第一个错误时停止

所有验证规则将按照它们出现的顺序进行评估。您可以告诉 Yerp，如果某个特定的规则失败，则停止验证剩余的规则。您可以通过将 true 传递给任何规则上的 last 属性来实现这一点

#[Rule\Nullable, Rules\Email(last: true), Rule\Equal('test@example.com')]
public string $emailAddress;

在上面的示例中，如果 Email 规则失败，则不会评估 Equal 规则。如果 Email 规则确实通过，则 Equal 规则将进行评估，并将出现在结果中。如果您使用 last 来结束评估，则任何后来的规则都不会包含在结果集中。这很重要，因为如果您尝试检查结果中不存在的规则的结果，您将得到一个 InvalidRuleException。

为每个规则设置消息

虽然 Yerp 设计为无翻译，但设置静态消息可能会有所帮助。您可以通过将字符串值传递给任何规则上的 failure 属性来实现这一点

#[Rules\Email(failure: 'Must be a valid email address')]
public string $email;

当此规则评估时，您将能够在 Result 类上使用 message 方法

$validated->property('email', Rules\Email::class)->message();

如果规则通过或未设置消息，则 message 方法将返回 null。默认情况下，只有在规则失败时才返回消息。但是，您可以指定一个成功消息，方法是向 success 属性传递一个字符串

#[Rules\Email(
    success: 'The email address is valid!',    // Success
    failure: 'Must be a valid email address',  // Failed
)]
public string $email;

可用规则

必需

Required 规则可以用来验证必须存在的属性。必需属性必须包含值，不能为 null 和不能为空。空数组或空字符串将失败

#[Rules\Required]
property ?string $someString;

Alpha

Alpha 规则确保属性的值仅包含字母。

#[Rules\Alpha]
property string $someString;

ArrayKey

ArrayKey 规则简单地确保指定的键存在于数组中

#[Rules\ArrayKey('test')]
property array $someArray;

Boolean

布尔规则允许您验证属性是否为 TRUE 或 FALSE

#[Rules\Boolean(true)]
property bool $mustBeTrue;

相等性

您可以通过将所需的值作为 Euqal 规则的第一个参数来确保属性等于特定值。

#[Rules\Equal('expected')]
propert ?string $someString;

还有一个相反的 NotEqual 规则。

电子邮件

常见的验证规则是确保字符串是有效的电子邮件地址。

#[Rules\Email]
property string $emailAddress;

在...

In 规则允许您测试一个值是否是指定的值之一。

#[Rules\In(['a', 'b', 'c'])]
property string $someString;

长度

Length 规则允许您指定最小和/或最大长度。如果属性类型是数组，则长度验证数组元素的数量。

#[Rules\Length(min: 5, max: 20)]
property string $someString;

您不需要同时指定，但您必须至少指定一个值。

数字

Numeric 规则确保属性可以解析为数字。

#[Rules\Numeric]
property string $someString;

正则表达式

您可以将正则表达式字符串作为 Regex 规则的第一个参数传递。

#[Rules\Regex('/^test$/')]
property string $regexString;

编写新规则

Yerp 仅提供少量规则。这主要是因为它们是我们当时唯一需要的。我们可能会添加更多规则，因为我们更频繁地需要它们，但添加自己的规则非常简单，无需询问。

创建一个新类来包含您的规则逻辑，并扩展 TPG\Yerp\Rules\AbstractRule 类，然后在类定义中添加 #[Attribute]。

您需要实现所需的 validate 方法，该方法返回一个 TPG\Yerp\Result。您可以使用返回一个新 Result 实例的 getResult 方法。

namespace CustomRules;

use Attribute;
use TPG\Yerp\Rules\AbstractRule;
use TPG\Yerp\Result;

#[Attribute]
class HyphenatedRule extends AbstractRule
{
    public function validate(mixed $value): Result
    {
        return $this->getResult(str_contains((string)$value, '-'));
    }
}

现在您可以在任何类中使用您的新规则。

use CustomRules\Hyphenated;

class Article
{
    public string $title;
    #[HyphenatedRule]
    public string $slug;
}

您的新规则具有相同的 last、success 和 failure 参数。如果您的规则需要接受一个值，只需在构造函数中指定它即可。

namespace CustomRules;

use Attribute;
use TPG\Yerp\Rules\AbstractRule;
use TPG\Yerp\Result;

use DelimitedRule extends AbstractRule
{
    public function __construct(protected string $delimiter = ',')
    {
    }

    public function validate(string $value): Result
    {
        return $this->getResult(str_contains($value, $this->delimited));
    }
}

致谢

Warrick Bayman

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅 LICENSE.md 文件。

thepublicgood / yerp

维护者

详细信息