jcubic/expression.php

Safely evaluate math, string, and boolean expressions

DESCRIPTION

Use the Expression class when you want to evaluate mathematical or boolean expressions from untrusted sources. You can define your own variables and functions, which are stored in the object.

FEATURES

• Integers and floats
• Math Expressions: * / - + %, ^, and **
• Boolean Expression: &&, ||, and !
• Comparisons: > < == != <= >=
• Strict comparison === and !==
• pi and e constants
• Regular Expressions and match operator =~
• String literals
• JSON objects and Arrays
• Square brackets operation on objects and arrays
• Bit shift operators >> <<
• Equal operator works on arrays and objects
• Functions and variables

INSTALLATION

composer require jcubic/expression

USAGE

<?

require_once(__DIR__ . "/vendor/autoload.php");
use jcubic\Expression;

$e = new Expression();
// basic evaluation:
$result = $e->evaluate('2+2');
// supports: order of operation; parentheses; negation; built-in functions
$result = $e->evaluate('-8(5/2)^2*(1-sqrt(4))-8');
// support of booleans
$result = $e->evaluate('10 < 20 || 20 > 30 && 10 == 10');
// support for strings and match (regexes can be like in php or like in javascript)
$result = $e->evaluate('"Foo,Bar" =~ /^([fo]+),(bar)$/i');
// previous call will create $0 for whole match match and $1,$2 for groups
$result = $e->evaluate('$2');
// create your own variables
$e->evaluate('a = e^(ln(pi))');
// or functions
$e->evaluate('f(x,y) = x^2 + y^2 - 2x*y + 1');
// and then use them
$result = $e->evaluate('3*f(42,a)');
// create external functions
$e->functions['foo'] = function() {
  return "foo";
};
// and use them
$result = $e->evaluate('foo()');

METHODS

• $e->evalute($expr)

Evaluates the expression and returns the result. If an error occurs, prints a warning and returns false. If $expr is a function assignment, returns true on success.

• $e->e($expr)

A synonym for $e->evaluate().

• $e->vars()

Returns an associative array of all user-defined variables and values.

• $e->funcs()

Returns an array of all user-defined functions.

PARAMETERS

• $e->suppress_errors

Set to true to turn off warnings when evaluating expressions

• $e->last_error

If the last evaluation failed, contains a string describing the error. (Useful when suppress_errors is on).

• $e->functions

Assoc array that contains functions defined externally.

• $e->variables

Assoc array that contains variables defined by user and externally.

HISTORY

This project started as a fork. Original code was created by Miles Kaufmann and published on PHPClasses.org. I've added a lot of features and bug fixes to original code, but then decided that the code is really hard to modify to add new features and fix bugs. So I decide to rewrite everything from scratch using PEG parser generator.

The original code is still available as version 1.0 on packagist and the source code you can find in legacy branch.

ACKNOWLEDGMENTS

• Logo uses:
  • icon from Clarity icon set
  • Prosto one font by Pavel Emelyanov
• The public API is taken from the original code by Miles Kaufmann

LICENSE

Copyright (c) 2024 Jakub T. Jankiewicz Released under MIT license