README

Hird，也称为housecarls，是hirdmen的集合，他们在维京时代和早期中世纪担任国王的个人卫兵。

Hird是一个具有合理默认值的可扩展数据验证库。

安装

您可以通过composer安装此包

composer require asko/hird

用法

Hird接受一个包含 $fields 的数组和一个包含 $rules 的数组。

$fields 数组中每个项目的键必须与 $rules 数组中每个项目的键相对应，这样Hird才能知道如何将它们连接起来。

$rules 必须有一个字符串值，其中规则通过 | 字符分隔，每个规则必须匹配实现的验证器的键，例如 len、email 或您自己实现的规则。此外，每个规则可以接受一个修饰符，规则名和修饰符通过 : 字符分隔。

例如，假设我们有一个名为 len 的验证器，它接受一个修饰符，允许该验证器验证字符串的长度，在这种情况下，我们会将该规则写成 len:8，表示使用 len 验证器，并传递一个值为 8 的修饰符给它。

示例用法

Hird的示例用法如下

use Askonomm\Hird\Hird;

$fields = ['email' => 'asko@asko.dev'];
$rules = ['email' => 'required|email|len:5'];
$hird = new Hird($fields, $rules);

if ($hird->fails()) {
    return $hird->errors();
}

从上面的示例中，您可以看到使用了两个Hird方法，例如 $hird->fails() 和 $hird->errors()。$hird->fails() 方法将运行验证并返回一个布尔值，表示验证是否失败，如果失败了，则返回 true。$hird->errors() 方法将返回一个数组，其中包含所有由验证器定义的错误。

您也可以使用 $hird->firstError() 方法获取第一个错误而不是所有错误。

如果您希望在不需要调用 $hird->fails() 的情况下运行验证，您可以选择调用 $hird->validate()。

覆盖验证消息中的字段名称

您可以使用 $hird->setFieldNames 来覆盖用于错误消息的字段名称，这样当显示给用户时，email 就可以变成 E-mail。只需提供一个数组，键是您使用Hird实例化的实际字段名称，值是您希望在验证消息中使用的名字，如下所示

$hird->setFieldNames(['email' => 'E-mail']);

手动添加错误

在某些情况下，您想使用相同的验证器提供的错误消息，但想将它们与Hird之外的验证混合使用。为此，您可以使用 addError 方法，如下所示

$hird->addError("My error message goes here");

这将提示Hird验证失败并显示该错误消息。

内置验证器

默认情况下提供了许多内置验证器可供使用。如果您想删除内置验证器，可以使用 $hird->removeValidator('rule-name') 方法删除一个。

email

email 验证器验证电子邮件地址，并注册为 email 规则。

use Askonomm\Hird\Hird;

$fields = ['email' => 'asko@bien.ee'];
$rules = ['email' => 'email'];
$hird = new Hird($fields, $rules);

len

《len》验证器用于验证字符串的长度，它被注册为《len》规则。此外，《len》验证器还接受并要求一个修饰符。可以通过在规则后附加一个颜色字符《:》并将修饰符传递给它来传递一个修饰符，例如《len:8》。

use Askonomm\Hird\Hird;

$fields = ['password' => 'SuperSecretPassword'];
$rules = ['password' => 'len:10'];
$hird = new Hird($fields, $rules);

必需

《required》验证器用于验证值的必要性，它被注册为《required》规则。如果值已设置并且不是空字符串，它将通过验证。

use Askonomm\Hird\Hird;

$fields = ['password' => 'SuperSecretPassword'];
$rules = ['password' => 'required'];
$hird = new Hird($fields, $rules);

日期格式

《date-format》验证器用于验证日期的字符串格式，它被注册为《date-format》规则。如果值已设置并且符合规则指定的格式，它将通过验证。

use Askonomm\Hird\Hird;

$fields = ['date' => '2020-09-17'];
$rules = ['date' => 'date-format:Y-m-d'];
$hird = new Hird($fields, $rules);

创建验证器

您还可以创建自己的验证器，或者如果您对现有验证器不满意，可以替换它们。

注意：要替换现有的验证器，首先使用《$hird->removeValidator('rule-name)》移除内置验证器，然后使用《$hird->registerValidator('rule-name', ValidatorClass::class)》添加自己的验证器。

验证器是实现《Validator》接口的类。一个正确的验证器的完整示例可能看起来像这样

use Asko\Hird\Validators\Validator;

class EmailValidator implements Validator
{
    public function __construct(
        private array $fields, // all fields data
        private array $fieldNames, // names of fields
    ){
    }

    /**
     * Returns a boolean `true` when given `$value` is a valid e-mail
     * address. Returns `false` otherwise.
     *
     * @param mixed $value
     * @param mixed $modifier
     * @return boolean
     */
    public function validate(string $field, mixed $value, mixed $modifier = null): bool
    {
        return filter_var($value, FILTER_VALIDATE_EMAIL);
    }

    /**
     * Composes the error message in case the validation fails.
     *
     * @param string $field
     * @param mixed $modifier
     * @return string
     */
    public function composeError(string $field, mixed $modifier = null): string
    {
        return "${field} is not a valid e-mail address.";
    }
}

您可以看到有两个方法，一个用于验证《$value》，另一个在验证失败时生成错误消息。这两个函数都接受一个《$modifier》参数，它只有在验证器使用修饰符时才有值。例如，《len》验证器使用修饰符来确定所需的字符串长度，通过传递规则作为《len:{字符数}》。

一旦创建了验证器的类，就可以通过调用《$hird->registerValidator('rule-name', YourValidator::class)》来注册它。