Eel
Eel stands for Embedded Expression Language and enables developers to create a Domain Specific Language.
E.g. Neos Fusion has Eel embedded to parse some parts in combination with FlowQuery.
Quickstart
The evaluation consists of two parts, the first one is the expression to evaluate. The second one is the context needed to evaluate the expression.
An expression can be something like:
'foo.bar == "Test" || foo.baz == "Test" || reverse(foo).bar == "Test"'
To enable this expression to be parsed, a context is needed to define foo.bar
, foo.baz
and
reverse()
.
Basically a context is nothing more then an array defining the parts as key value pairs. The above will need a context like:
[
'foo' => [
'bar' => 'Test1',
'baz' => 'Test2',
],
'reverse' => function ($array) {
return array_reverse($array, true);
},
]
To parse the above expression the following code can be used:
$expression = 'foo.bar == "Test" || foo.baz == "Test" || reverse(foo).bar == "Test"';
$context = new Context([
'foo' => [
'bar' => 'Test1',
'baz' => 'Test2',
],
'reverse' => function ($array) {
return array_reverse($array, true);
}
]);
$result = (new CompilingEvaluator)->evaluate($expression, $context);
In the above example $result
will be a boolean. But the result depends on the expression and can
be of any type.
Context Types
Two context types are available.
Context
will just provide everything you put into the array for the constructor.
ProtectedContext
will provide the same, except that methods are disallowed by default. You need
to explicitly allow methods:
$context = new ProtectedContext([
'String' => new \Neos\Eel\Helper\StringHelper,
]);
$context->allow('String.*');
$result = (new CompilingEvaluator)->evaluate(
'String.substr("Hello World", 6, 5)',
$context
);
In the above example, all methods for String
are allowed and therefore the result will be
"World"
.
In case a non allowed method is called, a \Neos\Eel\NotAllowedException
is thrown.
Evaluators
Two evaluator types are available.
CompilingEvaluator
will generate PHP Code for expression and cache the expressions.
InterpretedEvaluator
will not generate PHP Code and evaluate the expression every time. That’s
useful if you are using Eel outside of Flow context.
Helpers
Helpers provide convenient features like working with math, strings, arrays and dates. Each helper is implemented as a class. No helpers are available out of the box while parsing an expression. To include helpers add them to the context, e.g.
$context = new Context([
'String' => new \Neos\Eel\Helper\StringHelper,
]);
$result = (new CompilingEvaluator)->evaluate(
'String.substr("Hello World", 6, 5)',
$context
);
The package comes with some predefined helpers you can include in your context. A full, auto generated, list of helpers can be found at Neos Eel Helpers Reference.
Grammar
The full grammar can be found at the Eel repository.