PHPackages                             hiqdev/hoa-ruler - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. hiqdev/hoa-ruler

ActiveLibrary[Utility & Helpers](/categories/utility)

hiqdev/hoa-ruler
================

The Hiqdev Hoa\\Ruler library.

1.0.1(3y ago)39.3k↓20%1BSD-3-ClausePHPPHP >=7.4

Since Jul 6Pushed 3y agoCompare

[ Source](https://github.com/hiqdev/Hoa-Ruler)[ Packagist](https://packagist.org/packages/hiqdev/hoa-ruler)[ RSS](/packages/hiqdev-hoa-ruler/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (8)Versions (3)Used By (0)

Reasons to fork
---------------

[](#reasons-to-fork)

The Hoa project was archived, and no upgrades or patches are neither provided nor accepted by merge requests.

HOA Packages include some code that is Deprecated for PHP 8.0 and PHP 8.1, but we needed these packages to run on modern PHP versions.

What's changed in from?
-----------------------

[](#whats-changed-in-from)

The changes mainly affected the return data type hinting in methods declaration, access to uninitialized properties.

How to use
----------

[](#how-to-use)

We've currently forked the following packages, primarily to make hoa/ruler work with PHP 8.1:

Original packageForked packagehoa/rulerhiqdev/hoa-rulerhoa/compilerhiqdev/hoa-compilerhoa/protocolhiqdev/hoa-protocolhoa/iteratorhiqdev/hoa-iteratorYou can simply replace requirements in composer.json from hoa packages to the corresponding forked packages: there is no need to change something in the codebase. If you use someone's package, that requires hoa – simply add forks to your project root composer.json: we have marked forks as a replacement, so composer will install them instead of the original packages.

Versions
--------

[](#versions)

We've forked from the latest hoa package versions and bump own versions starting from 1.0.

Testing
-------

[](#testing)

Before running the test suites, the development dependencies must be installed:

```
$ composer install
```

Then, to run all the test suites:

```
$ vendor/bin/hoa test:run
```

For more information, please read the [contributor guide](https://hoa-project.net/Literature/Contributor/Guide.html).

Quick usage
-----------

[](#quick-usage)

As a quick overview, we propose to see a very simple example that manipulates a simple rule with a simple context. After, we will add a new operator in the rule. And finally, we will see how to save a rule in a database.

### Three steps

[](#three-steps)

So first, we create a context with two variables: `group` and `points`, and we then assert a rule. A context holds values to concretize a rule. A value can also be the result of a callable. Thus:

```
$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)
 */
```

In the next example, we have a `User` object and a context that is populated dynamically (when the `user` variable is concretized, two new variables, `group`and `points` are created). Moreover, we will create a new operator/function called `logged`. There is no difference between an operator and a function except that an operator has two operands (so arguments).

### Adding operators and functions

[](#adding-operators-and-functions)

For now, we have the following operators/functions by default: `and`, `or`, `xor`, `not`, `=` (`is` as an alias), `!=`, `>`, `>=`, `_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)
 */
```

Also, if a variable in the context is an array, we can access to its values from a rule with the same syntax as PHP. For example, if the `a` variable is an array, we can write `a[0]` to access to the value associated to the `0` key. It works as an hashmap (PHP array implementation), so we can have strings & co. as keys. In the same way, if a variable is an object, we can call a method on it. For example, if the `a` variable is an array where the value associated to the first key is an object with a `foo` method, we can write: `a[0].foo(b)` where `b` is another variable in the context. Also, we can access to the public attributes of an object. Obviously, we can mixe array and object accesses. Please, take a look at the grammar (`hoa://Library/Ruler/Grammar.pp`) to see all the possible constructions.

### Saving a rule

[](#saving-a-rule)

Now, we have two options to save the rule, for example, in a database. Either we save the rule as a string directly, or we will save the serialization of the rule which will avoid further interpretations. In the next example, we see how to serialize and unserialize a rule by using the `Hoa\Ruler\Ruler::interpret`static method:

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

And for next executions:

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

When a rule is interpreted, its object model is created. We serialize and unserialize this model. To see the PHP code needed to create such a model, we can print the model itself (as an example). Thus:

```
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
 *                 )
 *             )
 *         );
 */
```

Have fun!

Documentation
-------------

[](#documentation)

The [hack book of `Hoa\Ruler`](https://central.hoa-project.net/Documentation/Library/Ruler) contains detailed information about how to use this library and how it works.

To generate the documentation locally, execute the following commands:

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

More documentation can be found on the project's website: [hoa-project.net](https://hoa-project.net/).

Getting help
------------

[](#getting-help)

There are mainly two ways to get help:

- On the [`#hoaproject`](https://webchat.freenode.net/?channels=#hoaproject)IRC channel,
- On the forum at [users.hoa-project.net](https://users.hoa-project.net).

Contribution
------------

[](#contribution)

Do you want to contribute? Thanks! A detailed [contributor guide](https://hoa-project.net/Literature/Contributor/Guide.html) explains everything you need to know.

License
-------

[](#license)

Hoa is under the New BSD License (BSD-3-Clause). Please, see [`LICENSE`](https://hoa-project.net/LICENSE) for details.

Related projects
----------------

[](#related-projects)

The following projects are using this library:

- [RulerZ](https://github.com/K-Phoen/rulerz), Powerful implementation of the Specification pattern in PHP,
- [ownCloud](https://owncloud.org/), A safe home for all your data,
- [PhpMetrics](http://www.phpmetrics.org/), Static analysis tool for PHP,
- [`hiqdev/php-billing`](https://github.com/hiqdev/php-billing), a billing library in PHP
- [`atoum/ruler-extension`](https://github.com/atoum/ruler-extension), This extension allows to filter test results in [atoum](http://atoum.org/).

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity29

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 79.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

2

Last Release

1412d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/790fd24da129907d373559f60c6994f664f06e3f518502c03580cc9f3594615e?d=identicon)[hiqdev](/maintainers/hiqdev)

---

Top Contributors

[![Hywan](https://avatars.githubusercontent.com/u/946104?v=4)](https://github.com/Hywan "Hywan (194 commits)")[![stephpy](https://avatars.githubusercontent.com/u/232744?v=4)](https://github.com/stephpy "stephpy (23 commits)")[![vonglasow](https://avatars.githubusercontent.com/u/1275202?v=4)](https://github.com/vonglasow "vonglasow (7 commits)")[![ValeriyShnurovoy](https://avatars.githubusercontent.com/u/16237008?v=4)](https://github.com/ValeriyShnurovoy "ValeriyShnurovoy (5 commits)")[![Grummfy](https://avatars.githubusercontent.com/u/668804?v=4)](https://github.com/Grummfy "Grummfy (2 commits)")[![tafid](https://avatars.githubusercontent.com/u/3338188?v=4)](https://github.com/tafid "tafid (2 commits)")[![arnegroskurth](https://avatars.githubusercontent.com/u/5823621?v=4)](https://github.com/arnegroskurth "arnegroskurth (1 commits)")[![samundra](https://avatars.githubusercontent.com/u/760855?v=4)](https://github.com/samundra "samundra (1 commits)")[![shouze](https://avatars.githubusercontent.com/u/54712?v=4)](https://github.com/shouze "shouze (1 commits)")[![shulard](https://avatars.githubusercontent.com/u/482993?v=4)](https://github.com/shulard "shulard (1 commits)")[![SilverFire](https://avatars.githubusercontent.com/u/4499203?v=4)](https://github.com/SilverFire "SilverFire (1 commits)")[![Pierozi](https://avatars.githubusercontent.com/u/5133487?v=4)](https://github.com/Pierozi "Pierozi (1 commits)")[![Bhoat](https://avatars.githubusercontent.com/u/4126670?v=4)](https://github.com/Bhoat "Bhoat (1 commits)")[![jroenf](https://avatars.githubusercontent.com/u/396417?v=4)](https://github.com/jroenf "jroenf (1 commits)")[![K-Phoen](https://avatars.githubusercontent.com/u/66958?v=4)](https://github.com/K-Phoen "K-Phoen (1 commits)")[![marclaporte](https://avatars.githubusercontent.com/u/1004261?v=4)](https://github.com/marclaporte "marclaporte (1 commits)")[![mnapoli](https://avatars.githubusercontent.com/u/720328?v=4)](https://github.com/mnapoli "mnapoli (1 commits)")

---

Tags

libraryruler

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/hiqdev-hoa-ruler/health.svg)

```
[![Health](https://phpackages.com/badges/hiqdev-hoa-ruler/health.svg)](https://phpackages.com/packages/hiqdev-hoa-ruler)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)