# The Rule Engine, in Detail > > Scope: how conditional logic is created, stored, processed, and — most importantly — > extended in the customization layer · Last reviewed: 2026-08-02 Source: CBX documentation, version 3.x (released). Canonical page: https://docs.configbox.at/docs/technical/rule_engine. Last updated 2026-08-25. --- > **Scope:** how conditional logic ("rules") is created, stored, processed, and — most importantly — > **extended in the customization layer** · **Last reviewed:** 2026-08-02 > **Naming:** this page uses the 4.0 (CB4) vocabulary — `QuestionProperty` conditions, > `questionId`, `selectedAnswer.` field paths. CBX 3.x used the legacy element vocabulary > (`ElementAttribute`, `elementId`, `selectedOption.`); the 4.0 migration rewrites stored rule > JSON automatically — the full before/after map is in > [`migration-to-cb4/element-question-rename.md`](https://docs.configbox.at/docs/migration-to-cb4/element-question-rename). All paths are relative to `docroot/components/com_configbox/`. --- ## 0. Mental model A **rule** decides a single boolean: *does this question/answer apply?* It is attached to a **question** (`#__configbox_questions.rules`) or to an **answer** (`#__configbox_answers.rules`). - For a **question**: rule true ⇒ show the question; with **negation** ⇒ hide it when true. - For an **answer**: same, for an individual option. A rule is a tree of **conditions** joined by **combinators** (`AND`/`OR`) and grouped by **brackets**, optionally wrapped in a **negation**. Each condition is an instance of a **condition type** (a PHP class). The engine turns the tree into a PHP boolean expression and `eval()`s it. The *effects* (show/hide/grey-out/auto-select/require) are not part of the rule — they're driven elsewhere by calling the rule and reacting to the boolean (see §4.5). There are 4 built-in condition types (`classes/rule_condition_types/`): `QuestionProperty`, `Calculation`, `CustomerGroup`, and the internal `Negation`. A fifth file, `CustomConditionExample.php`, is the documented template for custom types. --- ## 1. Storage — what a rule actually is A rule is a **JSON string** stored in a single text column: - `#__configbox_questions.rules` — question-level rule (`models/questions.php:581`, property `type=>'rule'`). - `#__configbox_answers.rules` — answer-level rule (`models/answers.php:508`). The column is wired up as a Kenedo property of type **`rule`** (`external/kenedo/properties/rule.php` → `KenedoPropertyRule`). That property class: - renders the human-readable rule in list cells via `ConfigboxRulesHelper::getRuleHtml(...)`, - re-maps IDs when a product is copied (`copyRule()`), and - **validates the rule before it is stored** (`check()` → `getRuleErrors()`, §6). The JSON itself is **produced entirely client-side** by the rule editor JS and written into a hidden form field; the normal Kenedo model `store()` then persists that string verbatim. So "saving a rule" is "saving a string column", with one gate in front of it: the property refuses a rule the engine could not evaluate (§6). Nothing parses the rule *for meaning* on the way in — the structure and the references are checked, the outcome is not. ### The JSON shape A rule is a JSON **array of items**. Each item is one of: | Item | Shape | |-------------|-----------------------------------------------------------------------| | condition | `{ "type": "", "operator": "==", ...data }` | | combinator | `{ "type": "combinator", "kind": "AND" }` (or `"OR"`) | | bracket | a **nested array** of items (no `type` key) | | negation | `{ "type": "negation" }` — only ever the **first** item | The `...data` of a condition are arbitrary key/values the type defines (see §5). Example (question shows only when answer 22 is chosen in question 7 **AND** the slider in question 8 is ≥ 5): ```json [ { "type": "QuestionProperty", "questionId": 7, "field": "selectedAnswer.id", "operator": "==", "value": "22" }, { "type": "combinator", "kind": "AND" }, [ { "type": "QuestionProperty", "questionId": 8, "field": "selection", "operator": ">=", "value": 5 } ] ] ``` A negated version prepends `{ "type": "negation" }` to the array. An empty rule is `''` or `[]` (meaning "always applies"). --- ## 2. Creating a rule in the backend (the editor) ### 2.1 Where the editor lives - Controller: `controllers/adminruleeditor.php` — a thin shell; its only job is to return the view. - View: `views/adminruleeditor/view.html.php` (`ConfigboxViewAdminRuleeditor`) + `tmpl/default.php`. - JS module: `assets/javascript/rule-editor.js` (loaded via `configbox/ruleEditor::initRuleEditor`, see `view.html.php:getJsInitCallsEach`). - CSS: `assets/css/rule-editor.css`. ### 2.2 How it opens On a question/answer edit form, the `rule` property renders (`properties/tmpl/rule.php`): - a hidden `input.data-field` holding the current JSON, decorated with `data-editor-url`, `data-product-id`, `data-page-id`, `data-usage-in` (`question`|`answer`); - a read-only HTML rendering of the current rule (`ConfigboxRulesHelper::getRuleHtml($rule, false)`); - buttons: Change / Delete / Copy / Paste; and an empty `.rule-editor-modal`. Clicking **Change** (handler on `.trigger-edit-rule`, `assets/javascript/properties/rule.js:91` — the rule property's own JS module, no longer `admin.js`) loads the editor view (by `data-editor-url`) into a Bootstrap modal and stores a back-reference to the originating form property via `modal.data('form-property', ...)` (`rule.js:139`). The current rule JSON is passed to the view as the `rule` request param. ### 2.3 How the editor builds its panels (server side) `ConfigboxViewAdminRuleeditor::prepareTemplateVars()` (`view.html.php:96`): 1. Reads `rule`, `productId`, `pageId`, `usageIn` from the request. 2. Renders the current rule into editable HTML: `ConfigboxRulesHelper::getRuleHtml($rule)` (§3.4). 3. Picks the heading text by context ("Show the question if…" vs "Show the answer if…") and the negated variants. 4. Enumerates **all** condition types — `ConfigboxCondition::getConditionTypeNames()` (§5.1) — and for each whose `showPanel()` is true, builds a **tab title** (`getTypeTitle()`) and a **panel** of draggable available conditions (`getConditionsPanelHtml($this)`). > Minor latent bug worth knowing: the intended tab ordering array uses plural names > (`'Calculations'`, `'CustomerGroups'`) that don't match the real type names, and the > `if ($key)` guard treats the index-0 type (`QuestionProperty`) as falsy. The net effect is the > "preferred ordering" block is largely a no-op; tabs fall back to discovery order. Harmless, but > surprising. ### 2.4 The editing surface (`tmpl/default.php`) - A `.cb-rule-area` drop zone (the rule being built) — `tmpl/default.php:29`. - `#combinator-blueprints`: draggable `AND` / `OR` spans (``). - `#condition-picker`: one tab + panel per condition type; each panel lists draggable `` blueprints. - A `#cb-editor-operator-picker-blueprint` (full = 6 operators, short = is/is-not, `tmpl/default.php:69`) shown when the user clicks a condition's operator. - A negation `` **as a direct child** of `span.item.condition`. Its value lands in `$conditionData['someKey']`. **Use camelCase for `data-data-key`.** Numbers are auto-normalized for the locale decimal symbol. - Provide `.condition-name` (what the user sees) and `.condition-operator` (`$this->getOperatorText($op)`); the operator picker is wired automatically. - Respect `$forEditing`: editable `.input` when true, read-only `.condition-value` when false. 2. **`getConditionsPanelHtml($ruleEditorView)`** — return the editor tab's panel: a `
    ` of `getConditionHtml($blueprint)` items the user drags into the rule. Each blueprint is an associative array with at least `type`, `operator`, and your data keys (see the example's `$availableConditions`). 3. **`getEvaluationResult($conditionData, $selections)`** — read your keys out of `$conditionData`, compute the truth value, return `bool`. `$selections` is `[questionId => value]`; for customer data use `ConfigboxUserHelper::getUser()`. **Cache** — this runs many times per selection change. Optionally override `getTypeTitle()` (tab label), `getOperators()` (custom operator set), `getValidationErrors()` (§6), `showPanel()`, the `contains*Id()` methods (so referenced entities can't be deleted out from under the rule), and `getCopiedConditionData()` (ID remapping on product copy). ### 5.4 Minimal example `data/customization/rule_condition_types/CustomConditionStockLevel.php`: ```php 'StockLevel', 'sku'=>'', 'operator'=>'>=', 'threshold'=>'']; return '
    • ' . $this->getConditionHtml($blueprint) . '
    '; } function getConditionHtml($conditionData, $forEditing = true) { ob_start(); ?> getOperatorText($conditionData['operator']); ?> =","threshold":5}` in the `rules` column, and the engine evaluates it on every selection change. ### 5.5 Gotchas when extending - **Class loads twice safely** (`include_once`), but a fatal/parse error in your file breaks the whole admin — develop carefully. - **Type name = class suffix**, and it must round-trip through the JSON; keep it alphanumeric. - **Performance:** `getEvaluationResult` is on the per-keystroke hot path; memoize external lookups. - **No effects in the condition** — a condition only returns true/false. To *do* something on a selection (auto-select, require, deselect), that's the configurator/consistency engine (`getInconsistencies` / `getAutoSelectItems`, `rules.php:632/1016`) plus the question's `behavior_on_activation` / `behavior_on_changes` / `behavior_on_inconsistency` settings — not the rule type. - **i18n:** title via `getTypeTitle()`/`CONDITION_TYPE_` language key; UI strings via `KText::_`. - **Other customization extension points follow the same pattern**: custom question types (`data/customization/classes/question_types` / `ConfigboxQuestion`), custom calc term types (`calc_term_types/`), and uploadable observers (admin Connectors) — the rule condition mechanism is one instance of a consistent "drop a prefixed class in `data/customization`" convention. --- ## 6. Validation on save The editor is a drag and drop surface with **no validation of its own** (`storeRule()` serializes whatever is in the drop zone), and the JSON is stored verbatim. What the engine then does with it is build a PHP boolean expression and `eval()` it (§3.3), so a rule that does not hold together is not a rule that behaves oddly — it is a `ParseError`, a thrown exception in the admin, or a question that silently never shows. `KenedoPropertyRule::check()` refuses those on the way in. It is the standard Kenedo property validation hook, so it covers **every** write: the admin form (`KenedoController::store()`) and the MCP authoring tools (`ConfigboxMcpHelper::storeData()`) both call `KenedoModel::validateData()`. Failures come back as a 422, attributed to the `rules` field under `validationIssues` — `check()` reports through the property's own error store, which `validateData()` turns into a `KenedoValidationException` carrying one issue per bad field. ### 6.1 What is checked **Structure** — each of these produces PHP that does not parse: | Rule | Evaluated code | |---|---| | two conditions with no combinator | `return ( true true );` | | leading or trailing combinator | `return ( AND true );` | | two combinators in a row | `return ( true AND OR false );` | | an empty group | `return ( true AND () );` | | nothing but a negation marker | `return (!( ));` | Also refused: a `negation` marker anywhere but the very first item of the whole rule (elsewhere it contributes nothing, so the rule means something other than what was authored); an item that is neither a condition, a group nor a combinator (the engine recurses into anything without a `type` key and makes `()` of it); and a combinator whose `kind` is not `AND`/`OR` in any case — that value is injected into the eval'ed string verbatim, so it is whitelisted rather than escaped. **References and vocabulary** — these store and evaluate without complaint, which is why nobody notices them: - a condition `type` with no class behind it — `ConfigboxCondition::getCondition()` throws on it, and `getRuleHtml()` reaches the same call, so storing one breaks every list that shows the rule; - an operator the type does not have — `getOperatorText()` throws the same way; - a `field` that is not one of `getQuestionProperties()` (rules written before the CB4 rename say `selectedOption.id` and are in exactly this state); - a question, answer or calculation that does not exist — a rule that can never be satisfied, and in the calculation's case a fatal error in the list view, since `getConditionHtml()` reads `->name` off whatever the cache hands back. Per-type checks live in the condition classes (`getValidationErrors()`, §4.2), so a custom type gets the structural and operator checks for free and can add its own. ### 6.2 What is deliberately *not* checked - **A rule that is already stored.** Both write paths seed the request from the existing record, so an untouched rule is posted back on every partial update. Validating it would let a rule written by an older editor block edits to fields that have nothing to do with it. `check()` compares against the stored column first and only judges a rule that this save actually changes. The consequence: **broken rules already in the wild surface only when someone edits them** — finding them all is a separate audit, not this gate. - **Whether the rule can ever be true.** A condition on a question of *another product* is well-formed and unsatisfiable; the MCP encoder rejects that on its own surface (`ConfigboxMcpRulesHelper`), the property does not. - **Anything in the browser.** The editor still lets the user build a broken rule and closes its modal; the message arrives when the form is saved. ### 6.3 Two rules for anything added here - **Never throw.** Validation reaches into condition classes, third-party ones included. Every call into one is wrapped — a fatal error during validation is worse than the broken rule it was meant to catch. - **Never read through the cache.** `ConfigboxCacheHelper` is APCu-backed for the web process and file-backed on CLI, so an authoring tool would get a stale answer and refuse a rule that is perfectly valid on a freshly seeded catalog. The existence checks query the tables directly. Covered by `tests/specs/backend/rule-validation.spec.ts`.