README

PHP独立数据验证库。受Laravel的Illuminate\Validation启发。

功能

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

要求

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

快速入门

安装

composer require "rakit/validation"

使用

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

使用make

<?php

require('vendor/autoload.php');

use Rakit\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 Rakit\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。

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

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

为验证器设置自定义消息

使用这种方法，每次您使用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", 或 "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"，您可能需要将其翻译。

与错误消息一起工作

错误信息被收集在 Rakit\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://localhost/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
        }
    ]
]);

注册/覆盖规则

使用自定义验证规则的另一种方法是创建一个扩展Rakit\Validation\Rule的类。然后使用setValidator或addValidator进行注册。

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

首先，让我们创建UniqueRule类

<?php

use Rakit\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 Rakit\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方法（在Rakit\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 Rakit\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 Rakit\Validation\Rule;

class YourCustomRule extends Rule
{

    protected $implicit = true;

}

修改值

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

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

例如

<?php

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

class YourCustomRule extends Rule implements ModifyValue
{
    ...

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

        return $value;
    }

    ...
}

验证前钩子

您可能在验证运行之前想要做一些准备工作。例如，我们的 uploaded_file 规则将解析来自 $_FILES（不理想的）数组结构的属性值，将其转换为有组织的数组结构，这样我们就可以像验证其他数据一样验证多个文件上传。

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

例如

<?php

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

class YourCustomRule extends Rule implements BeforeValidate
{
    ...

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

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

    ...
}