PHPackages                             niro/kphoen-rulerz - 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. [Database & ORM](/categories/database)
4. /
5. niro/kphoen-rulerz

ActiveLibrary[Database & ORM](/categories/database)

niro/kphoen-rulerz
==================

Powerful implementation of the Specification pattern

0.21.3(4y ago)0154—0%MITPHPPHP >=7.1

Since Feb 7Pushed 4y agoCompare

[ Source](https://github.com/Alistair-zhong/rulerz)[ Packagist](https://packagist.org/packages/niro/kphoen-rulerz)[ Docs](https://github.com/K-Phoen/RulerZ)[ Patreon](https://www.patreon.com/kevin_gomez)[ RSS](/packages/niro-kphoen-rulerz/feed)WikiDiscussions master Synced 1mo ago

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

RulerZ [![Build Status](https://camo.githubusercontent.com/1a9ac8e5064e73aafe69d5eb5e5b4620646dd4352187d6d46b0245790b705484/68747470733a2f2f7472617669732d63692e6f72672f4b2d50686f656e2f72756c65727a2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/K-Phoen/rulerz) [![Scrutinizer Code Quality](https://camo.githubusercontent.com/462dfba1cf746f53da67c4226ae11f596dad92d4db8492dbda1bc7262c899317/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f4b2d50686f656e2f72756c65727a2f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/K-Phoen/rulerz/?branch=master)
==========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================

[](#rulerz--)

> The central idea of Specification is to separate the statement of how to match a candidate, from the candidate object that it is matched against.
>
> Specifications, [explained by Eric Evans and Martin Fowler](http://www.martinfowler.com/apsupp/spec.pdf)

RulerZ is a PHP implementation of the **Specification pattern** which puts the emphasis on three main aspects:

- an easy and **data-agnostic [DSL](http://en.wikipedia.org/wiki/Domain-specific_language)**to define business rules and specifications,
- the ability to check if a candidate **satisfies** a specification,
- the ability to **filter or query any datasource** to only retrieve candidates matching a specification.

Introduction
------------

[](#introduction)

Business rules can be written as text using a dedicated language, very close to SQL, in which case we refer to them as *rules* or they can be encapsulated in single classes and referred to as *specifications*.

Once a rule (or a specification) is written, it can be used to check if a single candidate satisfies it or directly to query a datasource.

The following datasources are supported natively:

- array of arrays,
- array of objects.

And support for each one of these is provided by an additional library:

- Doctrine DBAL QueryBuilders: [rulerz-php/doctrine-dbal](https://github.com/rulerz-php/doctrine-dbal/),
- Doctrine ORM QueryBuilders: [rulerz-php/doctrine-orm](https://github.com/rulerz-php/doctrine-orm/),
- [Pomm](http://www.pomm-project.org/) models: [rulerz-php/pomm](https://github.com/rulerz-php/pomm/),
- Elasticsearch (using the [official client](https://github.com/elasticsearch/elasticsearch-php): [rulerz-php/elasticsearch](https://github.com/rulerz-php/elasticsearch/),
- Solr (using the [solarium](https://github.com/solariumphp/solarium): [rulerz-php/solarium](https://github.com/rulerz-php/solarium/),
- Laravel's [Eloquent ORM](http://laravel.com/docs/5.0/eloquent): [rulerz-php/eloquent](https://github.com/rulerz-php/eloquent/).

**Killer feature:** when working with Doctrine, Pomm, or Elasticsearch, RulerZ is able to convert rules directly in queries and does not need to fetch data beforehand.

#### That's cool, but why do I need that?

[](#thats-cool-but-why-do-i-need-that)

First of all, you get to **express business rules** in a dedicated, **simple language**. Then, these business rules can be **encapsulated** in specification classes, reused and composed to form more complex rules. Specifications are now **reusable** and **testable**. And last but not least, these rules can be used both to check if a candidate satisfies it and to **filter any datasource**.

If you still need to be conviced, you can read the whole reasoning in [this article](http://blog.kevingomez.fr/2015/02/07/on-taming-repository-classes-in-doctrine-among-other-things/).

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

[](#quick-usage)

As a quick overview, we propose to see a little example that manipulates a simple rule and several datasources.

#### 1. Write a rule

[](#1-write-a-rule)

The rule hereafter describes a "*high ranked female player*" (basically, a female player having more than 9000 points).

```
$highRankFemalesRule = 'gender = "F" and points > 9000';
```

#### 2. Define a datasource

[](#2-define-a-datasource)

We have the following datasources:

```
// a Doctrine QueryBuilder
$playersQb = $entityManager
    ->createQueryBuilder()
    ->select('p')
    ->from('Entity\Player', 'p');

// or an array of arrays
$playersArr = [
    ['pseudo' => 'Joe',   'gender' => 'M', 'points' => 2500],
    ['pseudo' => 'Moe',   'gender' => 'M', 'points' => 1230],
    ['pseudo' => 'Alice', 'gender' => 'F', 'points' => 9001],
];

// or an array of objects
$playersObj = [
    new Player('Joe',   'M', 40, 2500),
    new Player('Moe',   'M', 55, 1230),
    new Player('Alice', 'F', 27, 9001),
];
```

#### 3. Use a rule to query a datasource

[](#3-use-a-rule-to-query-a-datasource)

For any of our datasource, retrieving the results is as simple as calling the `filter` method:

```
// converts the rule in DQL and makes a single query to the DB
$highRankFemales = $rulerz->filter($playersQb, $highRankFemalesRule);
// filters the array of arrays
$highRankFemales = $rulerz->filter($playersArr, $highRankFemalesRule);
// filters the array of objects
$highRankFemales = $rulerz->filter($playersObj, $highRankFemalesRule);
```

#### 3. (bis) Check if a candidate satisfies a rule

[](#3-bis-check-if-a-candidate-satisfies-a-rule)

Given a candidate, checking if it satisfies a rule boils down to calling the `satisfies` method:

```
$isHighRankFemale = $rulerz->satisfies($playersObj[0], $highRankFemalesRule);
```

Going further
-------------

[](#going-further)

Check out [the documentation](doc/index.md) to discover what RulerZ can do for you.

License
-------

[](#license)

This library is under the [MIT](LICENSE) license.

###  Health Score

30

—

LowBetter than 65% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity12

Limited adoption so far

Community18

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 90.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 ~54 days

Recently: every ~323 days

Total

49

Last Release

1500d ago

PHP version history (3 changes)0.5.3PHP >=5.4

0.15.0PHP >=5.5

0.21.0PHP >=7.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/a39a12e655b2894c21557ded75a7f9d1de92acbf21bba7e6a1c89fe6fa359d0a?d=identicon)[Alistair-zhong](/maintainers/Alistair-zhong)

---

Top Contributors

[![K-Phoen](https://avatars.githubusercontent.com/u/66958?v=4)](https://github.com/K-Phoen "K-Phoen (418 commits)")[![bobdercole](https://avatars.githubusercontent.com/u/3331705?v=4)](https://github.com/bobdercole "bobdercole (14 commits)")[![iainmckay](https://avatars.githubusercontent.com/u/1223726?v=4)](https://github.com/iainmckay "iainmckay (6 commits)")[![esserj](https://avatars.githubusercontent.com/u/1032205?v=4)](https://github.com/esserj "esserj (3 commits)")[![Alistair-zhong](https://avatars.githubusercontent.com/u/58490734?v=4)](https://github.com/Alistair-zhong "Alistair-zhong (2 commits)")[![jdeniau](https://avatars.githubusercontent.com/u/1398469?v=4)](https://github.com/jdeniau "jdeniau (2 commits)")[![Hywan](https://avatars.githubusercontent.com/u/946104?v=4)](https://github.com/Hywan "Hywan (1 commits)")[![estelsmith](https://avatars.githubusercontent.com/u/363670?v=4)](https://github.com/estelsmith "estelsmith (1 commits)")[![ikwattro](https://avatars.githubusercontent.com/u/1222009?v=4)](https://github.com/ikwattro "ikwattro (1 commits)")[![j0k3r](https://avatars.githubusercontent.com/u/62333?v=4)](https://github.com/j0k3r "j0k3r (1 commits)")[![jdecool](https://avatars.githubusercontent.com/u/433926?v=4)](https://github.com/jdecool "jdecool (1 commits)")[![yvoyer](https://avatars.githubusercontent.com/u/1745744?v=4)](https://github.com/yvoyer "yvoyer (1 commits)")[![jhuet](https://avatars.githubusercontent.com/u/372409?v=4)](https://github.com/jhuet "jhuet (1 commits)")[![claudusd](https://avatars.githubusercontent.com/u/3321326?v=4)](https://github.com/claudusd "claudusd (1 commits)")[![loicbourg](https://avatars.githubusercontent.com/u/4905942?v=4)](https://github.com/loicbourg "loicbourg (1 commits)")[![mikaelrandy](https://avatars.githubusercontent.com/u/187703?v=4)](https://github.com/mikaelrandy "mikaelrandy (1 commits)")[![mnapoli](https://avatars.githubusercontent.com/u/720328?v=4)](https://github.com/mnapoli "mnapoli (1 commits)")[![nclsHart](https://avatars.githubusercontent.com/u/833625?v=4)](https://github.com/nclsHart "nclsHart (1 commits)")[![pioneer32](https://avatars.githubusercontent.com/u/4023517?v=4)](https://github.com/pioneer32 "pioneer32 (1 commits)")[![pitchart](https://avatars.githubusercontent.com/u/2943883?v=4)](https://github.com/pitchart "pitchart (1 commits)")

---

Tags

specificationdoctrine

###  Code Quality

TestsBehat

### Embed Badge

![Health badge](/badges/niro-kphoen-rulerz/health.svg)

```
[![Health](https://phpackages.com/badges/niro-kphoen-rulerz/health.svg)](https://phpackages.com/packages/niro-kphoen-rulerz)
```

###  Alternatives

[kphoen/rulerz

Powerful implementation of the Specification pattern

8831.3M6](/packages/kphoen-rulerz)[happyr/doctrine-specification

Specification Pattern for your Doctrine repositories

452915.0k8](/packages/happyr-doctrine-specification)[sonata-project/doctrine-orm-admin-bundle

Integrate Doctrine ORM into the SonataAdminBundle

46117.7M155](/packages/sonata-project-doctrine-orm-admin-bundle)[portphp/portphp

Data import/export workflow

2702.9M22](/packages/portphp-portphp)[sylius/grid-bundle

Amazing grids with support of filters and custom fields integrated into Symfony.

1358.3M44](/packages/sylius-grid-bundle)[omines/datatables-bundle

Symfony DataTables Bundle with native Doctrine ORM, Elastica and MongoDB support

2851.4M6](/packages/omines-datatables-bundle)

PHPackages © 2026

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