htmlburger/carbon-validator

作为独立库实现的基类验证器。受 Laravel 验证模块启发。

维护者

详情

bitbucket.org/htmlburger/carbon-validator

主页

源代码

问题

安装次数: 5,908

依赖者: 2

建议者: 0

安全: 0

v1.2.0 2016-10-21 16:39 UTC

GPL-2.0 5a70c6cc1a29039ddad9500039b569ab3abc9c76

  • htmlBurger <info.woop@htmlburger.com>

This package is auto-updated.

Last update: 2024-08-29 04:39:59 UTC

README

PHP 输入数据验证库。

<?php
$validator = new Carbon_Validator($_POST, array(
	'name'    => 'required',
	'email'   => 'required|email',
	'message' => 'string_min_length:15|string_max_length:255'
));

if ($validator->fails()) {
	$errors = $validator->get_errors();
} else {
	send_mail_notification();
	header('Location: ?success');
}
?>
  1. 通过提交输入数据和验证规则来创建新对象
  2. 输入数据应该是类似于 $_POST 的关联数组。
  3. 验证规则是另一个关联数组，其中键是字段名，值是与该字段相关的所有规则。
  4. 我们可以通过调用方法 $validator->fails() 或 $validator->passes() 来检查数据是否有效。
  5. 我们可以通过 $validator->get_errors() 从验证器中提取自动生成的错误列表。
  6. 我们可以为特定字段和规则提交特定错误（以下为示例）

规则定义

每个字段都与一组验证规则相关联。它可以以字符串或数组的形式提交。当规则作为字符串提交时，它们通过管道符号（|）分隔

<?php
$validator = new Carbon_Validator($_POST, array(
	// The "customer_email" field is required and must be valid email
	'customer_email' => 'required|email' 
));
?>

当作为数组提交时，它必须按以下方式数字索引

<?php
$validator = new Carbon_Validator($_POST, array(
	'email' => array('required', 'email')
));
?>

每条规则本身由以下组成

  1. 名称（例如 string_min_length）
  2. 与名称分隔的参数（例如 :15 来自 string_min_length:15）

可用的验证规则

Carbon_Validator 随带一些验证规则包。要加载包，请使用以下静态方法

Carbon_Validator::load_package('wordpress');

包 generic（默认加载）

  • required - 字段必须有某种值
  • in:value1,value2,value3,... - 字段必须具有规则参数中提供的值之一
  • email - 有效的电子邮件地址（在括号内使用 PHP 的 filter_var 函数）
  • regex:/regex_body/i - 使用提供的正则表达式验证字段的值
  • numeric - 使用 PHP 的内置 is_numeric 函数通过值
  • string_min_length:value - 指定字段的最低长度
  • string_max_length:value - 指定字段的最高长度
  • numeric_min:value - 指定字段的最低数值
  • numeric_max:value - 指定字段的最高数值
  • url - 有效的 URL 地址（在括号内使用 PHP 的 filter_var 函数）
  • file:ext,ext2 - 确保上传了具有指定类型的文件。不检查文件的扩展名，而是检查其 MIME 类型
  • filesize:2M - 确保上传了小于指定大小（2MB）的文件。接受带有后缀 K（KB）的大小
  • email_exists - 检查是否存在具有该电子邮件地址的用户
  • user_exists - 检查是否存在具有该用户名的用户

包 wordpress

  • wp_nonce:action_name - 通过 wp_verify_nonce() 验证字段
  • wp_post:post_type1,post_type2 - 通过 get_post() 验证帖子 ID。可以选择添加 1 或多个帖子类型作为验证帖子的要求
  • wp_user:role_or_capability1,role_or_capability2 - 通过 get_userdata() 验证用户 ID。可以选择添加 1 或多个角色/权限作为验证用户的要求

存储/加载

您可以将 Carbon_Validator 实例保存并稍后加载。

Carbon_Validator::store('some_id', $validator);

$validator = Carbon_Validator::load('some_id');

示例

functions.php

<?php
add_action('template_redirect', 'crb_handle_contact_form');
function crb_handle_contact_form() {
	$is_contact_request = isset($_POST['action']) && $_POST['action'] === 'contact_form';

	if (!$is_contact_request) {
		return false;
	}

	$validator = new Carbon_Validator($_POST, array(
		"contact_name" => "required",
		"contact_email" => "required|email",
		"contact_message" => "required",
	));

	// Store the validator, so we can use it in the front-end
	Carbon_Validator::store('contact_form' , $validator);

	$success = $validator->passes();

	if ($success) {
		// Send email notification, or whatever. 
	}
}
?>

templates/contact.php

<?php
// Load the validator that was previously stored in functions.php
$validator = Carbon_Validator::load('contact_form');

// Check if the request is successful, otherwise output the errors
if ($validator): ?>
	<?php if ($validator->passes()): ?>
		<p class="alert alert-success"><?php _e('Your message has been sent.', 'crb'); ?></p> 
	<?php elseif ($errors = $validator->get_errors()): ?>
		<div class="alert alert-danger">
			<ul>
				<?php foreach ($errors as $error): ?>
					<li><?php echo esc_html($error) ?></li>
				<?php endforeach ?>
			</ul>
		</div>
	 <?php endif ?>
<?php endif; ?>

自定义错误消息

自动生成的验证错误在大多数情况下都能工作。然而，有时需要添加自定义错误信息。这可以通过类 Validator 构造函数的第三个参数来实现。

<?php
$rules = array(
	'name'    => 'required',
	'email'   => 'required|email',
	'message' => 'string_min_length:15|string_max_length:255'
);

$error_messages = array(
	'name.required' => 'We need your full name in order to contact you later. ',
	'message.string_min_length' => 'Your message is too short -- please enter more than 15 characters. ',
	'message.string_max_length' => 'Your message is too long -- please enter less than 255 characters. '
);

$validator = new Carbon_Validator($_POST, $rules, $error_messages);
?>

全局默认错误信息

要为所有 Carbon_Validator 实例添加或重写一条消息，可以使用以下静态方法。

// Carbon_Validator::register_default_error_message($rule, $message);
Carbon_Validator::register_default_error_message('required', 'You should really fill out the "%1$s" field.');

如果使用它，%1$s 将被替换为要验证的字段的用户友好名称。

此方法还允许您将消息传递给翻译函数（例如 WordPress 中的 __()、_e() 等）。

自定义验证规则

内置规则不一定足够。当需要进行更具体的验证时，我们可以做如下操作：

<?php
/**
 * Validates IP address and makes sure that it matches format "192.168.XXX.XXX"
 */
function validate_internal_ip_address($value) {
    if (!filter_var($value, FILTER_VALIDATE_IP)) {
    	return false;
    }
    $pieces = explode('.', $value);

    if (count($pieces) !== 4) {
    	return false;
    }

    if (intval($pieces[0]) !== 192 || intval($pieces[1]) !== 168) {
        return false;
    }

    return true;
}

// Bind the "internal_ip" validation rule to the "validate_internal_ip_address" callback function
Carbon_Validator::extend('internal_ip', 'validate_internal_ip_address');

# $_POST looks like:
# array(
# 	"name" => "John Doe",
# 	"ip-address" => "192.168.2.54",
# );

$rules = array(
	'ip-address' => 'required|internal_ip',
);

$messages = array(
	'ip-address.internal_ip' => 'Please enter valid internal IP addres. ',
);

$validator = new Carbon_Validator($_POST, $rules, $messages);
?>

扩展是通过静态方法 Carbon_Validator::extend($rule_name, $callback) 实现的。扩展后，$rule_name 可以在表单的验证规则中使用。

可以通过抛出特殊异常 Carbon_Validator_ValidationError 将错误传递给 Carbon_Validator 类。

自定义验证规则回调

传递给回调的参数包括

function my_custom_validation_rule_callback($value, $parameters, $field, $validator_instance) { };
  1. $value - 要验证的值
  2. $parameters - 作为规则参数传入的值数组（以逗号分隔的列表）
  3. $field - 要验证的字段
  4. $validator_instance - 调用此回调的验证器实例引用

文件验证

<?php
$data = array_merge($_POST, array(
	'avatar' => Carbon_FileUpload::make($_FILES['avatar'])
));

$validator = new Carbon_Validator($data, array(
    'name' => 'required',
    'email' => 'required|email',
    'message' => 'required',
    'avatar' => 'file:jpg|filesize:1M',
));

?>

文件验证的现有扩展可以在 validator/mime-types.php 中找到。

数组验证

当您在 $_POST 中有数组时，可以使用方括号来指定要验证的特定元素，如下所示：

<?php
$input = array(
	'user' => array(
		'first_name' => 'John',
		'last_name' => 'Doe',
		'email' => 'johndoe@example.com',
		'address' => array(
			'street' => array(
				'number' => "123"
			)
		)
	)
);
$validator = new Carbon_Validator($input, array(
	'user[first_name]' => 'required',
	'user[last_name]' => 'required|string_min_length:2',
	'user[email]' => 'email',
	'user[address][street][number]' => 'required',
));

var_dump($validator->passes());
?>

类的设计借鉴了 Laravel 库。