README

Expression executor, which allows to implement domain-specific language. This lib doesn’t contain any implemented operators or functions. Its only a framework, which allows you to build your own domain-specific language for expressions, with any functions, operators and typing system.

You can define your own operator, functions and variables. For example, you want to calc/execute expressions like:

MIN(5, 10.5) + NUMBER_OF_DAY(year: "2019", month: "01", day: "20") + PI * {{VARIABLE}} + ((-2) + 2.5) * 2

In example above

• MIN and NUMBER_OF_DAY - functions
• {{VARIABLE}} - variable
• PI - syntax user-defined constant (for example, you can define TRUE, FALSE and NULL constants)
• + and * - operators
• "5", "10", "2019" - strings in double-quotes
• 5, 10.5, (-2), 2.5, 2 - int/float as is, but negative values should be wrapped in brackets

Also, it support arrays and boolean logic like:

("HELLO" IN ["HELLO", "WORLD"]) && (10 IN [2+2, 3+3, 5+5, "string here"])

where

• ["HELLO", "WORLD"] - array of strings
• [2+2, 3+3, 5+5, "string here"] - mixed array of integers and strings
• IN - operator, that check is array contain value or not
• && - logic operator "and"

Installation:

composer require xakepehok/expression-executor

Usage

In order to calc/execute expressions above you need to define those functions, operators and values

MIN():

<?php
class MinFunction implements \XAKEPEHOK\ExpressionExecutor\FunctionInterface 
{

    public function getName(): string
    {
        return 'MIN';
    }

    public function execute(array $arguments, array $context)
    {
        return min($arguments);
    }
}

NUMBER_OF_DAY():

<?php
class NumberOfDayFunction implements \XAKEPEHOK\ExpressionExecutor\FunctionInterface 
{

    public function getName(): string
    {
        return 'NUMBER_OF_DAY';
    }

    public function execute(array $arguments, array $context)
    {
        $year = $arguments['year'] ?? ($arguments[0] ?? null);
        $month = $arguments['month'] ?? ($arguments[1] ?? null);
        $day = $arguments['day'] ?? ($arguments[2] ?? null);
        
        if ($year === null || $month === null || $day === null) {
            throw new \XAKEPEHOK\ExpressionExecutor\Exceptions\FunctionException('Arguments error');
        }
        
        return date('N', strtotime("{$year}-{$month}-{$day}"));
    }
}

+ operator:

<?php
class PlusOperator implements \XAKEPEHOK\ExpressionExecutor\OperatorInterface 
{
    
    public function operator() : string
    {
        return '+';    
    }
    
    /**
    * Custom integer priority value. For example, for "+" it can be 1, for "*" it can be 2
    * @return int
    */
    public function priority() : int
    {
        return 1;
    }
    
    public function execute($leftOperand, $rightOperand, array $context)
    {
        return $leftOperand + $rightOperand;
    }    
}

* operator:

<?php
class MultiplyOperator implements \XAKEPEHOK\ExpressionExecutor\OperatorInterface 
{
    
    public function operator() : string
    {
        return '*';    
    }
    
    /**
    * Custom integer priority value. For example, for "+" it can be 1, for "*" it can be 2
    * @return int
    */
    public function priority() : int
    {
        return 2;
    }
    
    public function execute($leftOperand, $rightOperand, array $context)
    {
        return $leftOperand * $rightOperand;
    }    
}

IN operator:

<?php
class InOperator implements \XAKEPEHOK\ExpressionExecutor\OperatorInterface 
{
    
    public function operator() : string
    {
        return 'IN';    
    }
    
    /**
    * Custom integer priority value. For example, for "+" it can be 1, for "*" it can be 2
    * @return int
    */
    public function priority() : int
    {
        return 1;
    }
    
    public function execute($leftOperand, $rightOperand, array $context)
    {
        return in_array($leftOperand, $rightOperand, true);
    }    
}

&& operator:

<?php
class AndOperator implements \XAKEPEHOK\ExpressionExecutor\OperatorInterface 
{
    
    public function operator() : string
    {
        return '&&';    
    }
    
    /**
    * Custom integer priority value. For example, for "+" it can be 1, for "*" it can be 2
    * @return int
    */
    public function priority() : int
    {
        return 1;
    }
    
    public function execute($leftOperand, $rightOperand, array $context)
    {
        return $leftOperand && $rightOperand;
    }    
}

Create executor instance:

<?php
$executor = new \XAKEPEHOK\ExpressionExecutor\Executor(
    [new MinFunction(), new NumberOfDayFunction()],
    [new PlusOperator(), new MultiplyOperator(), new InOperator(), new AndOperator()],
    function ($name, array $context) {
        $vars = [
            'VARIABLE' => 10,
            'CONTEXT.VALUE' => $context['value'],
        ];
        return $vars[$name];
    },
    ['PI' => 3.14]
);

//And simply execute our expression 
$result_1 = $executor->execute('MIN(5, 10.5) + NUMBER_OF_DAY(year: "2019", month: "01", day: "20") + PI * {{VARIABLE}} + ((-2) + 2.5) * 2');

$result_2 = $executor->execute('("HELLO" IN ["HELLO", "WORLD"]) && (10 IN [2+2, 3+3, 5+5, "string here"])');

Features

• Its safe. No eval()
• Executor can return and work with any types of data. All types checking and manipulating should be implemented in your classes (functions and operators)
• String arguments support escaped double quotes, for example "My name is \"Timur\""
• Functions accept any count of arguments (you can limit in function body by exceptions)
• Functions arguments can be named NUMBER_OF_DAY(year: "2019", month: "01", day: "20") and unnamed NUMBER_OF_DAY("2019", "01", "20"), but not combined
• Function arguments can be strings, numbers, variables, constants, other functions result and any expressions
• You can pass context (any common data as array) as second param for execute() method. Context will be passed to functions, operators and variables callable
• Use brackets (2 + 2) * 2 for priority
• Use brackets for negative numbers, such as (-1), (-1.2)
• You can implement any operator, such as >, >=, <, <= and any what you want and desire

See ExecutorTest.php for more examples.

Differences from analogues

• https://symfony.com/doc/current/components/expression_language.html - great symfony component for expressions, but it is impossible to override logic of any built-in operators and also impossible use your own strict type system. Only one way to extend - define your own function
• https://github.com/NeonXP/MathExecutor - good math expressions calculator with user-defined operators and functions, but it is also impossible to use your own strict type system. For example, you can't do something like Datetime - Datetime (with type saving)