README

Hoa 是一套 模块化、可扩展 和 结构化 的 PHP 库。
此外，Hoa 致力于成为工业和研究世界之间的桥梁。

Hoa\Ruler

这个库允许操作一个规则引擎。规则可以使用一种专用语言编写，这种语言非常接近 SQL。因此，它们可以被用户编写并保存在数据库中。

这类规则对于例如需要操作由用户编写的促销或特别优惠规则的商业解决方案非常有用。引用维基百科

业务规则引擎是一个软件系统，它在一个运行时的生产环境中执行一个或多个业务规则。这些规则可能来自法律规范（“员工可以被任何理由或没有理由解雇，但不能因非法理由解雇”），公司政策（“所有一次性消费超过100美元的客户将获得10%的折扣”）或其他来源。业务规则系统使得这些公司政策和其他运营决策可以与应用程序代码分开定义、测试、执行和维护。

了解更多.

安装

使用 Composer，要将此库包含到依赖项中，您需要要求 hoa/ruler

$ composer require hoa/ruler '~2.0'

有关更详细的安装说明，请参阅源代码页面。

测试

在运行测试套件之前，必须安装开发依赖项

$ composer install

然后，运行所有测试套件

$ vendor/bin/hoa test:run

有关更多信息，请参阅贡献者指南。

快速使用

作为一个快速概述，我们建议先看一个操作简单规则和简单上下文的简单示例。然后，我们将在规则中添加一个新的操作符。最后，我们将看到如何将规则保存在数据库中。

三步

因此，首先，我们创建一个包含两个变量 group 和 points 的上下文，然后断言一个规则。上下文持有值以具体化一个规则。值也可以是可调用的结果。因此

$ruler = new Hoa\Ruler\Ruler();

// 1. Write a rule.
$rule  = 'group in ["customer", "guest"] and points > 30';

// 2. Create a context.
$context           = new Hoa\Ruler\Context();
$context['group']  = 'customer';
$context['points'] = function () {
    return 42;
};

// 3. Assert!
var_dump(
    $ruler->assert($rule, $context)
);

/**
 * Will output:
 *     bool(true)
 */

在下一个示例中，我们有一个 User 对象和一个动态填充的上下文（当 user 变量具体化时，创建了两个新变量，group 和 points）。此外，我们将创建一个新的操作符/函数，称为 logged。操作符和函数之间没有区别，除了操作符有两个操作数（因此是参数）之外。

添加操作符和函数

目前，我们默认提供了以下操作符/函数：and、or、xor、not、=（is 作为别名）、!=、>、>=、<、<=、in 和 sum。我们可以通过不同的方式添加自己的。以下是一个简单且易变的方法示例。因此

// The User object.
class User
{
    const DISCONNECTED = 0;
    const CONNECTED    = 1;

    public $group      = 'customer';
    public $points     = 42;
    protected $_status = 1;

    public function getStatus()
    {
        return $this->_status;
    }
}

$ruler = new Hoa\Ruler\Ruler();

// New rule.
$rule  = 'logged(user) and group in ["customer", "guest"] and points > 30';

// New context.
$context         = new Hoa\Ruler\Context();
$context['user'] = function () use ($context) {
    $user              = new User();
    $context['group']  = $user->group;
    $context['points'] = $user->points;

    return $user;
};

// We add the logged() operator.
$ruler->getDefaultAsserter()->setOperator('logged', function (User $user) {
    return $user::CONNECTED === $user->getStatus();
});

// Finally, we assert the rule.
var_dump(
    $ruler->assert($rule, $context)
);

/**
 * Will output:
 *     bool(true)
 */

此外，如果上下文中的变量是一个数组，我们可以使用与 PHP 语法相同的语法访问其值。例如，如果 a 变量是一个数组，我们可以编写 a[0] 来访问与 0 键关联的值。它作为一个 hashmap（PHP 数组实现）工作，因此我们可以使用字符串等作为键。同样地，如果变量是一个对象，我们可以调用它上的方法。例如，如果 a 变量是一个数组，其中第一个键的值是一个具有 foo 方法的对象，我们可以编写：a[0].foo(b) 其中 b 是上下文中的另一个变量。此外，我们还可以访问对象的公共属性。显然，我们可以混合数组和对象的访问。请查看语法（hoa://Library/Ruler/Grammar.pp）以查看所有可能的构造。

保存规则

现在，我们有两种保存规则的方法，例如，在数据库中。要么我们直接保存规则字符串，要么我们保存规则的序列化版本，这将避免进一步的解释。在下面的示例中，我们将看到如何使用 Hoa\Ruler\Ruler::interpret 静态方法序列化和反序列化规则。

$database->save(
    serialize(
        Hoa\Ruler\Ruler::interpret(
            'logged(user) and group in ["customer", "guest"] and points > 30'
        )
    )
);

并且对于后续执行

$rule = unserialize($database->read());
var_dump(
    $ruler->assert($rule, $context)
);

当解释一个规则时，会创建其对象模型。我们序列化和反序列化这个模型。要查看创建此类模型所需的 PHP 代码，我们可以打印模型本身（作为示例）。因此

echo Hoa\Ruler\Ruler::interpret(
    'logged(user) and group in ["customer", "guest"] and points > 30'
);

/**
 * Will output:
 *     $model = new \Hoa\Ruler\Model();
 *     $model->expression =
 *         $model->and(
 *             $model->func(
 *                 'logged',
 *                 $model->variable('user')
 *             ),
 *             $model->and(
 *                 $model->in(
 *                     $model->variable('group'),
 *                     [
 *                         'customer',
 *                         'guest'
 *                     ]
 *                 ),
 *                 $model->{'>'}(
 *                     $model->variable('points'),
 *                     30
 *                 )
 *             )
 *         );
 */

玩得开心！

文档

hack book of Hoa\Ruler 包含有关如何使用此库及其工作原理的详细信息。

要本地生成文档，请执行以下命令

$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open

更多文档可以在项目的网站上找到：hoa-project.net。

获取帮助

主要有两种获取帮助的方式

在 #hoaproject IRC 频道中，
在 users.hoa-project.net 的论坛上。

贡献

你想贡献吗？谢谢！详细的贡献指南解释了你需要知道的一切。

许可证

Hoa 采用新的 BSD 许可证（BSD-3-Clause）。请参阅 LICENSE 以获取详细信息。

hoa/ruler

维护者

详细信息