resist/matex

PHP Mathematical expression parser and evaluator

1.1.1 2023-03-22 16:54 UTC

Requires

• php: >=8.1

Requires (Dev)

• phpunit/phpunit: ^9.5

MIT

README

PHP Mathematical expression parser and evaluator

This repository is a fork of original Matex:

https://github.com/madorin/matex
Dorin Marcoci - [e-mail] - https://www.marcodor.com

Installation

composer require resist/matex

Changelog

Changes:

• Added Composer and Packagist support
• Added new namespace: resist\Matex\Evaluator
• Added proper negative number support: thanks to https://github.com/blazer82/matex/
• Added custom MatexException
• Bumped required PHP version to 7.4
• Added unit tests
• Reformatted code

Original README and MANUAL below:

Matex

Matex is a PHP Mathematical expression parser and evaluator library.
It allows safe execution and calculation of the arbitrary expressions.

Installation

Matex can be installed using Composer package manager or manually connected to your project.

Composer way

Make sure the Composer is installed and your project is properly configured to use Composer tool.
Execute in console the following code in order to connect Matex library:

$ composer require madorin/matex

It will adjust the composer.json file of your project by adding Matex library as an requrement. Check if Composer's /vendor/autoload.php is included/required in your project.

Manual way

Download the Matex package and extract it in your project libraries folder. If you use a custom php autoloader, the classes located in /src/ folder are PSR-4 compatible, so may adjust the autoloader configuration and/or move the folder according to your rules.

For complete manual linking way, include the src/Evaluator.php in your project:

<?php
    require 'path/to/matex/src/Evaluator.php';

Features

• Fast evaluation
• Compact codebase
• Operators: + - * / ^ %
• Brackets, nested, unlimited levels
• Variables: predefined or estimated dynamically
• Functions: predefined or connected dynamically
• String arguments in functions, like field("name")
• String operations, currently concatenation is supported

Examples

Basic:

$evaluator = new \Matex\Evaluator();
echo $evaluator->execute('1 + 2');

String concatenation:

$evaluator = new \Matex\Evaluator();
echo $evaluator->execute('"String" + " " + "concatenation"');

Variables:

$evaluator = new \Matex\Evaluator();
$evaluator->variables = [
    'a' => 1,
    'b' => 2
    ];
echo $evaluator->execute('a + b');

Dynamic variables:

public function doVariable($name, &$value) {
    switch ($name) {
        case 'b':
            $value = 2;
            break;
    }
}

$evaluator = new \Matex\Evaluator();
$evaluator->variables = [
    'a' => 1
    ];
$evaluator->onVariable = [$this, 'doVariable'];
echo $evaluator->execute('a + b');

Functions:

static function sum($arguments) {
    $result = 0;
    foreach ($arguments as $argument)
        $result += $argument;
    return $result;
}

$evaluator = new \Matex\Evaluator();
$evaluator->functions = [
    'sum' => ['ref' => '\\Space\\Class::sum', 'arc' => null]
];
echo $evaluator->execute('sum(1, 2, 3)');

Extravaganza:

/*
Dynamic variable resolver
Invoked when the variable is not found in the cache
Returns the value by name
*/
public function doVariable($name, &$value) {
    switch ($name) {
        case 'zen':
            // Here may be a database request, or a function call
            $value = 999;
            break;
        case 'hit':
            $value = 666;
            break;
    }
}

/*
Dynamic function resolver
Invoked when the function is not found in the cache
Returns an associative array array with:
    ref - Function reference
    arc - Expected argument count
*/
public function doFunction($name, &$value) {
    switch ($name) {
        case 'cos':
            // Map to a system function
            $value = ['ref' => 'cos', 'arc' => 1];
            break;
        case 'minadd':
            // Map to a public object instance function
            $value = ['ref' => [$this, 'minAdd'], 'arc' => 2];
            break;
    }
}

/*
Custom functions, may be a
    - Built-in function
    - Global defined function
    - Static class function
    - Object instance function
*/
static function sum($arguments) {
    $result = 0;
    foreach ($arguments as $argument)
        $result += $argument;
    return $result;
}
// Just a sample custom function
function minAdd($a, $b) {
    $r = $a < 2 ? 2 : $a;
    return $r + $b;
}

// Let's do some calculations
$evaluator = new \Matex\Evaluator();
$evaluator->variables = [
    'a' => 1,
    'bet' => -10.59,
    'pi' => 3.141592653589
    ];
$evaluator->onVariable = [$this, 'doVariable'];
$evaluator->functions = [
    'sin' => ['ref' => 'sin', 'arc' => 1],
    'max' => ['ref' => 'max', 'arc' => null],
    'sum' => ['ref' => '\\Space\\Class::sum', 'arc' => null]
    ];
$evaluator->onFunction = [$this, 'doFunction'];
echo $evaluator->execute('a + MinAdd(PI * sin(zen), cos(-1.7 / pi)) / bet ^ ((A + 2) * 2) + sum(5, 4, max(6, hit))');

Author

Dorin Marcoci - [e-mail] - https://www.marcodor.com

License

Matex is distributed under MIT license. See LICENSE.md for more details.