README

受 Laravel 验证启发的 PHP 独立库，用于验证数据

这是一个基于由 Rakit 编写的原始库的分支，并进行了更多改进和更改。

特性

• 类似 Laravel 验证的 API。
• 数组验证。
• $_FILES 验证，支持多个文件。
• 自定义属性别名。
• 自定义验证消息。
• 自定义规则。

要求

• PHP 7.0 或更高版本
• Composer 用于安装

快速开始

安装

composer require ignitekit/validation

用法

使用此库验证数据有两种方式。使用 make 创建验证对象，然后使用 validate 进行验证。或者直接使用 validate。示例

使用 make

<?php

require('vendor/autoload.php');

use IgniteKit\Validation\Validator;

$validator = new Validator;

// make it
$validation = $validator->make($_POST + $_FILES, [
    'name'                  => 'required',
    'email'                 => 'required|email',
    'password'              => 'required|min:6',
    'confirm_password'      => 'required|same:password',
    'avatar'                => 'required|uploaded_file:0,500K,png,jpeg',
    'skills'                => 'array',
    'skills.*.id'           => 'required|numeric',
    'skills.*.percentage'   => 'required|numeric'
]);

// then validate
$validation->validate();

if ($validation->fails()) {
    // handling errors
    $errors = $validation->errors();
    echo "<pre>";
    print_r($errors->firstOfAll());
    echo "</pre>";
    exit;
} else {
    // validation passes
    echo "Success!";
}

或直接 validate

<?php

require('vendor/autoload.php');

use IgniteKit\Validation\Validator;

$validator = new Validator;

$validation = $validator->validate($_POST + $_FILES, [
    'name'                  => 'required',
    'email'                 => 'required|email',
    'password'              => 'required|min:6',
    'confirm_password'      => 'required|same:password',
    'avatar'                => 'required|uploaded_file:0,500K,png,jpeg',
    'skills'                => 'array',
    'skills.*.id'           => 'required|numeric',
    'skills.*.percentage'   => 'required|numeric'
]);

if ($validation->fails()) {
	// handling errors
	$errors = $validation->errors();
	echo "<pre>";
	print_r($errors->firstOfAll());
	echo "</pre>";
	exit;
} else {
	// validation passes
	echo "Success!";
}

在这种情况下，上述两个示例将输出相同的结果。

但使用 make，你可以在验证运行之前设置一些内容，例如自定义无效消息、自定义属性别名等。

属性别名

默认情况下，我们将您的属性转换为更易读的文本。例如 confirm_password 将显示为 Confirm password。但您可以使用 setAlias 或 setAliases 方法将其设置为任何您想要的内容。

示例

$validator = new Validator;

// To set attribute alias, you should use `make` instead `validate`.
$validation->make([
	'province_id' => $_POST['province_id'],
	'district_id' => $_POST['district_id']
], [
	'province_id' => 'required|numeric',
	'district_id' => 'required|numeric'
]);

// now you can set aliases using this way:
$validation->setAlias('province_id', 'Province');
$validation->setAlias('district_id', 'District');

// or this way:
$validation->setAliases([
	'province_id' => 'Province',
	'district_id' => 'District'
]);

// then validate it
$validation->validate();

现在如果 province_id 的值为空，错误消息将是 'Province is required'。

自定义验证消息

在注册/设置自定义消息之前，这里有一些您可以在自定义消息中使用的变量

• :attribute: 将替换为属性别名。
• :value: 将替换为属性值的字符串化版本。对于数组和对象，将替换为 JSON。

此外，还有一些根据其规则的消息变量。

以下是一些注册/设置您自定义消息的方式

Validator 的自定义消息

使用这种方法，每次您使用 make 或 validate 进行验证时，它都会设置您的自定义消息。这对于本地化非常有用。

为此，您可以将自定义消息作为构造函数的第一个参数设置，如下所示

$validator = new Validator([
	'required' => ':attribute harus diisi',
	'email' => ':email tidak valid',
	// etc
]);

// then validation belows will use those custom messages
$validation_a = $validator->validate($dataset_a, $rules_for_a);
$validation_b = $validator->validate($dataset_b, $rules_for_b);

或使用 setMessages 方法如下

$validator = new Validator;
$validator->setMessages([
	'required' => ':attribute harus diisi',
	'email' => ':email tidak valid',
	// etc
]);

// now validation belows will use those custom messages
$validation_a = $validator->validate($dataset_a, $rules_for_dataset_a);
$validation_b = $validator->validate($dataset_b, $rules_for_dataset_b);

验证的自定义消息

有时您可能想要为特定验证设置自定义消息。为此，您可以将自定义消息设置为 $validator->make 或 $validator->validate 的第三个参数，如下所示

$validator = new Validator;

$validation_a = $validator->validate($dataset_a, $rules_for_dataset_a, [
	'required' => ':attribute harus diisi',
	'email' => ':email tidak valid',
	// etc
]);

或您可以使用 $validation->setMessages 如此

$validator = new Validator;

$validation_a = $validator->make($dataset_a, $rules_for_dataset_a);
$validation_a->setMessages([
	'required' => ':attribute harus diisi',
	'email' => ':email tidak valid',
	// etc
]);

...

$validation_a->validate();

特定属性规则的自定义消息

有时您可能想要为特定规则属性设置自定义消息。为此，您可以使用冒号 : 作为消息分隔符或使用链式方法。

示例

$validator = new Validator;

$validation_a = $validator->make($dataset_a, [
	'age' => 'required|min:18'
]);

$validation_a->setMessages([
	'age:min' => '18+ only',
]);

$validation_a->validate();

或使用链式方法

$validator = new Validator;

$validation_a = $validator->make($dataset_a, [
	'photo' => [
		'required',
		$validator('uploaded_file')->fileTypes('jpeg|png')->message('Photo must be jpeg/png image')
	]
]);

$validation_a->validate();

翻译

翻译与自定义消息不同。翻译可能在您使用自定义消息进行 in、not_in、mimes 和 uploaded_file 规则时需要。

例如，如果您使用规则 in:1,2,3，我们将设置无效消息为 "The Attribute only allows '1', '2', or '3'"，其中部分 "'1', '2', or '3'" 来自 ":allowed_values" 标签。因此，如果您有自定义印度尼西亚语消息 ":attribute hanya memperbolehkan :allowed_values"，我们将设置无效消息为 "Attribute hanya memperbolehkan '1', '2', or '3'"，其中 "or" 一词不是印尼语的一部分。

因此，为了解决这个问题，我们可以使用翻译如下

// Set translation for words 'and' and 'or'.
$validator->setTranslations([
    'and' => 'dan',
    'or' => 'atau'
]);

// Set custom message for 'in' rule
$validator->setMessage('in', ":attribute hanya memperbolehkan :allowed_values");

// Validate
$validation = $validator->validate($inputs, [
    'nomor' => 'in:1,2,3'
]);

$message = $validation->errors()->first('nomor'); // "Nomor hanya memperbolehkan '1', '2', atau '3'" 

实际上，我们的内置规则只使用单词 'and' 和 'or'，您可能需要将其翻译。

与错误消息一起工作

错误信息收集在 IgniteKit\Validation\ErrorBag 对象中，您可以通过 errors() 方法获取它。

$validation = $validator->validate($inputs, $rules);

$errors = $validation->errors(); // << ErrorBag

现在您可以使用以下方法来检索错误信息

all(string $format = ':message')

获取所有消息作为一个扁平数组。

示例

$messages = $errors->all(); 
// [
//     'Email is not valid email',
//     'Password minimum 6 character',
//     'Password must contains capital letters'
// ]

$messages = $errors->all('<li>:message</li>');
// [
//     '<li>Email is not valid email</li>',
//     '<li>Password minimum 6 character</li>',
//     '<li>Password must contains capital letters</li>'
// ]

firstOfAll(string $format = ':message', bool $dotNotation = false)

从所有现有键中只获取第一个消息。

示例

$messages = $errors->firstOfAll(); 
// [
//     'email' => Email is not valid email',
//     'password' => 'Password minimum 6 character',
// ]

$messages = $errors->firstOfAll('<li>:message</li>');
// [
//     'email' => '<li>Email is not valid email</li>',
//     'password' => '<li>Password minimum 6 character</li>',
// ]

参数 $dotNotation 用于数组验证。如果它为 false，则返回原始数组结构；如果为 true，则返回使用点表示法的扁平数组。

例如

$messages = $errors->firstOfAll(':message', false); 
// [
//     'contacts' => [
//          1 => [
//              'email' => 'Email is not valid email',
//              'phone' => 'Phone is not valid phone number'
//          ],
//     ],
// ]

$messages = $errors->firstOfAll(':message', true);
// [
//     'contacts.1.email' => 'Email is not valid email',
//     'contacts.1.phone' => 'Email is not valid phone number',
// ]

first(string $key)

从给定键获取第一个消息。如果键有错误消息，则返回 string；如果没有错误，则返回 null。

例如

if ($emailError = $errors->first('email')) {
    echo $emailError;
}

toArray()

按键分组获取所有消息。

例如

$messages = $errors->toArray();
// [
//     'email' => [
//         'Email is not valid email'
//     ],
//     'password' => [
//         'Password minimum 6 character',
//         'Password must contains capital letters'
//     ]
// ]

count()

获取消息数量。

has(string $key)

检查给定的键是否有错误。如果键有错误，则返回 bool，否则返回其他值。

获取已验证、有效和无效数据

例如，您有以下验证：

$validation = $validator->validate([
    'title' => 'Lorem Ipsum',
    'body' => 'Lorem ipsum dolor sit amet ...',
    'published' => null,
    'something' => '-invalid-'
], [
    'title' => 'required',
    'body' => 'required',
    'published' => 'default:1|required|in:0,1',
    'something' => 'required|numeric'
]);

您可以使用以下示例中的方法获取验证数据、有效数据或无效数据

$validatedData = $validation->getValidatedData();
// [
//     'title' => 'Lorem Ipsum',
//     'body' => 'Lorem ipsum dolor sit amet ...',
//     'published' => '1' // notice this
//     'something' => '-invalid-'
// ]

$validData = $validation->getValidData();
// [
//     'title' => 'Lorem Ipsum',
//     'body' => 'Lorem ipsum dolor sit amet ...',
//     'published' => '1'
// ]

$invalidData = $validation->getInvalidData();
// [
//     'something' => '-invalid-'
// ]

可用规则

点击显示详细信息。

<input type="file" name="photos[]"/>
<input type="file" name="photos[]"/>
<input type="file" name="photos[]"/>

$validation = $validator->validate($_FILES, [
    'photos.*' => 'uploaded_file:0,2M,jpeg,png'
]);

// or

$validation = $validator->validate($_FILES, [
    'photos.*' => 'uploaded_file|max:2M|mimes:jpeg,png'
]);

<input type="file" name="images[profile]"/>
<input type="file" name="images[cover]"/>

$validation = $validator->validate($_FILES, [
    'images.*' => 'uploaded_file|max:2M|mimes:jpeg,png',
]);

// or

$validation = $validator->validate($_FILES, [
    'images.profile' => 'uploaded_file|max:2M|mimes:jpeg,png',
    'images.cover' => 'uploaded_file|max:5M|mimes:jpeg,png',
]);

$validation = $validator->validate([
    'enabled' => null
], [
    'enabled' => 'default:1|required|in:0,1'
    'published' => 'default:0|required|in:0,1'
]);

$validation->passes(); // true

// Get the valid/default data
$valid_data = $validation->getValidData();
$enabled = $valid_data['enabled'];
$published = $valid_data['published'];

$validation = $validator->validate($data, [
    'enabled' => [
        'required', 
        $validator('in', [true, 1])->strict()
    ]
]);

$validation = $validator->validate([
    'photo' => $_FILES['photo']
], [
    'photo' => 'required|min:1M'
]);

$validation = $validator->validate([
    'photo' => $_FILES['photo']
], [
    'photo' => 'required|max:2M'
]);

$validation = $validator->validate([
    'photo' => $_FILES['photo']
], [
    'photo' => 'required|between:1M,2M'
]);

$validation = $validator->validate($inputs, [
    'random_url' => 'url',          // value can be `any_scheme://...`
    'https_url' => 'url:http',      // value must be started with `https://`
    'http_url' => 'url:http,https', // value must be started with `http://` or `https://`
    'ftp_url' => 'url:ftp',         // value must be started with `ftp://`
    'custom_url' => 'url:custom',   // value must be started with `custom://`
    'mailto_url' => 'url:mailto',   // value must conatin valid mailto URL scheme like `mailto:a@mail.com,b@mail.com`
    'jdbc_url' => 'url:jdbc',       // value must contain valid jdbc URL scheme like `jdbc:mysql:///dbname`
]);

$validation = $validator->validate($_POST, [
    'even_number' => [
        'required',
        function ($value) {
            // false = invalid
            return (is_numeric($value) AND $value % 2 === 0);
        }
    ]
]);

$validation = $validator->validate($_POST, [
    'even_number' => [
        'required',
        function ($value) {
            if (!is_numeric($value)) {
                return ":attribute must be numeric.";
            }
            if ($value % 2 !== 0) {
                return ":attribute is not even number.";
            }
            // you can return true or don't return anything if value is valid
        }
    ]
]);

注册/覆盖规则

使用自定义验证规则的一种方法是创建一个继承自IgniteKit\Validation\Rule的类。然后使用setValidator或addValidator来注册它。

例如，你想创建一个unique验证器，用来从数据库中检查字段的可用性。

首先，让我们创建UniqueRule类

<?php

use IgniteKit\Validation\Rule;

class UniqueRule extends Rule
{
    protected $message = ":attribute :value has been used";
    
    protected $fillableParams = ['table', 'column', 'except'];
    
    protected $pdo;
    
    public function __construct(PDO $pdo)
    {
        $this->pdo = $pdo;
    }
    
    public function check($value): bool
    {
        // make sure required parameters exists
        $this->requireParameters(['table', 'column']);
    
        // getting parameters
        $column = $this->parameter('column');
        $table = $this->parameter('table');
        $except = $this->parameter('except');
	
        if ($except AND $except == $value) {
            return true;
        }
	
        // do query
        $stmt = $this->pdo->prepare("select count(*) as count from `{$table}` where `{$column}` = :value");
        $stmt->bindParam(':value', $value);
        $stmt->execute();
        $data = $stmt->fetch(PDO::FETCH_ASSOC);
	
        // true for valid, false for invalid
        return intval($data['count']) === 0;
    }
}

然后你需要将UniqueRule实例注册到验证器中，如下所示

use IgniteKit\Validation\Validator;

$validator = new Validator;

$validator->addValidator('unique', new UniqueRule($pdo));

现在你可以这样使用它

$validation = $validator->validate($_POST, [
    'email' => 'email|unique:users,email,exception@mail.com'
]);

在上面的UniqueRule中，属性$message用于默认的无效消息。属性$fillable_params用于fillParameters方法（在IgniteKit\Validation\Rule类中定义）。默认情况下，fillParameters将填充$fillable_params中列出的参数。例如，上面的示例中的unique:users,email,exception@mail.com将设置

$params['table'] = 'users';
$params['column'] = 'email';
$params['except'] = 'exception@mail.com';

如果你想让你的自定义规则接受类似in、not_in或uploaded_file规则的参数列表，你只需要在你的自定义规则类中重写fillParameters(array $params)方法。

注意，我们上面创建的unique规则也可以这样使用

$validation = $validator->validate($_POST, [
    'email' => [
    	'required', 'email',
    	$validator('unique', 'users', 'email')->message('Custom message')
    ]
]);

所以你可以通过添加一些返回其自身实例的方法来改进上面的UniqueRule类

<?php

use IgniteKit\Validation\Rule;

class UniqueRule extends Rule
{
    ...
    
    public function table($table)
    {
        $this->params['table'] = $table;
        return $this;
    }
    
    public function column($column)
    {
        $this->params['column'] = $column;
        return $this;
    }
    
    public function except($value)
    {
        $this->params['except'] = $value;
        return $this;
    }
    
    ...
}

然后你可以用这种方式使用它

$validation = $validator->validate($_POST, [
    'email' => [
    	'required', 'email',
    	$validator('unique')->table('users')->column('email')->except('exception@mail.com')->message('Custom message')
    ]
]);

隐式规则

隐式规则是一个规则，如果它无效，则忽略后续规则。例如，如果属性没有通过required*规则，那么大多数情况下，后续规则也将无效。因此，为了防止我们的后续规则消息被收集，我们将required*规则设置为隐式。

要使你的自定义规则成为隐式，你可以将$implicit属性值设置为true。例如

<?php

use IgniteKit\Validation\Rule;

class YourCustomRule extends Rule
{

    protected $implicit = true;

}

修改值

在某些情况下，你可能希望你的自定义规则能够修改其属性值，就像我们的default/defaults规则一样。因此，在当前和后续规则检查中，将使用你的修改后的值。

为此，你应该实现IgniteKit\Validation\Rules\Interfaces\ModifyValue并在你的自定义规则类中创建一个名为modifyValue($value)的方法。

例如

<?php

use IgniteKit\Validation\Rule;
use IgniteKit\Validation\Rules\Interfaces\ModifyValue;

class YourCustomRule extends Rule implements ModifyValue
{
    ...

    public function modifyValue($value)
    {
        // Do something with $value

        return $value;
    }

    ...
}

在验证之前

你可能想在验证运行之前做一些准备工作。例如，我们的uploaded_file规则会将来自$_FILES（不希望的）数组的结构解析为良好的组织结构，这样我们就可以像验证其他数据一样验证多个文件上传。

为此，你应该实现IgniteKit\Validation\Rules\Interfaces\BeforeValidate并在你的自定义规则类中创建一个名为beforeValidate()的方法。

例如

<?php

use IgniteKit\Validation\Rule;
use IgniteKit\Validation\Rules\Interfaces\BeforeValidate;

class YourCustomRule extends Rule implements BeforeValidate
{
    ...

    public function beforeValidate()
    {
        $attribute = $this->getAttribute(); // IgniteKit\Validation\Attribute instance
        $validation = $this->validation; // IgniteKit\Validation\Validation instance

        // Do something with $attribute and $validation
        // For example change attribute value
        $validation->setValue($attribute->getKey(), "your custom value");
    }

    ...
}