README

icanboogie/validate 包提供了一种简单的 API 用于数据验证。

以下是一些可用的验证器

标志
- Required, required: 表示值是必需的。应首先指定。
通用
- Blank, blank: 验证值是否为空。
- NotBlank, not-blank: 验证值是否不为空。
类型比较
- Boolean, boolean: 验证值是否为布尔值。
- IsFalse, is-false: 验证值是否为假。
- IsNull, is-null: 验证值是否为 null。
- NotNull, not-null: 验证值是否不为 null。
- IsTrue, is-true: 验证值是否为真。
- Type, type: 验证值是否为指定类型。
引用比较
- Equal, equal: 验证两个值是否相等。
- NotEqual, not-equal: 验证两个值是否不相等。
- Identical, identical: 验证两个值是否相同。
- NotIdentical, not-identical: 验证两个值是否不相同。
- Max, max: 验证值是否有一个最大值。
- MaxLength, max-length: 验证值是否有一个最大长度。
- Min, min: 验证值是否有一个最小值。
- MinLength, min-length: 验证值是否有一个最小长度。
范围比较
- Between, between: 验证值是否在两个引用之间。
- NotBetween, not-between: 验证值是否不在两个引用之间。
- BetweenLength，between-length：验证字符串长度是否介于两个参考值之间。
- NotBetweenLength，not-between-length：验证字符串长度是否不介于两个参考值之间。
字符串比较
- Email，email：验证值是否为有效的电子邮件。
- JSON，json：验证值是否为有效的JSON。
- Regex，regex：验证值是否与模式匹配或不匹配。
- TimeZone，timezone：验证值是否为有效的时区。
- URL，url：验证值是否为有效的URL。

以下示例演示了如何验证数据

<?php

use ICanBoogie\Validate\Validation;
use ICanBoogie\Validate\Reader\ArrayAdapter;

$validation = new Validation([
	'name' => 'required|min-length:3',
	'email' => 'required|email!|unique',
	'password' => 'required|min-length:6',
	'consent' => 'required',
]);

$errors = $validation->validate(new ArrayAdapter([
	'name' => "Ol",
	'email' => "olivier",
	'password' => "123",
]));

var_dump($errors['name']);
var_dump((string) reset($errors['name']));

array(1) {
  [0] =>
  class ICanBoogie\Validate\Message#582 (2) {
    public $format =>
    string(46) "should be at least {reference} characters long"
    public $args =>
    array(4) {
      'attribute' =>
      string(4) "name"
      'value' =>
      string(2) "Ol"
      'validator' =>
      string(39) "ICanBoogie\Validate\Validator\MinLength"
      'reference' =>
      string(1) "3"
    }
  }
}
string(36) "should be at least 3 characters long"

验证

使用键值对数组定义验证，其中键是验证的属性，值是规则。规则可以定义为字符串或键值对数组，其中键是验证器类或别名，值是参数和选项数组。可选地，您可以提供验证器提供者，如果没有提供，则默认创建一个BuiltinValidatorProvider实例。

验证由一个Validation实例表示。

<?php

use ICanBoogie\Validate\Validation;

$validation = new Validation([
	'name' => 'required|min-length:3',
]);

# or

$validation = new Validation([
	'name' => [
		'required' => [],
		'min-length' => [ 3 ],
	]
]);

# or

use ICanBoogie\Validate\Validator;

$validation = new Validation([
	'name' => [
		Validator\Required::class => [],
		Validator\MinLength::class => [ 3 ],
	]
]);

# or

$validation = new Validation([
	'name' => [
		Validator\Required::class => [],
		Validator\MinLength::class => [ Validator\MinLength::PARAM_REFERENCE => 3 ],
	]
]);

空值，必填属性

请注意，验证器不会在空值上运行，除非同时使用了required验证器。以下值被认为是空：null、空数组、空剪裁字符串；但false和0被认为是有效值。

以下示例演示了required如何影响验证

<?php

use ICanBoogie\Validate\Reader\ArrayAdapter;
use ICanBoogie\Validate\Validation;

$validation = new Validation([

	'required_tz' => 'required|timezone',
	'optional_tz' => 'timezone',

]);

$errors =$validation->validate(new ArrayAdapter([

	'required_tz' => '',
	'optional_tz' => '',

]));

isset($errors['required_tz']); // true
isset($errors['optional_tz']); // false

验证数据

validate()方法验证数据。如果验证失败，则返回一个ValidationErrors实例，否则返回一个空数组。

<?php

use ICanBoogie\Validate\Reader\RequestAdapter;
use ICanBoogie\Validate\Validation;

/* @var $validation Validation */

$errors = $validation->validate(new RequestAdapter($_POST));

if (!$errors)
{
	// because `$errors` is an empty array we can check if it is empty with `!`.
}

foreach ($errors as $attribute => $messages)
{
	// …
}

断言数据有效

可以使用assert()方法断言数据有效。与validate()方法返回一个ValidationErrors实例不同，该方法会抛出一个ValidationFailed异常。可以使用异常的errors属性检索验证错误。

<?php

use ICanBoogie\Validate\Validation;
use ICanBoogie\Validate\ValidationFailed;
use ICanBoogie\Validate\Reader\RequestAdapter;

/* @var $validation Validation */

try
{
	$validation->assert(new RequestAdapter($_POST));
}
catch (ValidationFailed $e)
{
	echo get_class($e->errors); // ICanBoogie\Validate\ValidationErrors
}

特殊验证选项

以下验证选项可以定义：

ValidatorOptions::OPTION_MESSAGE：自定义错误消息，该消息覆盖验证器默认消息。
ValidatorOptions::OPTION_IF：只有当此选项定义的可调用返回true时，验证器才会使用。可调用可以是闭包或实现IfCallable接口的实例。
ValidatorOptions::OPTION_UNLESS：如果此选项定义的可调用返回true，则跳过验证器。可调用可以是闭包或实现UnlessCallable接口的实例。
ValidatorOptions::OPTION_STOP_ON_ERROR：如果为true，则在发生错误后停止验证值的验证。对于Required验证器，此选项始终为true。

<?php

use ICanBoogie\Validate\Context;
use ICanBoogie\Validate\Validation;
use ICanBoogie\Validate\Validator\Required;
use ICanBoogie\Validate\Validator\Email;

$validation = new Validation([
	'email' => [
		Required::class => [
			Required::OPTION_MESSAGE => "An email address must be supplied if your wish to register.",
			Required::OPTION_IF => function(Context $context) {
				return $context->value('name');
			},
			Required::OPTION_UNLESS => function(Context $context) {
				return !$context->value('register');
			},
			Required::OPTION_STOP_ON_ERROR => true // already defined by Require
		],
		Email::class => [
			Email::OPTION_MESSAGE => "`{value}` is an invalid email address for the field E-Mail.",
		]
	]
]);

验证上下文

验证上下文由一个Context实例表示，并与要验证的值一起传递给验证器。验证器可以使用上下文来检索参数和选项，并在需要时获取正在进行验证的完整情况。

以下属性可用

attribute：正在验证的属性。
value：正在验证的属性的值。
validator：当前验证器。
validator_params：当前验证器的参数和选项。
reader：一个Reader适配器，提供对正在验证的值的访问。
message：当前验证器的可能错误消息。
message_args：可能错误消息的参数。
errors：收集到的错误。

以下示例演示了验证器如何从上下文中检索其参数和选项，以及如何从值读取器中检索一个值

<?php

use ICanBoogie\Validate\Context;
use ICanBoogie\Validate\Validator\ValidatorAbstract;

class SampleValidator extends ValidatorAbstract
{
	const PARAM_REFERENCE = 'reference';
	const OPTION_STRICT = 'strict';

	/**
	 * @inheritdoc
	 */
	public function validate($value, Context $context)
	{
		$reference = $context->param(self::PARAM_REFERENCE);
		$strict = $context->option(self::OPTION_STRICT, false);
		$other_value = $context->value('some_other_value');
	}
}

验证器提供程序

通过使用验证器提供程序来获取验证器实例。默认情况下，使用BuiltinValidatorProvider的实例，但您可以提供自己的提供程序，或者更好的是，一个提供程序集合。

以下示例演示了如何使用内置提供程序

<?php

use ICanBoogie\Validate\Validation;
use ICanBoogie\Validate\ValidatorProvider\BuiltinValidatorProvider;

/* @var $rules array */

$builtin_validator_provider = new BuiltinValidatorProvider;
$validation = new Validation($rules, $builtin_validator_provider);

# or

$validation = new Validation($rules);

以下示例演示了如何提供自己的sample验证器

<?php

use ICanBoogie\Validate\UndefinedValidator;
use ICanBoogie\Validate\Validation;
use ICanBoogie\Validate\Validator;

/* @var $sample_validator Validator */

$rules = [ 'attribute' => $sample_validator::ALIAS ];
$sample_validator_provider = function ($class_or_alias) use ($sample_validator) {

	switch ($class_or_alias)
	{
		case get_class($sample_validator):
		case $sample_validator::ALIAS:
			return $sample_validator;

		default:
			throw new UndefinedValidator($class_or_alias);
	}

};

$validation = new Validation($rules, $sample_validator_provider);

以下示例演示了如何使用容器提供验证器

<?php

use ICanBoogie\Validate\Validation;
use ICanBoogie\Validate\ValidatorProvider\ContainerValidatorProvider;
use Psr\Container\ContainerInterface;

/* @var $rules array */
/* @var $container ContainerInterface */

$prefix = 'validator.';
$container_validator_provider = new ContainerValidatorProvider($container, $prefix);

$validation = new Validation($rules, $container_validator_provider);

以下示例演示了如何将多个提供程序作为集合使用

<?php

use ICanBoogie\Validate\Validation;
use ICanBoogie\Validate\ValidatorProvider\BuiltinValidatorProvider;
use ICanBoogie\Validate\ValidatorProvider\ContainerValidatorProvider;
use ICanBoogie\Validate\ValidatorProvider\ValidatorProviderCollection;

/* @var $rules array */
/* @var $container_validator_provider ContainerValidatorProvider */
/* @var $sample_validator_provider callable */
/* @var $builtin_validator_provider BuiltinValidatorProvider */

$validator_provider_collection = new ValidatorProviderCollection([

	$container_validator_provider,
	$sample_validator_provider,
	$builtin_validator_provider,

]);
 
$validation = new Validation($rules, $validator_provider_collection);

要求

此包需要PHP 5.5或更高版本。

安装

安装此包的推荐方法是使用Composer。

$ composer require icanboogie/validate

克隆存储库

该包可在GitHub上找到，其存储库可以使用以下命令行克隆

$ git clone https://github.com/ICanBoogie/validate.git

文档

该包作为ICanBoogie框架的一部分进行文档记录。文档。您可以使用make doc命令生成包及其依赖项的文档。文档生成在build/docs目录中。ApiGen是必需的。可以使用make clean命令清理该目录。

测试

使用make test命令运行测试套件。PHPUnit和Composer需要全局可用才能运行套件。该命令根据需要安装依赖项。使用make test-coverage命令运行测试套件，并在build/coverage中创建HTML覆盖率报告。可以使用make clean命令清理该目录。

该包由Travis CI持续测试。

许可证

icanboogie/validate受新BSD许可证的许可 - 有关详细信息，请参阅LICENSE文件。

icanboogie / validate

维护者

详细信息