README

InSanity

主分支
开发

针对各种输入来源（如 $_POST 和路由参数）的可扩展验证和清理库。

为什么选择 InSanity？

• 支持各种输入来源的验证（按字段配置）
• 可扩展
• 可翻译
• 支持全局 php 函数，如 trim()、intval() 等。
• 支持数组字段输入
• 无依赖
• 100% 代码覆盖率的自动化测试
• 自由许可：zlib/libpng

注意：此库刚刚发布，可能还不完美。欢迎报告问题、改进想法或创建 pull 请求。

要求

• PHP >= 7.1

安装

通过 composer 安装

composer require lusito/insanity

在您的 php 脚本中包含自动加载器，除非您已经这样做

require __DIR__ . '/vendor/autoload.php';

使用方法

一个示例用例

use Lusito\InSanity\InSanity;

//...

$in = new InSanity(); // or new InSanity($_GET) if you want to use $_GET as default instead of $_POST.
$in->site_id('Site ID', $_GET)->required->is_natural->intval; // use $_GET as input instead of $_POST for this field
$in->parent_id('Parent ID')->required->is_natural->intval;
$in->title('Title')->required->trim->min_length(2)->max_length(255);
$in->slug('Slug')->max_length(255);
$in->visible('Visible')->required->is_bool->boolval;

$errors = $in->getErrors();
if ($errors) {
    http_response_code(400);
    header('Content-Type: application/json');
    echo json_encode(['error' => "Invalid input!", 'validation_errors' => $errors], JSON_UNESCAPED_SLASHES);
} else {
    // Get all values in an associative array:
    $json = $in->toJSON();
}

或者，您可以手动获取值，如下所示

use Lusito\InSanity\InSanity;

//...

$in = new InSanity(); // or new InSanity($_GET) if you want to use $_GET as default instead of $_POST.
$siteId = $in->site_id('Site ID', $_GET)->required->is_natural->intval->getValue(); // use $_GET as input instead of $_POST for this field
$parentId = $in->parent_id('Parent ID')->required->is_natural->intval->getValue();
$title = $in->title('Title')->required->trim->min_length(2)->max_length(255)->getValue();
$slug = $in->slug('Slug')->max_length(255)->getValue();
$visible = $in->visible('Visible')->required->is_bool->boolval->getValue();

//...

类

此库由以下类组成

• InSanity：协调验证过程。
• Field：用于将规则和清理器链接到值。实例将自动创建。
• RuleHandler：包含已包含规则的类。
• ErrorHandler：聚合错误。
• Translator：用于翻译消息和字段名称的类。

最后 3 个类可以扩展，甚至可以用您自己的实现替换，如果您愿意的话。

详情如下

InSanity

此类接收 3 个参数

• 一个可选的（关联）数组，用作未指定任何内容时的默认输入。如果是 null，则使用 $_POST。
• 一个可选的 RuleHandler 实例（或替换类）。如果是 null，则创建一个默认的 RuleHandler。
• 一个可选的 ErrorHandler 实例（或替换类）。如果是 null，则创建一个默认的 ErrorHandler。

要开始对字段进行验证和清理，请调用它如下

$in = new InSanity();
$in->my_field_name('My Field Label')->required->trim->min_length(2);

这由两部分组成

• $in->my_field_name('My Field Label')
  • my_field_name 是输入数组中存在的字段名称。
  • My Field Label 是生成错误消息时使用的文本。
  • 这返回一个 Field 实例。
• ->required->trim->min_length(2)
  • 这些应用您的规则。规则调用返回 Field 实例，以便于链式调用。

您可以使用 $in->getErrors() 获取错误。如果之后需要访问字段（或应用额外的规则），可以使用 $in->my_field_name 来访问字段。

为了方便，存在一个方法 $in->toJSON()，它将创建一个关联数组 field_name => field_value。

字段

字段实例由 InSanity 创建（见上文）。该实例支持执行和链式调用规则。

规则可以以 3 种不同的方式运行

// shortest way:
$field->required;
// does the same as:
$field->required();
// A parameter can be supplied like this:
$field->min_length(2);

规则（和过滤器）方法按顺序应用。如果给定方法返回一个布尔值，则将其解释为规则，否则解释为过滤器（唯一的例外是 boolval，见下文）。

示例

• 返回值假将导致验证失败（并跳过其余规则）
• 返回值为真将继续执行下一个规则（或过滤器）。
• 其他任何情况都将将当前值更改为规则处理器返回的值。

除了正常的规则处理外，还存在一些方法

• default(default)：如果值是 null，则值将被设置为 default。
• boolval()：此方法添加了两个原因
  • boolval 从 PHP 中不适用于与 is_bool 规则相同的值。
  • 它返回真或假，这通常会被解释为验证结果，因此不会被存储。
• getValue()：获取字段的当前值（应用规则后）
• getError()：获取错误消息，如果没有设置错误，则返回 null。
• setFailed(rule, param=null)：将字段设置为失败。将使用翻译器类生成错误消息。

RuleHandler

正如所述，RuleHandler 包含验证方法。该方法接收 1-2 个参数。第一个是待验证的值，第二个是用户传递的参数（如果没有给出则为 null）。

以下规则包含在内置 RuleHandler 类中

• is_alpha（a-z）
• is_alnum（a-z 和 0-9）
• is_alnum_dash（a-z，0-9，_ 和 -）
• is_numeric（一个数值，前缀为 + 或 -）
• is_integer（一个整数值，前缀为 + 或 -）
• is_natural（一个整数值，没有前缀）
• is_natural_no_zero（一个没有前缀且大于零的整数值）
• is_bool（true|false|on|off|yes|no|1|0）
• valid_email（有效的电子邮件地址）
• required（修剪后的值不能为空）
• min_length(length)（值必须具有最小长度）
• max_length(length)（值必须具有最大长度）
• exact_length(length)（值必须具有指定长度）

Translator

如果您计划编写自己的规则或需要除英语之外的目标语言，您可以通过向构造函数提供关联数组来添加/覆盖翻译，或者您可以编写自己的实现。

ErrorHandler

ErrorHandler 构建并聚合错误消息。当需要时，它将创建一个新的 Translator 实例。如果您希望它使用自定义的 Translator 实例，请将实例作为构造函数的第一个参数传递，或者覆盖 getTranslator() 方法。

报告问题

某些功能工作得不太如意？您需要尚未实现的功能？请检查 问题跟踪器，如果问题尚未列出，请添加新问题。请尽量提供详细的问题描述，包括重现问题的步骤。

贡献

太棒了！如果您想贡献一个新功能或提交一个错误修复，请克隆此仓库并发送拉取请求。请确保在提交之前所有单元测试都通过，并在引入新功能的情况下添加新测试。

许可证

InSanity 已在 zlib/libpng 许可证下发布，这意味着您可以免费使用它，无需附加任何条件，在商业和非商业项目中使用。感谢您提供贡献，但这不是强制性的。