oxygensuite / php-ast
A lightweight Abstract Syntax Tree (AST) implementation for PHP, enabling structured parsing, analysis, and transformation of PHP code.
Requires
- php: ^8.4
- ext-ctype: *
- ext-mbstring: *
Requires (Dev)
- laravel/pint: ^1.28
- phpunit/phpunit: ^13.0
- roave/security-advisories: dev-latest
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A lightweight formula engine for PHP built on an Abstract Syntax Tree (AST). Parse, evaluate, and transform expressions with support for variables, functions, wildcards, and operator precedence.
Requirements
- PHP 8.4+
- ext-ctype
- ext-mbstring
Installation
composer require oxygensuite/php-ast
Quick Start
use OxygenSuite\PhpAst\Formulas\FormulaEvaluator; $evaluator = new FormulaEvaluator(); $data = [ 'lines' => [ ['quantity' => 2, 'unit_price' => 10.0, 'discount' => 0], ['quantity' => 3, 'unit_price' => 15.0, 'discount' => 5], ['quantity' => 1, 'unit_price' => 8.0, 'discount' => 0], ], ]; // Variable access (dot-notation) $evaluator->evaluate('lines.0.quantity', $data); // 2 // Arithmetic $evaluator->evaluate('lines.0.quantity * lines.0.unit_price', $data); // 20.0 // Wildcards $evaluator->evaluate('SUM(lines.*.quantity)', $data); // 6 // Functions $evaluator->evaluate('MAP(lines; quantity * unit_price - discount)', $data); // [20, 40, 8]
Variables
Variables use dot-notation for nested property access. Types are preserved (string, int, float, bool, null, array).
| Syntax | Resolves to |
|---|---|
uid |
$data['uid'] |
lines.0.quantity |
$data['lines'][0]['quantity'] |
a.b.c |
$data['a']['b']['c'] |
Variables can be used directly in expressions:
$evaluator->evaluate('lines.0.quantity * lines.0.unit_price', $data); $evaluator->evaluate('(base_price + tax) * quantity', $data);
Wildcards
The * wildcard extracts values across all items in an array.
// Single-level: lines.*.quantity → PLUCK(lines; "quantity") $evaluator->evaluate('lines.*.quantity', $data); // [2, 3, 1] // Multi-level: lines.*.taxes.*.amount → extracts all tax amounts from all lines $evaluator->evaluate('SUM(lines.*.taxes.*.amount)', $data);
Operators
Listed from highest to lowest precedence:
| Precedence | Operators | Description |
|---|---|---|
| 1 | ** |
Exponentiation |
| 2 | * / % |
Multiplication, division, modulo |
| 3 | + - |
Addition, subtraction; + joins text |
| 4 | == != < > <= >= <=> |
Comparison |
| 5 | && |
Logical AND |
| 6 | || |
Logical OR |
| 7 | ?? ?: |
Null coalescing, elvis |
Parentheses override precedence: (a + b) * c.
Variables keep their values' types, so text compares and combines as text: customer.name == "ACME",
street || city. + adds numbers, including a number written as text when the other side is a number ("1" + 5 is
6), and joins text otherwise, so codes keep their digits ("001" + "12" is "00112"). &&, ||
and ?: read a value as true or false the way IF() does: text is false only when it is "", "0" or "false".
Functions
All functions use semicolons (;) as argument separators.
Aggregation
| Function | Description | Example |
|---|---|---|
SUM(values) |
Sum of numeric values | SUM(lines.*.quantity) |
AVG(values) |
Average | AVG(lines.*.unit_price) |
MIN(values) |
Minimum value | MIN(lines.*.unit_price) |
MAX(values) |
Maximum value | MAX(lines.*.quantity) |
COUNT(values) |
Number of elements, 1 for a single value, 0 for a missing one | COUNT(lines.*.quantity) |
Rounding
| Function | Description | Example |
|---|---|---|
ROUND(value; precision) |
Round to precision decimals | ROUND(10.567; 2) → 10.57 |
CEIL(value) |
Round up | CEIL(10.1) → 11 |
FLOOR(value) |
Round down | FLOOR(10.9) → 10 |
Array Manipulation
| Function | Description | Example |
|---|---|---|
PLUCK(array; "key") |
Extract column from array of objects | PLUCK(lines; "quantity") |
FLAT(array; depth) |
Flatten nested arrays (default depth: 1) | FLAT([[1,2],[3,[4,5]]]; 2) |
MAP(array; expr) |
Apply expression per item | MAP(lines; quantity * unit_price) |
FILTER(array; condition) |
Filter items by condition | FILTER(lines; unit_price > 10) |
GROUP(array; "key") |
Group items by key | GROUP(lines; "tax_category") |
SORT(array) |
Sort array | SORT(lines.*.quantity) |
JOIN(array; separator) |
Join into string | JOIN(lines.*.quantity; ",") |
CONCAT(value; …) |
Join values as text, lists item by item | CONCAT(series; "-"; number) |
TEXTJOIN(separator; value; …) |
Join the non-blank values with a separator | TEXTJOIN(" "; street; number) |
FIRST(array) |
First element | FIRST(lines) |
LAST(array) |
Last element | LAST(lines) |
LEN(text) |
Number of characters | LEN(header.invoice_number) |
Conditional
| Function | Description | Example |
|---|---|---|
IF(cond; true_val; false_val) |
Conditional | IF(quantity > 10; "bulk"; "single") |
VALUE(array; "key") |
Get value by key | VALUE(line; "quantity") |
EMPTY(value) |
Missing, blank or an empty list | EMPTY(customer.name) |
EXISTS(value) |
Not empty: zero counts as a value | EXISTS(header.series) |
Composing Functions
Functions can be nested and combined with arithmetic:
// Sum of (quantity * unit_price) per line $evaluator->evaluate('SUM(MAP(lines; quantity * unit_price))', $data); // Filter then sum $evaluator->evaluate('SUM(PLUCK(FILTER(lines; tax_category == 1); "net_amount"))', $data); // Grouped aggregation $evaluator->evaluate('GROUP(lines; "tax_category")', $data); // → [1 => [...], 2 => [...], 3 => [...]] // Arithmetic on aggregated results $evaluator->evaluate('SUM(lines.*.net_amount) + SUM(lines.*.vat_amount)', $data);
Context Providers
For injecting external values (e.g., configuration, session data) into formula evaluation:
use OxygenSuite\PhpAst\ContextProvider\ContextProvider; class MyContext implements ContextProvider { public function getContextValue(string $key): mixed { return match ($key) { 'tax_rate' => 0.24, 'currency' => 'EUR', default => null, }; } } $evaluator = new FormulaEvaluator(new MyContext()); $evaluator->evaluate('unit_price * tax_rate', $data); // uses tax_rate from context
Context values take priority over data array values. Inside MAP() and FILTER(), a field the item has comes first:
in MAP(lines; amount * tax_rate), amount is each line's even when the context has an amount too.
Wildcard Resolvers
A context provider that also implements WildcardResolver decides which items a wildcard path reads, for example the
current line of a loop over lines. It gets each wildcard path as the formula writes it, and whether a function reads
it as its list (SUM(lines.*.net_amount), COUNT(lines.*.taxes)), and returns the path to read instead, or null to
read every item:
use OxygenSuite\PhpAst\ContextProvider\ContextProvider; use OxygenSuite\PhpAst\ContextProvider\WildcardResolver; class CurrentLine implements ContextProvider, WildcardResolver { public function __construct(private int $line) {} public function getContextValue(string $key): mixed { return null; } public function resolveWildcardPath(string $path, bool $asList): ?string { // The current line's values, except where a function sums or counts all lines return $asList ? null : preg_replace('/^lines\.\*/', "lines.{$this->line}", $path); } } $evaluator = new FormulaEvaluator(new CurrentLine(2)); $evaluator->evaluate('lines.*.net_amount / SUM(lines.*.net_amount)', $data); // line 2's share of the total
A function's #[FunctionDefinition] says which argument it reads as a list (listArgument), whether only when it is
the only argument (listArgumentAlone, as for SUM, which otherwise adds up its arguments), whether its result
keeps the keys of that list (keepsKeys, as for FILTER and MAP), and whether its result is items of that list
(keepsItems, as for FILTER and SORT).
Scope Resolvers
A context provider that also implements ScopeResolver reads every name of a formula itself. It gets the name as the
formula writes it and the items of MAP() and FILTER() it is read in, innermost first, each with the path of its
list when that is a path (taxes in MAP(FILTER(taxes; amount > 0); amount)), and returns the name's value. It can so
decide which scope a name belongs to, an item, a loop of its own or the data, by a schema rather than by the keys an
item happens to have:
use OxygenSuite\PhpAst\ContextProvider\ContextProvider; use OxygenSuite\PhpAst\ContextProvider\ScopeResolver; class Scoped implements ContextProvider, ScopeResolver { public function __construct(private array $data) {} public function getContextValue(string $key): mixed { return $this->resolveName($key, []); } public function resolveName(string $path, array $items): mixed { // A line's "discount" is the line's, also on a line without one foreach ($items as ['item' => $item, 'path' => $list]) { if ($list === 'lines' && $path === 'discount') { return $item['discount'] ?? null; } } return $this->data[$path] ?? null; } }
Custom Functions
Simple Function
Implement the Formula interface:
use OxygenSuite\PhpAst\AST\ASTEvaluator; use OxygenSuite\PhpAst\Formulas\Formula; readonly class DoubleFunction implements Formula { public function execute(array $arguments, array $data, ASTEvaluator $evaluator): float|int|string|array { return ($arguments[0] ?? 0) * 2; } }
AST-Aware Function
For functions that need per-item evaluation (like MAP/FILTER), implement ASTFormula instead. It receives raw AST nodes so you can evaluate expressions against each item:
use OxygenSuite\PhpAst\AST\ASTEvaluator; use OxygenSuite\PhpAst\Formulas\ASTFormula; readonly class MyTransform implements ASTFormula { public function execute(array $astNodes, array $data, ASTEvaluator $evaluator): mixed { [$itemsNode, $callbackNode] = $astNodes; $items = $itemsNode->accept($evaluator, $data); return array_map( fn($item) => $callbackNode->accept($evaluator, $item), $items, ); } }
Caching
Parsed ASTs are automatically cached per evaluator instance (default: 1000 entries). Repeated evaluation of the same formula string skips parsing entirely.
$evaluator->getCacheStats(); // ['hits' => 42, 'misses' => 10, 'size' => 10, 'hitRate' => 0.807] $evaluator->clearCache();
Error Handling
| Scenario | Behavior |
|---|---|
| Missing variable | Returns null |
| Division by zero | Returns 0 |
| Unknown function | Throws ParseException |
| Invalid expression | Throws ParseException |
| Arithmetic on text | Throws RuntimeException |
| Recursion depth > 32 | Throws RuntimeException |
License
MIT