README

简单的输入验证。

使用方法

本库包含两个组件。一组验证方法和一个输入验证引擎。

验证器

可以使用 Validator 类快速验证单个输入。

include 'vendor/autoload.php';

use werx\Validation\Validator;

$input = 'foo';
$valid = Validator::minlength($input, 4);
var_dump($valid);

/*
bool(true)
*/

以下验证器可用。每个验证器返回一个布尔值：true = 通过验证，false = 未通过验证。

bool required (mixed $input)
bool date (mixed $input [, $input_format = MM/DD/YYYY])
	# Other input formats available YYYY/MM/DD, YYYY-MM-DD, YYYY/DD/MM, YYYY-DD-MM, DD-MM-YYYY, DD/MM/YYYY, MM-DD-YYYY, MM/DD/YYYY, YYYYMMDD, YYYYDDMM
bool minlength(mixed $input, int $min)
bool maxlength(mixed $input, int $max)
bool exactlength(mixed $input, int $length)
bool greaterthan($input, int $min)
bool lessthan(mixed $input, int $max)
bool alpha(mixed $input)
bool alphanumeric(mixed $input)
bool integer(mixed $input)
bool float(mixed $input)
bool numeric(mixed $input)
bool email(mixed $input)
bool url(mixed $input)
bool phone(mixed $input)
bool zipcode(mixed $input)
bool startswith(mixed $input, string $match)
bool endswith(mixed $input, string $match)
bool contains(mixed $input, string $match)
bool regex(mixed $input, string $regex)
bool inlist(mixed $input, array $list)

验证引擎

验证引擎用于验证一组数据与一组规则。

使用方法

首先，获取验证引擎的实例

use werx\Validation\Engine as ValidationEngine;

$validator = new ValidationEngine;

然后添加规则

$validator->addRule('firstname', 'First Name', 'required|minlength[2]|alpha');

参数

• 要验证的表单输入名称 / 数组键
• 元素的友好标签
• 用管道分隔的规则列表
  • 每个规则对应于 Validator 类中的方法名
  • 如果方法接受参数，则参数应在规则名之后用方括号括起来
    • 示例： minlength[2]
    • 异常：接受数组作为参数的方法应在规则名之后用大括号括起来。
      • 示例： inlist{red,white,blue}
  • 除了 required 验证器外，所有验证器如果输入为空都会返回 true。
    • 换句话说，minlength[2] 只有在添加 required 规则时才会实际触发。

现在您可以获取验证结果。

$valid = $validator->validate($_POST);

验证输入数组

有时您不是使用简单的字符串作为输入字段名称。假设您的 HTML 输入表单如下所示

<input type="text" name="volunteer[name]">
<input type="text" name="volunteer[email]">

在此场景下创建规则时，请将数组名称和键名称用点分隔。

$validator->addRule('volunteer.name', 'Name', 'required|minlength[2]|alpha');
$validator->addRule('volunteer.email', 'Email Address', 'required|email');

闭包

除了 Validator 类中的预定义验证方法外，您还可以使用 闭包 创建自定义验证方法。

$closure = function ($data, $id, $label) {
	$message = null;
	$success = $data[$id] == 'Foo';
	
	if (!$success) {
		$message = sprintf('%s must equal "Foo"', $label);
	}
	
	return [$success, $message];
};

$validator->addRule('firstname', 'First Name', $closure);

$valid = $validator->validate($_POST);

闭包将接收三个值

1. 正在验证的完整数据集。
2. 正在验证的元素的 ID。
3. 正在验证的元素的标签。

闭包应返回一个数组。

• 数组的第一个元素应该是验证结果（bool）。
• 数组的第二个元素应该是如果验证失败要显示的错误消息。
  • 如果验证通过，消息可以为 null。

规则集

如果您想保存一组规则而不是每次验证时都单独添加每个规则，我们已为您做好准备。

创建一个扩展 werx\Validation\Ruleset 的新类，并在构造函数中添加您的规则。

namespace your\namespace\Rulesets;

use werx\Validation\Ruleset;

class Contact extends Ruleset
{
	public function __construct()
	{
		$this->addRule('firstname', 'First Name', 'required|minlength[2]');
		$this->addRule('lastname', 'Last Name', 'required');
		$this->addRule('phone', 'Phone Number', 'required|phone');
		$this->addRule('email', 'Email Address', 'required|email');
	}
}

然后，当您准备好验证这组规则时

$contact_rules = new your\namespace\Rulesets\Contact;
$validator->addRuleset($contact_rules);
$valid = $validator->validate();

实用方法

有几个实用方法可以使处理验证结果变得更加容易。

getErrorSummary()

返回一个简单数组，其中包含验证错误消息列表。

if (!$valid) {
	$summary = $validator->getErrorSummary();
}

/*
Array
(
	[0] => First Name must only contain the letters A-Z.
	[1] => First Name must be at least 2 characters long.
	[2] => Last Name is a required field.
)
*/

getErrorSummaryFormatted()

返回格式化为 HTML 无序列表（<ul>）的错误摘要。

getErrorFields()

返回有错误的字段列表。如果您想为有验证错误的字段在表单上应用一些装饰，这很有用。

if (!$valid) {
	$error_fields = $validator->getErrorFields();
}

/*
Array
(
	[0] => firstname
	[1] => lastname
)
*/

getRequiredFields()

添加规则后，您可以获取所需字段的列表。当您想在表单上标记哪些字段必须填写时，这非常有用。

$validator->addRule('firstname', 'First Name', 'required');
$validator->addRule('lastname', 'Last Name', 'required');
$validator->addRule('age', 'Age', 'required|integer');

$required = $validator->getRequiredFields();

/*
Array
(
	[0] => firstname
	[1] => lastname
	[2] => age
)
*/

addCustomMessage()

允许您设置自定义错误信息。

在显示错误信息时，{name}将被替换为正在验证的字段名称。其余字段将使用sprintf()进行解析，以便将像minlength这样的参数放置在返回的错误信息中。

示例

$validator->addCustomMessage('required', "You didn't provide a value for {name}!");
$validator->addCustomMessage('minlength', "Oops, {name} must be at least %d characters long.");

安装

该软件包可以通过Composer以werx/validation的方式安装和自动加载。如果您不熟悉PHP的Composer依赖管理器，您应该先阅读这个。

$ composer require werx/validation --prefer-dist

贡献

单元测试

$ vendor/bin/phpunit

编码标准

此库使用PHP_CodeSniffer来确保遵循编码标准。

我采用了PHP FIG PSR-2编码标准，除了缩进时使用制表符或空格的规则。PSR-2说使用4个空格。我使用制表符。没有讨论。

为了支持使用制表符缩进，我定义了一个自定义的PSR-2规则集，它扩展了由PHP_CodeSniffer使用的标准PSR-2规则集。您可以在该项目的根目录下找到此规则集，文件名为PSR2Tabs.xml。

从该项目的根目录执行codesniffer命令，使用这些自定义规则运行检查器。

$ ./codesniffer