Skip to main content

Engine API

Qanna\ExpressionEngine\Engine is the entry point. In Laravel it's a container singleton (app(Engine::class)) and is also proxied by the Qanna\ExpressionEngine\Facades\ExpressionEngine facade — every method below is callable statically on the facade with the same signature.

Throughout, $context is array|ContextContract and defaults to [].

__construct(array $config = [])​

new Engine(config('expression-engine'));

Accepts the configuration array. Recognised keys: delimiters.open, delimiters.close, strict, cache.ast, cache.results, env_whitelist. Unknown keys are ignored; missing keys fall back to defaults.

evaluate(string $expression, $context = []): mixed​

Evaluates a raw expression (no delimiters) and returns its typed result.

$engine->evaluate('trigger.order.total > 100', $context); // → bool

resolve(mixed $value, $context = []): mixed​

If $value is a string, replaces every {{ expr }} (or your configured delimiters) in it. A string that is a single placeholder with no other text returns the raw typed value; otherwise the result is a string with each value stringified. Non-string $value is returned unchanged.

$engine->resolve('Hi {{ trigger.user.name }}', $context);      // → string
$engine->resolve('{{ trigger.order.lines }}', $context);       // → array

resolveArray(array $data, $context = []): array​

Walks $data recursively and runs resolve() on every string value. Non-string scalars pass through untouched; nested arrays are walked in place.

$engine->resolveArray([
    'to'      => '{{ trigger.user.email }}',
    'subject' => 'Welcome {{ trigger.user.name }}',
], $context);

run(array $expressions, $context = []): mixed​

Evaluates each expression in order against one shared context and returns the last one's value. Values written with set() in an earlier line are visible to later lines. See Code blocks.

$engine->run([
    'set("tax", trigger.subtotal * 0.15)',
    'trigger.subtotal + get("tax")',
], $context);

registerMethod(string $name, string $type, callable $handler): void​

Registers a chainable method for a value type (string, int, double, bool, array, Carbon\CarbonImmutable, or any). The handler receives ($value, ...$args). Overrides an existing name/type pair. See Extending the engine.

registerFunction(string $name, callable $handler): void​

Registers a global function callable as name(...). The handler receives the evaluated arguments.

availableMethods(?string $type = null): array​

All registered method names, or — with $type — the names valid for that value type (including methods registered for any). Sorted.

availableFunctions(): array​

All registered function names plus the always-available get and set. Sorted, unique.

suggestMethods(string $expression, $context = []): array​

Evaluates $expression and returns:

[
    'type'    => 'string',            // runtime type name
    'value'   => 'Ada',               // the evaluated value
    'methods' => ['upper', 'lower'],  // methods chainable onto it
]

suggestKeys(string $expression, $context = []): array​

Evaluates $expression (expected to resolve to a list of records) and returns the union of array keys across its items — the candidate current.<field> names for a filter() / map() / sort(). Returns [] if the result isn't a list of records.

See Building autocomplete for how the last three methods fit together in editor tooling.