README

yavljs (https://npmjs.net.cn/package/yavljs) 的 PHP 实现，允许您在前端和后端使用相同的定义进行验证。

为什么选择 YavlJS for PHP ?

yavljs (https://npmjs.net.cn/package/yavljs) 是一个用于前端表单验证的 JavaScript 库。遗憾的是，前端验证仅仅是为了用户体验：开发者**永远**不应该完全依赖于它来验证提交的数据。

因此，我决定开发其 PHP 等价物。

我的目标是您可以在应用程序的前端和后端部分进行验证，所有这些都可以使用相同的文件。

与 YavlJS 的关键区别是什么？

只有一个区别，即**字段的名称**。

在使用 yavljs 时，您可以简单地为了语义而命名，在 yavlphp 中情况有所不同，让我们用一个例子来说明这一点

<form id="form">
  <input type="text" name="field1"/>
  <input type="text" name="field2"/>
  <input type="text" name="field3"/>
  
  <button type="submit">
    Submit
  </button>
</form>

使用 yavljs

{
  "form": "#form",
  "fields": {
    "first field": {
      "selector": "[name='field1']",
      "error_selector": "*",
      "required": true,
      "type": "int",
      "rules": {
        "min": 3,
      	"max": 6
      }
    },
    "second field": {
      "selector": "[name='field2']",
      "error_selector": "*",
      "required": true,
      "type": "int",
      "rules": {
        "min": 8,
      	"max": 12
      }
    },
    "third field": {
      "selector": "[name='field3']",
      "error_selector": "*",
      "required": true,
      "type": "int",
      "rules": {
        "min": 24,
      	"max": 32
      }
    },
  }
}

使用 yavlphp

{
  "form": "#form",
  "fields": {
    "field1": {
      "selector": "[name='field1']",
      "error_selector": "*",
      "required": true,
      "type": "int",
      "rules": {
        "min": 3,
      	"max": 6
      }
    },
    "field2": {
      "selector": "[name='field2']",
      "error_selector": "*",
      "required": true,
      "type": "int",
      "rules": {
        "min": 8,
      	"max": 12
      }
    },
    "field3": {
      "selector": "[name='field3']",
      "error_selector": "*",
      "required": true,
      "type": "int",
      "rules": {
        "min": 24,
      	"max": 32
      }
    },
  }
}

如您所见，仅用于语义的名称现在必须作为字段名称。

这是因为大多数用例都将使用请求的变量来验证表单。

除了这个之外，验证过程的执行方式没有其他区别。

如何安装 yavlphp ?

如果您还没有使用 composer，我强烈建议您使用它，它是一个非常方便的 PHP 包管理器。

安装 composer 后，只需在您的应用程序文件夹中运行以下命令即可

composer require voltra/yavlphp

这将自动安装 yavlphp 及其依赖项（如果有）。

如何使用 yavlphp ?

验证器的实例

这非常简单，您将使用 YavlPhp\Yavl 的一个实例。您可以直接从 YavlPhp\Components\YavlFieldsMap 和 YavlPhp\Components\YavlLocaleMap 创建它。

use YavlPhp\Yavl;
use YavlPhp\Components\YavlFieldsMap;
use YavlPhp\Components\YavlLocaleMap;

$validationSettings = new YavlFieldsMap(/* check the documentations for parameters */);
$errorMessages = new YavlLocaleMap(/* check the documentations for parameters */);

$v = new Yavl($validationSettings, $errorMessages);

或者，您可以跳过这些步骤，直接使用您的 JSON 文件

use YavlPhp\Yavl;

function getUrlFromServerRoot(string $path) : string{}

$v = Yavl::fromJson(
	getUrlFromServerRoot("assets/json/formx/form.json"),
  	getUrlFromServerRoot("assets/json/formx/locale.json")
);

注意： Yavl\Php\Components\YavlLocaleMap 和到本地化文件的路径都是可选的，它们是默认的（但强烈建议提供其中一个）。

实际验证数据

现在您已经准备好可以使用 Yavl 实例了，您将使用其 validate 方法，该方法可以接受一个参数：数据的关联数组，关联是 fieldName => fieldValue。

请注意，如果您不提供此参数，它将尝试从 $_GET 或 $_POST（如果是 GET 方法，则使用 $_GET，如果不是 GET，则使用 $_POST）中获取参数。

$errors = $v->validate();

$errors = $v->validate($formFieldsAssociativeArray);

然后处理验证并返回方法中的错误。

validate 方法返回一个关联数组，将错误消息与字段名称相关联

当不遵守验证规则（必填、正则表达式等）时，它将设置相应的错误信息，并继续处理其他字段。

因此，如果没有验证错误（意味着数据完全通过验证），那么结果将是一个空数组。

错误处理

假设你有一个如下所示的表单

<form>
  <input type="text" name="username"/>
  <input type="text" name="password"/>
  <button type="submit">Submit</button>
</form>

你可以这样处理错误

$errors = $v->validate;
if(!empty( $errorss )){
  rediret_to_form_with_errors("some/url/to/the/form", $errors);
  //This is not an actual function ;)
}else{
  //go on with your correct data !
}

如何扩展yavlphp（插件）？

创建插件

这非常简单，验证规则/函数是继承自YavlPhp\Components\YavlValidationFunction的类的对象，该类有两个需要重写的方法

call → 检查数据是否有效的方法
getNameForJson → 返回此规则名称的方法，该名称应出现在JSON文件中

以下是它们的签名

abstract function call(YavlLocaleMap $locale, $value, $expected, array $fieldsValues) : ?string;

abstract function getNameForJson() : string;

注意，如果数据（$value）有效，则call将返回null，否则它将返回从$locale返回的相应的错误信息。

例如，让我们看看YavlPhp\Rules\YavlMaxLength，这是maxLength规则（在JSON文件中）的验证函数

final class YavlMaxLength extends YavlValidationFunction {

    public function call(
      YavlLocaleMap $locale,
      $value,
      $expected,
      array $fieldsValues
    ): ?string {
      //$expected is the value given in the JSON file for this rule
      //$value is the field's value
        return (strlen("{$value}") <= intval($expected))
          ? null //It is less than or equal to the maximum value, so return null
          : $locale->get($this->getNameForJson()); //It is not, fetch the error message
    }

    public function getNameForJson(): string {
        return "maxLength";
    }
}

如果你的错误信息需要任何类型的操作（例如，将%input%替换为$value变量），你可以使用preg_replace或str_replace。

注意，%value%总是替换为$expected的值，除非你首先替换它。

将插件添加到验证器

一旦你有你的插件类准备好了，你可以使用其registerPlugin方法将其添加到验证器中

$v = /*get a Yavl instance*/;
$v->registerPlugin(new AwesomeYavlPlugin());

它将自动推断名称（getNameForJson）。请注意，这样做可能会覆盖他人的插件，所以请小心。

移除插件

如果你想要移除插件，可以使用验证器的removePlugin方法。

此方法需要一个参数，即你的插件名称（参见图getNameForJson方法）。

获取已定义插件的列表

你也可以获取已定义插件的列表，这可能在你需要确定你的插件的新名称时很有用（如果你的初始名称已被使用）。

为此，你需要调用你的验证器的getPluginNamesList方法，该方法返回所有插件的名称（参见图getNameforJson方法）。

需要更多信息吗？

有关如何使用yavlphp的说明，请参阅此页面（npm上的yavljs）。

使用PHPUnit测试你的插件，你可以从YavlPhp\Tests\Components\YavlFunctionTest_Abstract继承。

voltra / yavlphp

维护者

详细信息