Download the PHP package fivelab/ruler without Composer

Russia has become a terrorist state.

Ruler

Write a filter as a single string rule and apply it to different query builders — Doctrine ORM, Elasticsearch / OpenSearch (via Elastica or the native clients) and ClickHouse — without rewriting the condition for each backend.

The same rule string produces a DQL WHERE for Doctrine, a bool query for Elasticsearch, or a WHERE clause for ClickHouse — you only change the target you pass in.

Why Ruler?

• One rule, many backends. Reuse a filter across your database and your search index.
• Safe values. Rule values are passed as parameters and never written into the query by Ruler.
• Composable. Build rules from reusable specifications (and / or, per-target overrides).
• Extensible. Add your own operators or targets through small interfaces.
• Maintained. PHP 8.2+, Doctrine ORM 2 & 3, actively developed — a drop-in idea for the unmaintained kphoen/rulerz.

Installation

Install the packages for the targets you use (they are declared as suggest):

Usage

Create a Ruler for the target(s) you need, then apply() a rule to a query object.

Doctrine ORM

Joins are detected automatically from the dotted path: category.key adds a LEFT JOIN on the category association and filters on its key field. Nested associations (variants.category.key) are supported too.

Elasticsearch / OpenSearch

For the ruflin/elastica client, pass an Elastica\Query:

For the native elasticsearch/elasticsearch or opensearch-project/opensearch-php clients, use RawSearchQuery and read the built body:

apply() only sets the query part, so size, sort, aggs, etc. are preserved. Calling it several times combines the conditions with bool.must.

ClickHouse

The ClickHouse target builds a WHERE string and its parameters for you to embed in your own SQL (placeholders use the smi2/phpclickhouse format):

Multiple targets at once

Wrap several targets in Targets and reuse one Ruler for all of them; it picks the right executor by the query object you pass:

Rule syntax

A rule is a string of conditions combined with and / or. Values are always passed as named parameters (:name); the array you pass to apply() provides them.

Operators

• Grouping: use parentheses — (a = :a or b = :b) and c > :c.
• Arithmetic (+, -, *, /) is available for the SQL targets (Doctrine ORM, ClickHouse).
• Constants: integers, floats, true, false and null may be written inline (published = true, price > 100).
• Null: field = null / field != null become IS NULL / IS NOT NULL for SQL targets and an exists check for Elasticsearch (it has no NULL).
• Nested paths: a dot builds joins (Doctrine) or a nested query (Elasticsearch). To treat a dot as part of the field name, escape it: name\.keyword — for Elasticsearch and ClickHouse only, Doctrine ORM field names cannot contain a dot.

Good to know

A few current constraints of the parser:

• Operators must be surrounded by spaces: price > :price, not price>:price.
• String and negative-number values cannot be written inline — pass them as parameters (name = :name, not name = 'John'; price > :min, not price > -5).
• Elasticsearch nested paths support a single level (variants.name).

The full reference — precedence, constants, null checks, errors and the differences between the backends — is in docs/targets.md.

Specifications

Rules can be wrapped in reusable, composable specifications and applied with applySpec():

OrX, EmptySpecification and TargetableSpecification (a single specification that carries a different rule per target, resolved with SpecificationFilter::filterByTarget()) are available too.

A composite renames the duplicated parameters of its specifications (:status, :status_1, …), so one specification can appear in it several times. The renaming does not reach across separate applySpec() calls on one query — see Duplicated names.

Extending

• Custom operators — implement OperatorsConfiguratorInterface and register handlers on the Operators collection.
• Custom targets — implement TargetInterface (or IdentifiableTargetInterface) to support another query builder.

See docs/extending.md for complete examples.

Documentation

• Rule syntax — operators, precedence, fields, parameters, constants, errors.
• Targets — what Doctrine ORM, Elasticsearch and ClickHouse build from a rule.
• Extending — custom operator handlers and custom targets.

Security

• Rule values are safe. Ruler never writes values from the parameters array into query text: the SQL targets emit placeholders that Doctrine binds (or your ClickHouse client fills in with escaped values), and Elasticsearch gets them as structured values — so they are safe from injection.
• The rule string is code, not input. Field names and operators from the rule string are interpreted and written into the query. Do not build the rule string from untrusted user input. If users drive the filtering, keep the rule template static and let them supply only parameter values, or validate field names against an allow-list.

To report a vulnerability, see SECURITY.md.

Migrating from RulerZ

kphoen/rulerz solves a similar problem but has had no release since 2018. Ruler is a maintained alternative for the Doctrine ORM and Elasticsearch use cases, with ClickHouse support added. A few differences to keep in mind when migrating:

• Ruler mutates your query object in place via apply() (RulerZ returns filtered results from filter()); you keep full control of the query builder.
• Values must be passed as named parameters — inline literals in the rule string are not supported.
• Ruler has no in-memory/array target yet; it targets query builders (Doctrine ORM, Elasticsearch, ClickHouse).

Requirements

• PHP ~8.2
• doctrine/orm ~2.10 || ~3.0 — for the Doctrine ORM target
• ruflin/elastica ~7.3 — for the Elasticsearch / OpenSearch target

Development

For easy development you can use Docker.

After the container starts, install the vendors:

Before opening a PR, please run the checks:

License

Ruler is released under the MIT License.