README

异步验证库

要求

• PHP 7.3
  • ext-ctype
  • ext-dom
  • ext-fileinfo
  • ext-filter
  • ext-gd
  • ext-hash
  • ext-json
  • ext-libxml
  • ext-mbstring
• Redis

对于非阻塞上下文，还需要安装以下事件库之一

• ev
• event
• php-uv

安装

composer require harmonyio/validation

使用方法

此库基于amphp 并发框架。

基本用法

针对单个规则验证值

<?php declare(strict_types=1);

namespace HarmonyIO\Validation\Examples;

use Amp\Loop;
use HarmonyIO\Validation\Result\Result;
use HarmonyIO\Validation\Rule\Numeric\NumericType;

require_once '/path/to/vendor/autoload.php';

Loop::run(static function () {
    /** @var Result $result */
    $result = yield (new NumericType())->validate(true);

    var_dump($result);
});

这将产生以下Result对象

object(HarmonyIO\Validation\Result\Result)#11 (2) {
  ["valid":"HarmonyIO\Validation\Result\Result":private]=>
  bool(false)
  ["errors":"HarmonyIO\Validation\Result\Result":private]=>
  array(1) {
    [0]=>
    object(HarmonyIO\Validation\Result\Error)#10 (2) {
      ["message":"HarmonyIO\Validation\Result\Error":private]=>
      string(19) "Numeric.NumericType"
      ["parameters":"HarmonyIO\Validation\Result\Error":private]=>
      array(0) {
      }
    }
  }
}

堆叠验证规则

当你想对同一个值应用多个规则时，可以在规则之上堆叠规则

<?php declare(strict_types=1);

namespace HarmonyIO\Validation\Examples;

use Amp\Loop;
use HarmonyIO\Validation\Result\Result;
use HarmonyIO\Validation\Rule\Combinator\All;
use HarmonyIO\Validation\Rule\Numeric\Maximum;
use HarmonyIO\Validation\Rule\Numeric\Minimum;
use HarmonyIO\Validation\Rule\Numeric\NumericType;

require_once '/path/to/vendor/autoload.php';

Loop::run(static function () {
    /** @var Result $result */
    $result = yield (new All(
        new NumericType(),
        new Minimum(1),
        new Maximum(100)
    ))->validate(102);

    var_dump($result);
});

这将产生以下Result对象

object(HarmonyIO\Validation\Result\Result)#11 (2) {
  ["valid":"HarmonyIO\Validation\Result\Result":private]=>
  bool(false)
  ["errors":"HarmonyIO\Validation\Result\Result":private]=>
  array(1) {
    [0]=>
    object(HarmonyIO\Validation\Result\Error)#26 (2) {
      ["message":"HarmonyIO\Validation\Result\Error":private]=>
      string(15) "Numeric.Maximum"
      ["parameters":"HarmonyIO\Validation\Result\Error":private]=>
      array(1) {
        [0]=>
        object(HarmonyIO\Validation\Result\Parameter)#24 (2) {
          ["key":"HarmonyIO\Validation\Result\Parameter":private]=>
          string(7) "maximum"
          ["value":"HarmonyIO\Validation\Result\Parameter":private]=>
          float(100)
        }
      }
    }
  }
}

验证规则

已经实现了详尽的验证规则列表。有关所有支持的规则概述，请参阅wiki中的文档。

所有验证规则都遵循相同的接口

<?php declare(strict_types=1);

namespace HarmonyIO\Validation\Rule;

use Amp\Promise;

interface Rule
{
    /**
     * @param mixed $value
     * @return Promise<HarmonyIO\Validation\Result\Result>
     */
    public function validate($value): Promise;
}

这将确保任何值都可以传递进行验证，并且总是会产生一个解析为Result对象的承诺。

如果您缺少一个验证规则，请随时打开一个问题。

组合器

组合器是一种将多个验证规则组合成单个结果的方法。

这可以用于根据现有规则构建更复杂的验证规则。

结果和错误

所有验证始终产生一个HarmonyIO\Validation\Result\Result对象。
在验证后，我们可以通过调用HarmonyIO\Validation\Result\Result::isValid()方法来检查值是否有效，该方法返回一个简单的布尔值。

如果验证失败，可以通过Result对象上的两种方法之一访问验证错误

• HarmonyIO\Validation\Result\Result::getFirstError() - 如果没有错误，则返回null，否则返回一个HarmonyIO\Validation\Result\Error对象
• HarmonyIO\Validation\Result\Result::getErrors() - 返回一个包含HarmonyIO\Validation\Result\Error对象的数组

错误

当验证产生无效结果时，至少会向Result对象中添加一个Error对象。

错误对象始终有一个错误消息（可以用于在项目中渲染翻译）和零个或多个参数。
参数用于失败的验证规则基于动态值时。例如，当文本的最小长度验证规则失败时，会产生以下Error对象

object(HarmonyIO\Validation\Result\Error)#17 (2) {
      ["message":"HarmonyIO\Validation\Result\Error":private]=>
      string(18) "Text.MinimumLength"
      ["parameters":"HarmonyIO\Validation\Result\Error":private]=>
      array(1) {
        [0]=>
        object(HarmonyIO\Validation\Result\Parameter)#15 (2) {
          ["key":"HarmonyIO\Validation\Result\Parameter":private]=>
          string(6) "length"
          ["value":"HarmonyIO\Validation\Result\Parameter":private]=>
          int(4)
        }
      }
    }

传统/阻塞用法

尽管该项目基于异步编程，但也可以使用wait()辅助函数以更传统的阻塞方式使用它

<?php declare(strict_types=1);

namespace HarmonyIO\Validation\Examples;

use HarmonyIO\Validation\Result\Result;
use HarmonyIO\Validation\Rule\Numeric\NumericType;
use function Amp\Promise\wait;

require_once '/path/to/vendor/autoload.php';

/** @var Result $result */
$result = wait((new NumericType())->validate(true));

var_dump($result);

规则

所有实现的规则的概述（包括用法和版本信息）已在wiki中记录。